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: true does nothing for pages/ routes. If the project has a pages/ or src/pages/ tree but no app/ or src/app/ tree, stop and tell the user — Pages → App migration is its own project, not part of this skill. A hybrid app (both pages/ and app/) is fine: the flag affects the app/ 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 for app/ against the wrong cwd and find nothing. Look for app/ and src/app/ under it, and treat every command and glob in this skill as relative to whichever one exists. If both exist, Next.js builds app/ and never looks at src/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 dev and a browser, so the app has to boot. If it reads a database or required env at import (e.g. an env.ts that throws on a missing DATABASE_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 the cache-components-instant-false codemod. If next --version reports below 16.3, upgrade first:

  • npx @next/codemod@latest upgrade latest to 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: true errors on any file that still exports dynamic, revalidate, or fetchCache. 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. The cache-components-instant-false codemod does not remove these configs.

• experimental.dynamicIO is fatal. It was renamed to top-level cacheComponents and the old key now aborts before any build can run — remove it (or replace with cacheComponents: true) first. experimental.useCache is still accepted as a deprecated alias; redundant once cacheComponents: true is set, so remove it for clarity.