Version history: Next.js
v1
scan: pass2026-08-11 — Ingested from sourceInitial version.
v2
currentscan: pass2026-11-02 — Currency pass 2026-11-01: removed duplicated and filler bullets; added Next.js 15+ async params/cookies/headers, uncached-by-default fetch with revalidate/tags, route segment config, Server Actions with useActionState and Zod, next/image and next/font guidance. Frontmatter description unquoted, globs made valid YAML.---- description: "Next.js with TypeScript and Tailwind UI best practices" - globs: **/*.tsx, **/*.ts, src/**/*.ts, src/**/*.tsx+ description: Next.js App Router conventions with TypeScript, Server Components, Server Actions, and Zod validation. + globs: "**/*.{ts,tsx}" alwaysApply: false --- # Next.js Best Practices ## Project Structure - Use the App Router directory structure- - Place components in `app` directory for route-specific components+ - Place route-specific components next to the route in `app` - Place shared components in `components` directory - Place utilities and helpers in `lib` directory - Use lowercase with dashes for directories (e.g., `components/auth-wizard`) ## Components - Use Server Components by default- - Mark client components explicitly with 'use client' - - Wrap client components in Suspense with fallback - - Use dynamic loading for non-critical components - - Implement proper error boundaries+ - Mark client components explicitly with `'use client'` and keep them at the leaves of the tree + - Wrap slow or data-dependent subtrees in `Suspense` with a fallback + - Use `next/dynamic` for heavy, non-critical client components + - Add `error.tsx` and `loading.tsx` per route segment instead of ad-hoc error boundaries - Place static content and interfaces at file end - ## Performance - - Optimize images: Use WebP format, size data, lazy loading - - Minimize use of 'useEffect' and 'setState' - - Favor Server Components (RSC) where possible - - Use dynamic loading for non-critical components - - Implement proper caching strategies - ## Data Fetching- - Use Server Components for data fetching when possible - - Implement proper error handling for data fetching - - Use appropriate caching strategies - - Handle loading and error states appropriately+ - Fetch data in Server Components with `async`/`await`; avoid `useEffect` for initial data + - In Next.js 15+, `params`, `searchParams`, `cookies()`, `headers()`, and `draftMode()` are async: `const { id } = await params` + - Fetches are uncached by default in Next.js 15+; opt in with `fetch(url, { next: { revalidate: 3600, tags: ['posts'] } })` or `'use cache'` + - Set route segment config (`export const dynamic`, `export const revalidate`) deliberately, not by copy-paste + - Use `revalidatePath` / `revalidateTag` after mutations instead of refetching on the client + ## Server Actions + - Put mutations in Server Actions (`'use server'`) called from forms or `useActionState` + - Validate every action input with Zod on the server; never trust client-provided IDs or roles + - Return typed results (`{ ok: true, data } | { ok: false, errors }`) rather than throwing for expected failures + - Show pending state with `useFormStatus` or `useActionState` + + ## Performance + - Use `next/image` for images (explicit `width`/`height` or `fill`, `sizes` for responsive layouts, `priority` for LCP) + - Use `next/font` to self-host fonts and avoid layout shift + - Minimize `useEffect` and client state; favor Server Components where possible + - Keep third-party scripts out of the critical path with `next/script` + ## Routing- - Use the App Router conventions - - Implement proper loading and error states for routes - - Use dynamic routes appropriately - - Handle parallel routes when needed+ - Use the App Router conventions (`page.tsx`, `layout.tsx`, `template.tsx`, `route.ts`) + - Implement loading and error states for routes + - Use dynamic routes appropriately and `generateStaticParams` for known paths + - Handle parallel and intercepting routes when needed ## Forms and Validation- - Use Zod for form validation - - Implement proper server-side validation - - Handle form errors appropriately+ - Use Zod schemas shared between client and server + - Validate on the server even when the client already validated + - Surface field errors from the action result - Show loading states during form submission ## State Management - Minimize client-side state - Use React Context sparingly- - Prefer server state when possible - - Implement proper loading states+ - Prefer server state (URL, cookies, database) when possible + - Keep loading and empty states explicit