Next.js 15 to 16 Migration Playbook: Cache Components 2026

The Next.js 15 to 16 migration is one of the more substantive upgrades in the App Router era — Cache Components reshape how caching is reasoned about, the use cache directive replaces unstable_cache, and middleware.ts is renamed to proxy.ts. The good news: most of the mechanical work is codemoddable, and a phased rollout lands cleanly in one to three weeks for a mid-size app.

What changed and why it matters. Next.js 16 ships five distinct axes of change at once: a new caching model (Cache Components plus Partial Prerendering as the default), a new directive ( use cache) with companion helpers (cacheLife, cacheTag, updateTag), a deprecation path for unstable_cache, a literal file rename from middleware.ts to proxy.ts, and runtime tuning (Turbopack as the default, Node.js and Bun runtimes available on routing middleware). Any one of these would be a quarter of work to adopt deliberately; together they require a plan.

What this playbook covers: a phase-by-phase rollout from the audit step through codemod application, opt-in cache adoption, and post-migration cleanup. Concrete codemods Vercel ships and what they cover, what they leave untouched, the patterns that bite in production (over-broad cache invalidation is the number one culprit), and the right rollback procedure for the first 24 hours after the bump lands.

Next.js 16 is not a single-feature release. The major-version bump consolidates a year of work across five distinct axes, each of which has its own migration implications. Reading the release as a checklist of five independent migrations rather than one monolithic upgrade is the right mental model.

The five axes, in the order they typically affect a migration: the caching model shifts from the legacy fetch-cache plus revalidate approach to Cache Components — Partial Prerendering on by default, the use cache directive for explicit cached functions, and a tag-based invalidation model via cacheTag and updateTag. The unstable_cache primitive enters a deprecation window with a codemod path to use cache. The middleware file is renamed to proxy.ts at the filesystem level — same primitive, new name. Vercel ships codemods covering roughly 80 to 90 percent of the mechanical changes. Turbopack is the default bundler, and routing middleware (proxy.ts) gains Node.js and Bun runtime options alongside the existing Edge runtime.

The release adopts a clear philosophy: caching becomes explicit and composable rather than implicit and global. The Next.js 13–15 era cached fetch calls by default and required opt-outs via { cache: 'no-store' } or revalidate: 0; Next.js 16 inverts the default — nothing is cached unless you mark it with use cache. That single change clarifies many years of confusion about why a particular page was or was not cached, and is the right move architecturally, but it does mean every existing app needs an audit of where caching was being relied on implicitly.

Cache Components is the umbrella name for the new caching model. The four pieces work together. Partial Prerendering (PPR) splits a page into a static shell (prerendered at build) and dynamic holes (rendered at request and streamed in). The use cache directive marks a function as cacheable — its return value is cached on first invocation and reused on subsequent calls that match the same arguments. cacheLife configures the TTL profile for a cached function — short, default, long, days, weeks. cacheTag attaches one or more tags to a cache entry; updateTag (called from a Server Action or a Route Handler) invalidates every entry carrying that tag.

The four primitives, in plain English

The shift from revalidate (a time-based interval) to cacheLife profiles is a quiet but important simplification. Instead of every cache call site picking a number of seconds, you choose from a small set of named profiles (typically seconds, minutes, hours, days, weeks, and max), and the profile encodes both a stale time and a revalidate-on-error budget. Centralizing the profiles in configuration means a single change tightens or loosens caching across the entire app — useful during incident response and for consistency across a team.

Tag-based invalidation via cacheTag and updateTag is the right model for any app with a non-trivial data graph. The old revalidatePath/revalidateTag from 14 and 15 are still available but the new pair are the recommended primitives — they participate in PPR cleanly and have better telemetry in the Vercel dashboard. The discipline rule for tags is covered in Section 07: scope tags as narrowly as the entity that actually changes, never broader.

One implementation note worth pinning down: use cache can be applied at three scopes — file, function, or component. File-level "use cache" at the top marks every export as cached; function-level wraps an individual async function; component-level wraps a Server Component. Start at function scope when migrating; the granular scope is easier to reason about and easier to roll back if a particular cache key misbehaves. File-scope and component-scope are sensible consolidations once a page is stable.

unstable_cache was the workaround that many teams adopted in Next.js 14 and 15 to memoize non-fetch data calls — database queries, third-party SDK responses, computed values. In 16, the primitive is formally deprecated and the migration path is the use cache directive. The codemod @next/codemod next-async-request-api rewrites the majority of call sites mechanically; what remains is the manual review.

What the codemod handles cleanly

The straightforward case — a top-level async function wrapped in unstable_cache with a static key array — converts to an async function with "use cache" at the top, with the cache key options translated to cacheLife and cacheTag calls inside the function body. The codemod recognizes the common patterns and produces clean output.

What needs manual review

Three patterns the codemod surfaces as TODO comments rather than converting in place. First, closures over request-scoped data — if the cached function references a value from the surrounding scope that varies per request (a header, a cookie, a user ID), the conversion is not mechanical; you either pass that value as an argument so the cache key includes it, or move the dynamic read outside the cached function. Second, conditional caching — code that wraps unstable_cache only when a condition holds needs to be re-expressed; use cache is always-on once applied. Third, nested caching — a cached function calling another cached function works under use cache but the cache-key derivation may need adjustment.

For teams with a large surface area of cached calls — anything past a hundred call sites — the practical workflow is: run the codemod, audit every TODO comment in a single pass, and ship the converted code behind a feature flag if the cache behavior is critical. The use cache directive is supported in 15.5 onward as well, so the rewrites can land on 15 first and run there in production before the major-version bump — strongly recommended for risk-averse rollouts.

