Next.js + TypeScript Rules

1# Next.js + TypeScript Cursor Rules2 3You are an expert Next.js 14 App Router developer working in a strict TypeScript4codebase. These rules apply to every suggestion you make in this project.5 6## App Router7- App Router only — never suggest code in the pages/ directory8- Server Components are the default; add 'use client' ONLY when a component needs event handlers, browser APIs, or React state9- When you add 'use client', put it at the TOP of the file and keep the client boundary small — push state down, not up10- Colocate loading.tsx, error.tsx, not-found.tsx next to the route they belong to11- Use route groups (folder) to organize files without affecting URL paths12- Use generateStaticParams for known dynamic routes to pre-render at build time13 14## TypeScript15- strict: true is assumed; do not weaken it16- noUncheckedIndexedAccess: true — guard every array / record access17- Never use any — use unknown and narrow with type guards18- Prefer type over interface except when you need declaration merging19- Name component props as ComponentNameProps20- Type Server Action signatures explicitly — never rely on inference for public API21- Type every function parameter and return value22- No @ts-ignore; use @ts-expect-error with a comment explaining the expected error23 24## Components25- One exported component per file26- Props interface / type at the top of the file, named ComponentNameProps27- Default to function components; no classes28- Server Components are async and return JSX directly29- Keep files under 200 lines — extract once you exceed that30 31## Data32- Server Actions ('use server') for mutations — not API routes, unless you need a public HTTP endpoint33- Zod for all input validation, reused on client and server34- Fetches on the server use the Next.js fetch with { next: { tags: ['tag'] } }35- revalidateTag for targeted invalidation; revalidatePath only when tags do not fit36- Never fetch from a client component on first render — fetch in a Server Component and pass data down37 38## File Structure39- app/ for routes (layout, page, loading, error, route handlers)40- components/ for reusable UI (one export per file)41- components/ui/ for shadcn primitives42- lib/ for pure logic, DB clients, server-only utilities43- lib/validations/ for Zod schemas44- types/ for shared ambient types45 46## Styling47- Tailwind CSS only; no CSS modules unless integrating legacy48- shadcn/ui for primitives (Button, Dialog, Form, Input, Select)49- Combine classes with the cn() helper from lib/utils50- No inline style except for truly dynamic values51- Avoid className strings longer than ~120 characters — extract into a variant52 53## Performance54- next/image with explicit width and height for every non-decorative image55- next/font for custom fonts56- dynamic() with ssr: false only for truly client-only libraries57- Stream slow children behind Suspense with a meaningful fallback58 59## Error Handling60- Every route has an error.tsx boundary61- Server Actions return { ok: true, data } | { ok: false, error: { code, message } }62- Never leak stack traces to the client63- Log errors with a correlation id in production