nextjs-docs

name	nextjs-docs
description	Next.js 16 App Router reference — routing, layouts, Server/Client Components, Cache Components (`use cache`), Server Actions, Route Handlers, `proxy.ts` (formerly middleware), styling, images, fonts, config, deployment. Use when building, reviewing, or debugging Next.js App Router code.

Next.js 16 App Router

Condensed reference for agent-assisted Next.js work. Targets v16+ — covers the renames and new APIs that break assumptions from earlier versions.

v16 deltas that matter

• middleware.ts → proxy.ts. Same runtime, same matcher. Functionality unchanged. See references/proxy.md.
• Cache Components is the caching model: opt in with cacheComponents: true, use 'use cache' + cacheLife + cacheTag. The old per-fetch { cache, next: { revalidate, tags } } model is now called "Previous Model". See references/caching.md.
• updateTag (Server Actions, immediate expiry, for read-your-own-writes) vs revalidateTag (actions + route handlers, stale-while-revalidate). See references/revalidation.md.
• refresh() from next/cache refreshes the router after a mutation without revalidating tags.
• error.js receives unstable_retry instead of reset. unstable_catchError wraps arbitrary subtrees. See references/error-handling.md.
• params and searchParams are Promises — must be awaited.
• Route prop helpers are global: PageProps<'/blog/[slug]'>, LayoutProps<'/dashboard'>, RouteContext<'/users/[id]'>. Generated by next dev/next build/next typegen. No imports.
• Partial Prerendering (PPR) is the default rendering behavior under Cache Components.

When to read what

Follow links inline; don't preload everything. Each file is self-contained.

Topic	File
File-system routing, layouts, pages, dynamic segments, linking, navigation	references/routing.md
Server vs Client Components, composition, server-only	references/server-client-components.md
Fetching data, streaming, Suspense, parallel/sequential, use	references/data-fetching.md
Server Actions, forms, useActionState, optimistic updates	references/data-mutation.md
Cache Components, use cache, cacheLife, cacheTag, PPR	references/caching.md
revalidateTag, updateTag, revalidatePath, refresh	references/revalidation.md
error.js, global-error, notFound, unstable_catchError	references/error-handling.md
Tailwind, CSS Modules, global CSS, CSS-in-JS	references/styling.md
<Image>, <next/font>, public/	references/assets.md
route.ts, BFF patterns, webhooks, CORS, content negotiation	references/route-handlers.md
proxy.ts (middleware), matchers	references/proxy.md
next.config.ts, TypeScript, src/	references/config.md
Forms, CSP, data security, env vars	references/security-and-forms.md
Lazy loading, bundling, memory, preserving UI state, public pages, view transitions, scripts	references/performance.md
Deploying, self-hosting, static exports, production checklist	references/deployment.md
Rendering philosophy (mental model)	references/rendering-philosophy.md

Default stack assumptions

• Bun as runtime, TypeScript, App Router, Cache Components enabled.
• When scaffolding, prefer next.config.ts, typed routes, src/ layout.
• Tailwind for most styling; CSS Modules for scoped exceptions.
• Data: server-side fetching in Server Components via ORM/SDK; SWR/React Query only when client-side fetching is actually needed.
• Mutations: Server Actions with useActionState for pending/error state.

Non-obvious gotchas

• async Server Component → fetch directly. Don't call your own Route Handler — it's an extra HTTP hop. Route Handlers are for clients and third parties.
• Client Components can receive props from Server Components only if the props are serializable. Functions/classes are blocked by default.
• Adding cookies()/headers()/searchParams/params to a component forces dynamic rendering for that subtree. Wrap in <Suspense> if you want the rest of the page to prerender.
• loading.js at a segment only covers the page, not uncached access in a sibling layout. Put layout-level dynamic access behind its own <Suspense>.
• CSP with nonces forces dynamic rendering on every page. Use SRI or a no-nonce policy if static/PPR is needed.
• Static export (output: 'export') disables: proxy, server actions, cookies, rewrites/redirects/headers config, image optimization default loader, dynamic route handlers, ISR, draft mode, intercepting routes.
• Self-hosting with multiple instances: set NEXT_SERVER_ACTIONS_ENCRYPTION_KEY, deploymentId, and a shared cache handler with refreshTags for tag coordination.