next-cache-components-adoption
Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the `cacheComponents` flag, work through a flood of blocking-prerender / instant validation errors, run the `cache-components-instant-false` codemod, or decide between opting routes out with `export const instant = false` and fixing them in place.
vercel · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add vercel/next.js --skill next-cache-components-adoption技能说明
name: next-cache-components-adoption
description: >
Turn on Cache Components in a Next.js app and resolve the blocking routes it
surfaces. Use when the user wants to enable, adopt, or migrate to Cache
Components, flip the cacheComponents flag, work through a flood of
blocking-prerender / instant validation errors, run the
cache-components-instant-false codemod, or decide between opting routes out
with export const instant = false and fixing them in place.
next-cache-components-adoption
Enable Cache Components on an app and walk it to a passing build. This skill sequences the work; per-error recipes live in the dev overlay fix cards and the build's terminal output. The migrating to Cache Components guide is the canonical reference for the concepts and per-API recipes this skill applies — consult it whenever the skill steps reference a pattern ("use cache", cacheLife, <Suspense> placement, etc.) and you want the full explanation.
requires
-
App Router project. Cache Components is an App Router feature;
cacheComponents: truedoes nothing forpages/routes. If the project has apages/orsrc/pages/tree but noapp/orsrc/app/tree, stop and tell the user — Pages → App migration is its own project, not part of this skill. A hybrid app (bothpages/andapp/) is fine: the flag affects theapp/routes;pages/routes are unaffected and don't need opt-outs. -
A resolved app directory. Locate
next.config.{js,ts,mjs,cjs}first: that's the project root, and an agent invoked from a subdirectory would otherwise test forapp/against the wrongcwdand find nothing. Look forapp/andsrc/app/under it, and treat every command and glob in this skill as relative to whichever one exists. If both exist, Next.js buildsapp/and never looks atsrc/app/, so its routes are shadowed and unbuilt — tell the user that and ask which tree to migrate instead of picking one. -
A runnable app. The whole loop verifies against
next devand a browser, so the app has to boot. If it reads a database or required env at import (e.g. anenv.tsthat throws on a missingDATABASE_URL), confirm it actually starts — with the real environment, or local data you stand up — before step 1. Adoption can't be verified against an app that won't run. -
Next.js 16.3 or later. That release is where the pieces this skill relies on land: top-level
cacheComponents,export const instant, the dev-overlay instant-navigation validation warnings, and thecache-components-instant-falsecodemod. Ifnext --versionreports below 16.3, upgrade first:npx @next/codemod@latest upgrade latestto apply the version-to-version codemods.- Read the relevant version upgrade guide (e.g. Version 16) for what the codemod doesn't cover.
-
No incompatible config keys.
cacheComponents: trueerrors on any file that still exportsdynamic,revalidate, orfetchCache. Inventory these exports before running the codemod, then follow the migration guide's per-key sections. The guide is the source of truth for translating each value. Thecache-components-instant-falsecodemod does not remove these configs. -
experimental.dynamicIOis fatal. It was renamed to top-levelcacheComponentsand the old key now aborts before any build can run — remove it (or replace withcacheComponents: true) first.experimental.useCacheis still accepted as a deprecated alias; redundant oncecacheComponents: trueis set, so remove it for clarity.
notes
-
No passing baseline before the flag. If the app already uses
"use cache", the pre-flag build errors withplease enable the feature flag cacheComponents. Enabling the flag is the first thing you do (in Incremental, before the codemod; in Direct, before fixing routes) — not a thing to do after getting a passing build. Note this in your starting summary so it doesn't read as a regression. -
Existing caches can stay. Follow the migration guide's
fetchandunstable_cachesections. Do not rewrite them solely to enable Cache Components. -
Offline docs. Guide links have offline copies under
node_modules/next/dist/docs/(bundled since Next.js 16.2), with the directory layout numbered for ordering (e.g.node_modules/next/dist/docs/01-app/02-guides/migrating-to-cache-components.md). If you can't predict the numbered prefix,find node_modules/next/dist/docs -name '<slug>.md'resolves it. The/docs/messages/*error pages are not bundled. -
Older versions without bundled docs. Suggest
npx @next/codemod@latest agents-mdto the user before starting: it downloads a version-matched copy to.next-docs/and writes an index intoAGENTS.md. It touches files in their repo, so ask first and run it only if they want it.
the shape of the work
There's one loop: walk the route tree top-down, one feature at a time, adopting each route against next dev + a browser. The build is a final check for each feature, not the working surface.
The choice in step 1 is whether to opt every route out of validation first or fix routes as you go. Either way the loop is the same:
- With a quiet pre-step (Incremental). Run the codemod, fix what it can't, and fully migrate routes that previously required static rendering. Other routes keep their opt-outs for follow-up PRs.
- Without (Direct). Enable
cacheComponentsand start the loop on whatever the build flags first. Same loop, but every fix sits on one branch until adoption is complete.
In both, the per-route success bar is the same: dev loop reports no errors AND next build passes. Check in with the use