The simplest of the five axes — and the one teams overthink the most. middleware.ts is renamed to proxy.ts. Same primitive, same matcher API, same request and response shapes. The rename is a clarification: "middleware" had become an overloaded term across the web ecosystem, and the file's actual behavior — intercepting requests before they hit the cache layer — is more accurately described as a proxy. Vercel's docs and the Next.js changelog both note that the rename is not changing the model, only the name.

What the codemod does

The next-proxy-rename codemod moves the file from middleware.ts to proxy.ts at the project root and updates the export name if you were exporting middleware as a named export. The matcher config is unchanged. Any imports of the old file (rare, since middleware files are not typically imported) are also updated.

What changed beyond the name

One material change: proxy.ts supports the Node.js and Bun runtimes in addition to Edge. Most existing middleware files are Edge-runtime by default and should stay there for latency reasons. The Node.js runtime is useful when the file needs to call a library that does not run on Edge (a heavyweight SDK, a database client, a crypto library with native bindings) — previously these calls had to happen in a route handler downstream of middleware, adding latency. With the Node.js runtime on proxy.ts, the call can happen at the proxy layer.

Practical rule of thumb: if your existing middleware does authentication, A/B-test cohort assignment, or geographic rewrites, leave it on Edge after the rename. If your existing middleware was working around an Edge-runtime limitation by calling out to a separate route handler, consider switching to the Node.js runtime on proxy.ts to collapse the indirection.

Vercel ships codemods through the @next/codemod CLI. Running npx @next/codemod@latest opens an interactive picker; running npx @next/codemod@latest upgrade latest attempts the full sweep. The codemods cover the mechanical changes — file renames, API signature shifts, import path updates, and the unstable_cache migration — and leave the conceptual decisions (which functions to cache, how to scope tags, what to put behind PPR) to the team.

The matrix below summarizes what each codemod covers

Run the codemods in the order shown — earlier codemods produce input the later codemods expect. Skipping the order is the single most common reason migrations stall on the first day.

What the codemods deliberately do not cover: any decision that requires understanding the data model. Cache-tag scope, cache-life profile selection, which functions deserve use cache at all, where to apply PPR — these all require thinking about how data flows through the app. The codemods clear the mechanical debt so the team can focus on the substantive decisions; they do not replace the substantive decisions.

The other thing worth knowing: the codemods are not perfect. Always run them on a clean working tree, review the diff before merging, and add a regression-test pass before pushing to production. For larger apps, run the codemods on a long-lived branch and let the team poke at it for a day before merging — the first hour after a codemod sweep is when most subtle issues surface.

The four-phase rollout below is the shape that consistently lands cleanly across mid-size apps. Skipping a phase or compressing two into one is the most common cause of post-merge incidents — each phase has a distinct purpose and a distinct rollback model.

The discipline that holds the whole rollout together: do not skip Phase 1. The audit step is where you discover the call site depending on an implicit cache that nobody documented, the route that quietly expects revalidate: 0, the third-party integration that breaks when its responses get cached. Skipping the audit and discovering these in production is the most expensive way to find them.

Measurement is the discipline that holds Phase 3 together. The Vercel dashboard exposes cache-hit ratios per route after Cache Components are enabled — watch this number on the first page you migrate before rolling to the second. A page sitting at 95% cache hits is doing what you want; a page at 30% has a cache-key problem that will compound if you replicate the pattern across other pages. The first page is the one where you tune the model; subsequent pages should be roll-outs of a known-good pattern, not re-discoveries.

For teams with multiple environments, the right cadence is: Phase 2 lands in staging for a week, Phase 3 rolls out one page at a time to production with a 24-hour soak between pages, Phase 4 lands the week after the last Phase 3 page goes green. For teams with a single environment, double every duration. For teams with no preview infrastructure, set one up before starting — running a migration of this scope without a preview environment is a recoverable mistake the first time and a non-recoverable one the second.

If your team has not migrated to App Router yet, that work precedes this playbook. Our web development engagements include App Router migrations and Next.js major-version bumps as a packaged offering — the Pages Router to App Router move is a larger lift than this 15 to 16 step, but the playbook shape is similar.

Every team that ships Cache Components into production trips one of the four pitfalls below in the first month. Pre-reading them is cheaper than rediscovering them. Each one has a clean fix; the risk is not knowing to look for it.

One pattern worth internalizing for Pitfall 03 specifically: any request-scoped value you reference inside a use cache function must be passed as an explicit argument, not closed over from the surrounding scope. The cache key is derived from the function arguments; closures are invisible to the key. The codemod for unstable_cache emits TODO comments for this case but cannot fix it automatically — the manual review is mandatory.

For teams who want to go deeper on the stack-level decisions before starting a migration like this, the Next.js 16 AI chatbot tutorial covers the streaming and route-handler patterns that interact with the cache model; the Vercel AI SDK v5 to v6 migration playbook walks through a parallel-shaped upgrade if your app also depends on the AI SDK.

A final note on observability. Once Cache Components is enabled, the Vercel dashboard exposes per-route cache-hit ratios, average cache-entry age, and tag-invalidation counts. Add an alert when cache-hit ratio drops below the expected band for a given route — a 95% steady-state route dropping to 40% is almost always a cache-key bug or an over-eager updateTag call site, and catching it within an hour is the difference between a five-minute fix and a half-day incident. The same dashboard surfaces tag-invalidation rates, which is the right place to look when Pitfall 01 is suspected.