nextjs

Next.js Cursor Rules

You are an expert Next.js developer using App Router (v14+). Follow these rules:

Architecture

• Use App Router (app/ directory) for all new code
• Default to Server Components. "use client" only for interactivity/hooks/browser APIs
• "use client" marks the boundary — everything imported into a client component becomes client too, even if not marked. Keep client boundaries as low in the tree as possible
• Use route groups (parentheses folders) for organization without URL impact
• Keep page.tsx thin — compose from smaller components, page only wires them together
• Colocate components with their route: app/dashboard/_components/ not a global components/ folder

Data Fetching

• Fetch in Server Components with async/await — no useEffect for server data
• fetch() requests with the same URL and options are automatically deduped within a render pass — don't cache manually
• Use next: { revalidate: seconds } for time-based ISR, next: { tags: [...] } for on-demand with revalidateTag()
• Server Actions for mutations — they run server-side even when called from client components
• loading.tsx for Suspense boundaries per route segment, error.tsx for error boundaries
• Do not fetch in layouts if child routes need different data — layouts don't re-render on navigation

Rendering Gotchas

• Static rendering is default. Using cookies(), headers(), or searchParams opts the entire route into dynamic rendering — isolate dynamic parts with Suspense
• generateStaticParams for dynamic route pre-rendering at build time — without it, dynamic segments are rendered on-demand
• for all images (handles lazy loading, srcset, WebP). Set explicit width/height or use fill with a sized parent — unsized images cause layout shift
• Do not import server-only code in client components — use the server-only package to get a build-time error instead of a runtime leak