1---2name: nextjs-app-router3description: Next.js App Router expert guidance. Use when building, debugging, or architecting Next.js applications — routing, Server Components, Server Actions, layouts, data fetching, rendering strategies, metadata, image/font optimization, error handling, and hydration debugging. Triggers on tasks involving Next.js pages, app directory structure, RSC boundaries, or App Router migration.4license: MIT5---67# Next.js App Router Best Practices89Comprehensive reference for building Next.js applications with the App Router. Contains 20 reference docs covering architecture, patterns, and common pitfalls.1011## When to Apply1213Reference these guidelines when:14- Building or modifying Next.js App Router pages and layouts15- Choosing between Server and Client Components16- Implementing data fetching or caching strategies17- Debugging hydration errors or RSC boundary issues18- Configuring metadata, images, fonts, or scripts19- Migrating from Pages Router to App Router20- Setting up error handling or parallel routes2122## Reference Docs2324### Project Structure2526| Reference | What it covers |27|-----------|---------------|28| [file-conventions.md](references/file-conventions.md) | Special files, route segments, dynamic/catch-all/group routes, parallel and intercepting routes |29| [app-router-files.md](references/app-router-files.md) | App Router file hierarchy and conventions |30| [directives.md](references/directives.md) | `'use client'`, `'use server'`, `'use cache'` directives |3132### Components and Rendering3334| Reference | What it covers |35|-----------|---------------|36| [rsc-boundaries.md](references/rsc-boundaries.md) | Server/Client Component boundaries, invalid patterns, serialization rules |37| [suspense-boundaries.md](references/suspense-boundaries.md) | Suspense placement, CSR bailout with `useSearchParams`/`usePathname` |38| [hydration-error.md](references/hydration-error.md) | Common hydration error causes and fixes |39| [parallel-routes.md](references/parallel-routes.md) | Modal patterns, `@slot` interceptors, `default.tsx` fallbacks |4041### Data and Fetching4243| Reference | What it covers |44|-----------|---------------|45| [data-patterns.md](references/data-patterns.md) | Server Components vs Server Actions vs Route Handlers, avoiding waterfalls |46| [async-patterns.md](references/async-patterns.md) | Next.js 15+ async `params`, `searchParams`, `cookies()`, `headers()` |47| [route-handlers.md](references/route-handlers.md) | `route.ts` basics, GET/POST handlers, when to use vs Server Actions |48| [functions.md](references/functions.md) | Navigation hooks, server functions, generate functions |4950### Optimization5152| Reference | What it covers |53|-----------|---------------|54| [bundling.md](references/bundling.md) | Server-incompatible packages, CSS imports, ESM/CJS, bundle analysis |55| [image.md](references/image.md) | `next/image`, remote config, responsive sizes, blur placeholders, LCP priority |56| [font.md](references/font.md) | `next/font` setup, Google/local fonts, Tailwind integration |57| [scripts.md](references/scripts.md) | `next/script` strategies, inline scripts, Google Analytics |58| [metadata.md](references/metadata.md) | Static/dynamic metadata, `generateMetadata`, OG images with `next/og` |59| [runtime-selection.md](references/runtime-selection.md) | Node.js vs Edge runtime selection |6061### Error Handling and Debugging6263| Reference | What it covers |64|-----------|---------------|65| [error-handling.md](references/error-handling.md) | `error.tsx`, `global-error.tsx`, `not-found.tsx`, `redirect`, `unstable_rethrow` |66| [debug-tricks.md](references/debug-tricks.md) | MCP endpoint for AI debugging, `--debug-build-paths` |6768### Deployment6970| Reference | What it covers |71|-----------|---------------|72| [self-hosting.md](references/self-hosting.md) | `output: 'standalone'` for Docker, cache handlers, multi-instance ISR |7374## Boundaries7576- Not for React performance optimization patterns — use `vercel-react-best-practices` instead77- Not for component composition/architecture — use `vercel-composition-patterns` instead78- Not for Vercel deployment or CLI — use `vercel-deploy` instead79- Not for React Native80- Reference docs are point-in-time snapshots; check official docs for breaking changes8182## Verification8384- Server Components do not import `useState`, `useEffect`, or other client hooks without `'use client'`85- `params` and `searchParams` are awaited in Next.js 15+ page/layout components86- `cookies()` and `headers()` are awaited in server code87- Error boundaries exist at appropriate route segment levels88- Metadata uses `generateMetadata` for dynamic values, not `next/head`8990## Sibling skills9192Vercel/React reference layer — App Router-focused. Sibling references at different axes:9394- `vercel-react-best-practices` — perf optimization (waterfalls, server-component data shaping). Pair with this skill on perf-sensitive routes.95- `vercel-composition-patterns` — component composition patterns. Orthogonal axis.96- `vercel-deploy` / `vercel-preview-logs` — runtime side.
davisbuilds