Migrate Next.js to Cache Components Before v17
Résumé
Pixel shares a hands-on guide to migrating an existing Next.js App Router app to Cache Components before they become the default in Next.js 17. It covers upgrading to 16.4.5 or later, enabling cacheComponents, using a codemod, handling request-dependent content with Suspense, and converting routes incrementally.
DEV Community
Migrating an existing Next.js app to Cache Components before Next.js 17
With Next.js 16.4 (October 2026), the Next.js team started recommending Cache Components for every app. New projects from create-next-app have it switched on, and the release notes say it will become the default in Next.js 17. If you have an existing App Router app, that gives you a choice: migrate now at your own pace, or do it under pressure during a major upgrade. This post walks through the migration by hand, in the order that keeps your app building the whole time. Short version: enable cacheComponents, run the codemod that opts every route out of validation, fix the few things that can't be deferred, then convert one route at a time. Nothing is cached any more unless you write use cache. Patch to 16.4.5 first. Last checked: 15 November 2026, against the Next.js 16.4 documentation. What actually changes In the older App Router model, caching was mostly implicit and set per route: export const dynamic, export const revalidate, fetchCache, and cache options on fetch. With Cache Components the rule flips: Nothing is cached unless you mark it with the 'use cache' directive. You mark the function or component that should be cached, instead of setting a route-wide config. Anything that needs the request (cookies, headers, search params) goes inside a boundary, so the rest of the page can be prerendered as a static shell and the request-specific part streams in. The Next.js team describes use cache as a component-level version of the Cache-Control header. Before you start Be on Next.js 16. Cache Components needs it. Coming from 15 or older, do the version upgrade first. Install 16.4.5 or later. The November 2026 security release fixed several cache-disclosure bugs in Cache Components. Details in my write-up of that release. Decide who drives. There's an official agent skill that does this migration feature by feature (npx skills add vercel/next.js --skill next-cache-components-adoption), and next upgrade --agent gives a coding agent version-specific guidance. Even if you use them, read on: you're the one reviewing the pull requests. The migration, step by step Step 1: turn it on // next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
cacheComponents: true,
partialPrefetching: true,
};
export default nextConfig;
The 16.4 release notes treat Partial Prefetching as part of the model, so enable both. If you previously used experimental.dynamicIO or experimental.useCache, cacheComponents replaces them. Your build will now fail on any route segment that still exports dynamic, revalidate or fetchCache. That's expected. The table in the next section tells you what to do with each. Step 2: opt every route out of validation In development, Next.js now checks whether each route can render instantly and reports what blocks it. On an existing app that's a lot of reports at once. One codemod defers them all: npx @next/codemod@canary cache-components-instant-false ./app
It adds export const instant = false to every page, layout and default file. Use ./src/app if your project has a src folder. A wrong path reports "0 ok" rather than failing, so check the file count it prints. instant = false means "this segment is allowed to block". It doesn't force the route to be dynamic. Step 3: fix what can't be deferred Synchronous, non-deterministic calls during prerender fail the build whether a route is opted out or not: new Date() and Date.now() Math.random() crypto.randomUUID() Move each one so it runs at request time: put the component that needs it inside and call connection() before it, or move it into a Client Component. Step 4: convert one route at a time Remove instant = false from a route, open it in development and read the dev overlay. Each insight names the component and offers one of two fixes: Cache it: add 'use cache' to the component or data function. Stream it: wrap it in . Repeat until no route opts out. One thing that's easy to miss: insights don't appear i...

Powered by Readybot.io