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