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`.