/nextjs-16

name: nextjs-16
description: Use when building Next.js 16 apps — Turbopack, App Router, Cache Components, proxy.ts, v15 migration. Not for stack scaffolding (nextjs-stack) or React SPA (react-expert).
versions:
  nextjs: 16
  react: 19
user-invocable: true
references: references/installation.md, references/upgrade.md, references/project-structure.md, references/typescript.md, references/styling.md, references/app-router.md, references/routing-advanced.md, references/navigation.md, references/route-segment-config.md, references/pages-router.md, references/server-components.md, references/directives.md, references/react-19.md, references/rendering.md, references/streaming.md, references/runtime.md, references/data-fetching.md, references/forms.md, references/static-generation.md, references/cookies-headers.md, references/caching.md, references/cache-components.md, references/turbopack.md, references/react-compiler.md, references/dynamic-imports.md, references/loading-patterns.md, references/error-handling.md, references/proxy.md, references/middleware-migration.md, references/api-routes.md, references/security.md, references/metadata.md, references/metadata-files.md, references/images.md, references/fonts.md, references/scripts.md, references/third-party.md, references/analytics.md, references/instrumentation.md, references/devtools-mcp.md, references/environment.md, references/deployment.md, references/testing.md, references/config-advanced.md
related-skills: nextjs-i18n, better-auth, tailwindcss-core, solid-nextjs, nextjs-stack, nextjs-server-components, nextjs-tanstack-query

<objective> Covers Next.js 16 core framework mechanics (current stable: 16.4): Turbopack (default bundler; Webpack remains available via the `--webpack` opt-out flag), the App Router (nested layouts, parallel/intercepting routes, file conventions like page.tsx/layout.tsx/loading.tsx/error.tsx/not-found.tsx), Cache Components (`use cache`, `cacheTag()`, `cacheLife()`, `revalidateTag()`), `proxy.ts` (full Node.js runtime, replaces Edge middleware), and React 19 integration (View Transitions, new hooks).

Documents the critical v15→v16 breaking changes: proxy.ts replacing middleware.ts, Turbopack as the default for `next dev`/`next build`, `cacheComponents` replacing the removed `experimental.ppr` flag, required React 19, and async `params`/`searchParams`. This skill covers core framework APIs only — for assembling a full production stack (Prisma, Better Auth, shadcn/ui, Zustand together) use nextjs-stack instead; for a pure React SPA without `next.config.*` use the react-expert skills instead. </objective>

Next.js 16 Expert

Production-ready React framework with Server Components, streaming, and Turbopack.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - Analyze existing routes, components, and patterns 2. **fuse-ai-pilot:research-expert** - Verify latest Next.js 16 docs via Context7/Exa 3. **mcp__context7__query-docs** - Check breaking changes v15→v16

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

Overview

When to Use

• Building new React applications with server-first architecture
• Need Server Components for optimal performance and SEO
• Implementing streaming and progressive rendering
• Migrating from Next.js 14/15 to version 16
• Using proxy.ts for route protection (replaces middleware)
• Leveraging Turbopack for faster development builds

Why Next.js 16

| Feature | Benefit | |---------|---------| | Turbopack default | 2-5x faster builds, 10x faster HMR; Webpack only via `--webpack` opt-out | | Cache Components | Explicit caching with `use cache` directive | | proxy.ts | Full Node.js runtime, replaces Edge middleware | | React Compiler | Automatic memoization, no manual useMemo/useCallback | | React 19 | View Transitions, useEffectEvent, Activity component | | App Router | Nested layouts, parallel routes, intercepting routes |

---

Breaking Changes from v15

Critical Migration Points

1. **proxy.ts replaces middleware.ts** - Full Node.js runtime, not Edge 2. **Turbopack by default** - `next dev`/`next build` use Turbopack; a custom `webpack` config fails the build unless you migrate it or opt out with `--webpack` 3. **`cacheComponents` + `use cache`** - Replaces `experimental.ppr` / `experimental_ppr` (removed); PPR is the default behavior under `cacheComponents` 4. **React 19 required** - New hooks and View Transitions API 5. **Async params/searchParams** - Must await dynamic route params

Cache Components: the recommended model (16.4+)

Since 16.4 Cache Components is recommended for **every** Next.js app, `create-next-app` enables it by default, and it becomes the default in Next.js 17. Data fetching is dynamic by default; opt in to caching per component/function with `'use cache'`. Use the two-flag setup (`cacheComponents: true` + `partialPrefetching: true`, set `partialPrefetching` explicitly) for new code and when touching caching/data fetching; see [cache-components.md](references/cache-components.md). Existing apps: `npx next@canary upgrade --agent=latest` (see [upgrade.md](references/upgrade.md)).

New in 16.1 – 16.4 (see [upgrade.md](references/upgrade.md))

• **16.1** - Turbopack filesystem cache on by default for `next dev`; `next dev --inspect`
• **16.2** - `transitionTypes` prop on `<Link>`, `next start --inspect`, Adapters API stable
• **16.3** - `catchError` + `retry()` error recovery (stable), `next/root-params`, `import.meta.glob`, Turbopack build cache on by default, opt-in Instant Navigations (`partialPrefetching` with `cacheComponents`)
• **16.4** - Cache Components recommended for all apps (on by default in `create-next-app`, default in Next.js 17); `ensureStatic` route segment config; `navigation()` / `prefetch()` from `next/cache`; `next upgrade --agent` + `experimental.agentUpgrade`; React 19.3 (stable View