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.
Comprehensive reference for building Next.js applications with the App Router. Contains 20 reference docs covering architecture, patterns, and common pitfalls.
Reference these guidelines when:
| Reference | What it covers |
|---|---|
| file-conventions.md |
| Special files, route segments, dynamic/catch-all/group routes, parallel and intercepting routes |
| app-router-files.md | App Router file hierarchy and conventions |
| directives.md | 'use client', 'use server', 'use cache' directives |
| Reference | What it covers |
|---|---|
| rsc-boundaries.md | Server/Client Component boundaries, invalid patterns, serialization rules |
| suspense-boundaries.md | Suspense placement, CSR bailout with useSearchParams/usePathname |
| hydration-error.md | Common hydration error causes and fixes |
| parallel-routes.md | Modal patterns, @slot interceptors, default.tsx fallbacks |
| Reference | What it covers |
|---|---|
| data-patterns.md | Server Components vs Server Actions vs Route Handlers, avoiding waterfalls |
| async-patterns.md | Next.js 15+ async params, searchParams, cookies(), headers() |
| route-handlers.md | route.ts basics, GET/POST handlers, when to use vs Server Actions |
| functions.md | Navigation hooks, server functions, generate functions |
| Reference | What it covers |
|---|---|
| bundling.md | Server-incompatible packages, CSS imports, ESM/CJS, bundle analysis |
| image.md | next/image, remote config, responsive sizes, blur placeholders, LCP priority |
| font.md | next/font setup, Google/local fonts, Tailwind integration |
| scripts.md | next/script strategies, inline scripts, Google Analytics |
| metadata.md | Static/dynamic metadata, generateMetadata, OG images with next/og |
| runtime-selection.md | Node.js vs Edge runtime selection |
| Reference | What it covers |
|---|---|
| error-handling.md | error.tsx, global-error.tsx, not-found.tsx, redirect, unstable_rethrow |
| debug-tricks.md | MCP endpoint for AI debugging, --debug-build-paths |
| Reference | What it covers |
|---|---|
| self-hosting.md | output: 'standalone' for Docker, cache handlers, multi-instance ISR |
vercel-react-best-practices insteadvercel-composition-patterns insteadvercel-deploy insteadvercel-react-native-skills insteaduseState, useEffect, or other client hooks without 'use client'params and searchParams are awaited in Next.js 15+ page/layout componentscookies() and headers() are awaited in server codegenerateMetadata for dynamic values, not next/head