Skill: next-v16

Next.js 16 App Router (GA October 2025). Prefer the version-matched docs in node_modules/next/dist/docs/ over training data. Codemods: npx @next/codemod@canary upgrade latest, middleware-to-proxy, next-async-request-api.

Scope

• Applies to: Next.js 16 App Router — Turbopack, Cache Components vs previous cache model, proxy.ts, async request APIs, Server Components, Server Actions, streaming, metadata, client islands
• Does NOT cover: Pages Router, generic React 19 (see vercel-react-v1), non-Next server rendering

Assumptions

• Next.js 16.x, React 19.2 App Router, Node.js 20.9+, TypeScript 5.1+
• Two cache models exist. Detect cacheComponents in next.config before choosing APIs
• fetch is not cached by default in either model. Opt in explicitly

Principles

• Read node_modules/next/dist/docs/ for this installed version before generating Next APIs
• Cache is opt-in. Declare intent on every server fetch
• Network boundary is proxy.ts (Node.js). Auth gates, rewrites, redirects, header mutation
• Request APIs are async: await cookies(), await headers(), await draftMode(), await params, await searchParams
• Turbopack is the default bundler. --webpack is an opt-out, not the 16 idiom
• Prefer Server Components. Push 'use client' to interactive leaves
• When the user asks to audit or modernize Next code, follow references/_review-algorithm.md

Constraints

MUST

• await params, searchParams, cookies(), headers(), draftMode()
• Call revalidateTag(tag, profile) with a cacheLife profile ('max' | 'hours' | 'days' | inline { expire }). One-arg form is deprecated
• Use updateTag(tag) from Server Actions when the user must see the write immediately (read-your-writes). Use revalidateTag(tag, 'max') for stale-while-revalidate
• Export proxy from proxy.ts (named or default). Runtime is nodejs and cannot be set to Edge
• Before adding 'use cache', cacheLife, or cacheTag, confirm cacheComponents: true

SHOULD

• Enable Cache Components only as an explicit migration: cacheComponents: true, then replace segment configs dynamic / revalidate / fetchCache with 'use cache' + cacheLife. Guide: Migrating to Cache Components
• If the app was not adopting experimental.dynamicIO / experimental.useCache / experimental.ppr, remove those flags. Do not set cacheComponents: true as a rename — it can fail the build for uncached data outside Suspense
• Without Cache Components, cache with cache: 'force-cache', next: { revalidate, tags }, or unstable_cache. Guide: Caching without Cache Components
• Keep a config.matcher on proxy.ts that excludes /_next/static, /_next/image, and public assets
• Use next/image remotePatterns (not deprecated images.domains). Use next/image, not next/legacy/image
• Generate sitemaps/robots from app/sitemap.ts and app/robots.ts
• Import cacheLife / cacheTag from next/cache (stable). Do not use unstable_cacheLife / unstable_cacheTag
• Rename skipMiddlewareUrlNormalize to skipProxyUrlNormalize

AVOID

• Generating 'use cache' in an app that has not set cacheComponents: true (directive is a Cache Components feature)
• Flipping cacheComponents: true because experimental.dynamicIO / experimental.useCache / experimental.ppr were present. Enabling the flag is a programming-model migration
• middleware.ts for new code. Keep it only if Edge runtime is still required; it is deprecated
• Sync params / cookies() / headers() (removed, not warned)
• next lint (removed). Lint with ESLint or Biome
• experimental.ppr, experimental.dynamicIO, experimental.useCache, export const experimental_ppr (removed)
• experimental.turbopack (moved to top-level turbopack)
• experimental.turbo.persistentCaching — that is not the Next 16 API. Filesystem cache is experimental.turbopackFileSystemCacheForDev / experimental.turbopackFileSystemCacheForBuild (on by default)
• next dev --turbopack / next build --turbopack as the 16 idiom. Turbopack is already default; --webpack is the opt-out
• Custom webpack in config while running default next build (fails). Migrate to Turbopack or pass --webpack
• Treating 'max' on revalidateTag as “read-your-writes”. That is SWR; use updateTag in Server Actions
• Claiming Server Actions must replace every Route Handler. Route Handlers remain correct for cookies, webhooks, OAuth callbacks, and proxying an external API

Interactions

• React 19 concurrent UI: vercel-react-v1
• Client data after hydration: tanstack-query-v5
• Forms that stay on the Next server: workflow/nextjs-form

Two cache models (do not mix)

Config	What to generate
cacheComponents unset / false	Previous model. fetch uncached unless cache: 'force-cache' or next.revalidate. Segment configs dynamic, revalidate, fetchCache still work. unstable_cache for non-fetch. Do not emit 'use cache'
cacheComponents: true	Cache Components. Dynamic by default. Cache with 'use cache' + cacheLife / cacheTag. Segment configs dynamic / revalidate / fetchCache error. PPR is the default behavior. Fetches inside a 'use cache' scope are cached

'use cache' requires cacheComponents: true (use cache). Enabling the flag is a migration, not an automatic Next 16 default (cacheComponents).

Invalidation (both models, Next 16 signatures):

• revalidateTag(tag, 'max') — stale-while-revalidate; works in Server Actions and Route Handlers
• updateTag(tag) — expire and read fresh in the same request; Server Actions only
• refresh() — refresh uncached data only; Server Actions only
• revalidatePath — unchanged

Next.js 16 idioms (do not generate Next 15)

• proxy.ts + export function proxy (Node) — not middleware.ts unless Edge is required
• Turbopack default — next dev / next build with no --turbopack. Opt out: --webpack
• await params / await searchParams / await cookies()
• revalidateTag(tag, profile) — not revalidateTag(tag)
• reactCompiler: true is stable and opt-in (not default)
• turbopack: { ... } at the Next config root — not experimental.turbopack
• Parallel route slots need default.js (build fails without it)

How to review or refactor

When the user asks to review, refactor, modernize, or audit Next code, follow references/_review-algorithm.md. Do not improvise.

1. Pick Mode A (≤~20 files) or Mode B (whole tree)
2. Detect cache model from next.config before Category 2
3. Category-major sweep with a scope declaration, per-category progress lines, and a coverage table
4. Category 9 last (dedup / consolidate / delete / demote 'use client')

Rule categories

1. Build & Bundle — CRITICAL — barrels, optimizePackageImports, serverExternalPackages, Turbopack, next/dynamic
2. Caching — CRITICAL — fetch intent, segment config or 'use cache' (model-dependent), revalidateTag+profile, revalidatePath, React cache()
3. Server Components — HIGH — parallel fetch, Suspense, colocation, preload, no client initial fetch
4. Routing — HIGH — parallel/intercepting routes, prefetch, proxy.ts, notFound()
5. Server Actions — MEDIUM-HIGH — forms, useFormStatus, action results, optimistic UI, revalidation. Skip when mutations already go to an external API
6. Streaming — MEDIUM — Suspense, loading.tsx on routes that await, error.tsx, matching skeletons
7. Metadata — MEDIUM — generateMetadata, sitemap.ts, robots.ts, opengraph-image.tsx
8. Client islands — LOW-MEDIUM — 'use client' leaf, children slot, hydration, next/script
9. Hygiene — CROSS-CUTTING — dedup fetchers, consolidate routes, dead code, boundary audit, name drift

Full rule list: AGENTS.md. Rule files: references/.

References

• Next.js 16 blog
• Upgrade to 16
• Caching (Cache Components)
• Caching without Cache Components
• Migrating to Cache Components
• use cache
• proxy.ts
• middleware → proxy