next-cache-components-adoption

Enable Cache Components in Next.js apps and resolve blocking routes to a passing build.

Updated Aug 15, 2025
One-click install
npx skills add https://github.com/yehezkieldio/topaz --skill next-cache-components-adoption-yehezkieldio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: next-cache-components-adoption
Source: https://github.com/yehezkieldio/topaz/tree/main/.agents/skills/next-cache-components-adoption
Command: npx skills add https://github.com/yehezkieldio/topaz --skill next-cache-components-adoption-yehezkieldio

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Adopting Next.js Cache Components floods a project with blocking-prerender and instant-validation errors, and developers struggle to sequence the migration, choose between opting routes out with export const instant = false versus fixing them in place, and verify that routes actually stream correctly at runtime. ## Core Features & Use Cases - Guided adoption strategies: Choose between an incremental path (run the cache-components-instant-false codemod to opt every route out, ship a passing build, then adopt feature-by-feature) or a direct path (fix blocking routes as the build surfaces them). - Systematic blocker resolution: Diagnose and fix the three blocker classes — request-time reads (cookies(), headers(), await params), sync-IO calls (Date.now(), Math.random()), and "use cache" files reading request data — using the docs page linked from each error. - Runtime verification loop: Verify each fix with next dev plus a browser (via the next-dev-loop skill), not just a passing build, confirming static shells render and <Suspense> fallbacks resolve. - Use Case: A team upgrades to Next.js 16.3, flips cacheComponents: true, and faces dozens of build errors; this skill walks them route-by-route to a clean build with partial prerendering. ## Quick Start Ask the AI to enable Cache Components in your Next.js app and work through the resulting blocking-route errors one feature at a time.

Frequently Asked Questions about next-cache-components-adoption

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I enable Cache Components in a Next.js app?

Set `cacheComponents: true` in next.config, then resolve the blocking routes the build surfaces. You can run the `cache-components-instant-false` codemod to opt every page and layout out first, or fix routes directly as errors appear.

How do I fix blocking-prerender errors in Next.js?

Blocking-prerender errors come from request-time reads like `cookies()`, `headers()`, or `await params` outside a `<Suspense>` boundary. Push the read into a Suspense-wrapped child component, and follow the docs page linked in each error for the exact recipe.

What does export const instant = false do in Next.js?

It marks a route as allowed to block, clearing it in both dev and build validation. On a layout it covers the whole subtree during builds, but client navigations still validate each descendant segment individually.

Does Cache Components work with the Next.js Pages Router?

No, Cache Components is an App Router feature; the flag does nothing for `pages/` routes. A hybrid app works fine — the flag affects only `app/` routes while `pages/` routes are unaffected.

Why does my Next.js build still fail after adding instant = false?

Sync-IO calls like `new Date()`, `Date.now()`, `Math.random()`, or `crypto.randomUUID()` at module or render time fail the build even with the opt-out. Locate them via the build error's file and line, then apply the fix from the linked docs page.

What Next.js version is required for Cache Components?

Next.js 16.3 or later is required, since that release adds top-level `cacheComponents`, `export const instant`, dev-overlay validation warnings, and the codemod. Upgrade first with `npx @next/codemod@latest upgrade latest`.