next-cache-components-optimizer

Diagnoses and refactors Next.js cacheComponents routes to grow static shells and speed up navigation.

Updated Jun 27, 2026

Search Tags:#suspense #next.js #performance optimization #navigation #use cache #cachecomponents #static shell

Ready to run

npx skills add https://github.com/rachmadideni/ai-staff-assistant --skill next-cache-components-optimizer-rachmadideni

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: next-cache-components-optimizer
Source: https://github.com/rachmadideni/ai-staff-assistant/tree/main/.agents/skills/next-cache-components-optimizer
Command: npx skills add https://github.com/rachmadideni/ai-staff-assistant --skill next-cache-components-optimizer-rachmadideni

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Next.js apps with `cacheComponents: true` often ship slow first paints and sluggish in-app navigation because dynamic I/O blocks the static shell. This Skill diagnoses which Suspense boundaries actually block rendering and applies targeted refactors so more content renders statically. ## Core Features & Use Cases - Page-render loop: Ranks Suspense fallback areas on a shell-only render of a single route, then grows the static shell by pushing I/O down into wrapped children or adding `'use cache'` with a `cacheLife` profile. - Navigation loop: Captures a destination route's suspended boundaries after a client-side `pushstate`, filters out SSR-only client-hook blockers, and applies private caching plus runtime prefetch for cookie-derived data. - Use Case: A user complains that clicking from a dashboard to a detail page holds the old UI until data resolves. Run the nav loop to capture the detail page's real blockers, wrap the request-API read in `'use cache: private'`, and verify with before/after screenshots that the static layout now appears immediately. ## Quick Start Ask the agent to optimize the slow navigation between two routes in your Next.js app that has cacheComponents enabled.

Frequently Asked Questions about next-cache-components-optimizer

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

FAQPage Schema

How do I optimize a Next.js page with cacheComponents enabled?▼

Run the page-render loop: capture the shell-only render with the instant cookie set, rank Suspense fallback areas by visible pixel size, then push I/O down into Suspense-wrapped children or add 'use cache' with a cacheLife profile. Verify with before and after screenshots that visibly differ.

How to make Next.js in-app navigation show the next page immediately?▼

Use the navigation loop: pushstate to the target route with the instant cookie set, capture suspended boundaries, and filter out client-hook blockers like usePathname that only affect SSR. Fix real blockers with push-down or 'use cache: private' plus prefetch = 'allow-runtime'.

Does this optimization work without cacheComponents in Next.js?▼

No. The Skill refuses to run unless cacheComponents: true is set in next.config.ts, since its levers like 'use cache', cacheLife profiles, and runtime prefetch all depend on that mode. It also requires the next-dev-loop session for browser and log access.

Why does my Next.js route show a blocking-route or NEXT_STATIC_GEN_BAILOUT error?▼

These errors mean the route has no static shell because dynamic I/O runs without a Suspense boundary. The Skill treats this as a no-shell bailout: you must wrap the offending dynamic access in <Suspense> before any shell-growing or caching optimization can apply.

When should I use 'use cache: private' instead of 'use cache' in Next.js?▼

Use 'use cache: private' when the I/O reads request APIs like cookies(), headers(), or searchParams, since shared caching bails to dynamic for those reads. Pair it with prefetch = 'allow-runtime' on the owning segment so navigation can resolve session-specific data at link-visibility time.