nextjs

Next.js 16 App Router Best Practices

Comprehensive Next.js 16 App Router guide for AI agents. Contains 45 rules across 9 categories, prioritized by impact from critical (build optimization, caching strategy) through to cross-cutting codebase hygiene (dedup, dead routes, boundary coherence). Reflects Next.js 16 changes: 'use cache' directive replacing implicit caching, revalidateTag(tag, cacheLife) requirement, proxy.ts replacing middleware.ts, Turbopack persistent caching, App Router conventions.

Rule files describe pattern shapes (not API names) and open with a "Shapes to recognize" section listing 2–4 syntactic disguises the same break can wear. Selected high-value rules (those whose disguises are most common in practice — 'use cache', parallel-fetching, dynamic-imports, server-action-forms, client-boundary, server-vs-client-fetching) include an extra concrete "In disguise" incorrect/correct example pair to teach pattern detection beyond the grep-friendly cases.

When to Apply

• Writing new Next.js 16 App Router code
• Auditing or modernizing a Next.js codebase — single file, PR, or whole repo (see references/_review-algorithm.md)
• Migrating from Next.js 15 to 16 (implicit caching → 'use cache', middleware.ts → proxy.ts, revalidateTag single-arg → with cacheLife)
• Configuring caching strategies with 'use cache', unstable_cache, revalidateTag, revalidatePath
• Implementing Server Components and parallel/colocated data fetching
• Setting up parallel routes, intercepting routes, prefetching, proxy.ts
• Creating Server Actions for form handling and mutations
• Tuning 'use client' boundaries to minimize client bundle
• Finding codebase-level issues that single-file rules can't see: duplicated server fetchers, near-duplicate routes/layouts, dead routes, 'use client' propagation across the route tree, prop-shape drift (see Category 9)

How to Review or Refactor a Codebase

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

Four non-negotiables from that doc:

1. Two modes — never refuse a whole-repo audit. Pick Mode A (scoped, ≤~20 files) or Mode B (whole-tree: inventory pass + targeted sweeps + full Category 9).
2. Judgment over grep. Each rule names a pattern shape, not a syntactic marker. Read each rule's Shapes to recognize section before sweeping — grep finds the easy violations and misses the high-value ones (a layout marked 'use client' for one button; TanStack Query fetching initial page data; a route handler doing the work of a Server Action; a hand-rolled cache layer mimicking 'use cache'; sequential fetches hidden across parent/child Server Components).
3. Category-major, not file-major — with forcing functions. Sweep one category at a time across all in-scope files in priority order (CRITICAL → … → CROSS-CUTTING). The algorithm requires a scope declaration, per-category progress lines, and a final coverage table (category × file/bucket, cells ∈ {clean, N findings, n/a}). A missing category in the output is immediately visible.
4. Codebase-level findings come from Category 9. Single-file rules can't tell you "these two routes should be one" or "this server action is dead." Category 9 (Codebase Hygiene) sweeps the full inventory at the end and produces remove / dedup / reuse / consolidate findings.

Single-file ad-hoc questions ("is this caching strategy right?") can go straight to the relevant rule. The algorithm exists for the multi-file and whole-repo cases.

Rule Categories

Quick Reference

Critical patterns — get these right first:

• Add 'use cache' to Server Components/functions whose results should be cached (Next.js 16 dropped implicit fetch caching)
• Call revalidateTag(tag, cacheLife) with a profile — never the one-arg API
• Configure optimizePackageImports for icon/utility libraries with flat-export surfaces
• Don't disable Turbopack persistent caching
• Wrap <form action={serverAction}> instead of POST-to-/api/...

Next.js 16 idioms (do NOT generate Next.js 15 patterns):

• proxy.ts (Node runtime) — not middleware.ts (Edge)
• Explicit 'use cache' — not implicit fetch caching
• revalidateTag(tag, cacheLife) — not single-arg revalidateTag(tag)
• Server Action + useActionState — not client fetch + useState
• app/sitemap.ts — not hand-maintained public/sitemap.xml

Common single-file mistakes — avoid these anti-patterns:

• Sequential await for independent data (use Promise.all or preload)
• useEffect + fetch in a Client Component for initial page data
• 'use client' at the layout level for one interactive button
• Missing revalidatePath/revalidateTag after a mutating Server Action
• Skeletons that don't match content dimensions (CLS hit)

Codebase-level patterns — surface these in Category 9 sweeps:

• 2+ Server Components hitting the same upstream with drifting cache policies — extract to a shared cached fetcher
• 2+ near-duplicate routes/layouts that should be one with a variant or dynamic segment — consolidate
• Routes / route handlers / Server Actions with no inbound traffic for 90+ days — delete (after analytics check)
• 'use client' propagating up the route tree because of one interactive leaf — demote layouts/parents to Server Components, leave a client island
• Same concept under different route-param/search-param/prop names — converge on a canonical name (watch out for SEO redirects)

Table of Contents

1. Build & Bundle Optimization — CRITICAL
   • 1.1 Import from the source module, not from a barrel index.ts — CRITICAL (2-10x faster dev startup)
   • 1.2 Declare package-flat-export libraries in optimizePackageImports — CRITICAL (200-800ms faster imports, 50-80% smaller bundles)
   • 1.3 Mark Node packages with native bindings as serverExternalPackages — HIGH
   • 1.4 Don't disable Turbopack's persistent caching — CRITICAL (5-10x faster cold starts)
   • 1.5 Split heavy components into separately loaded chunks — CRITICAL (30-70% smaller initial bundle)
2. Caching Strategy — CRITICAL
   • 2.1 Make every server fetch declare its caching intent — HIGH
   • 2.2 Declare route-level caching via segment-config exports — MEDIUM-HIGH
   • 2.3 Mark cacheable Server Components/functions explicitly with — CRITICAL

References

1. Next.js Documentation
2. Next.js 16 Release Notes
3. React Documentation
4. Vercel Engineering Blog

Related Skills

• For React 19 fundamentals (concurrent rendering, hooks, components), see react skill
• For client-side form handling, see react-hook-form skill
• For client data caching with TanStack Query, see tanstack-query skill

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md