Version history: Next.js

v1

scan: pass2026-08-11 — Ingested from source

Initial 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