next-cache-components-optimizer

Optimizes Next.js routes for instant navigation using test-driven Cache Components workflows.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/devsajad/next.js-starter-kit --skill next-cache-components-optimizer-devsajad
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: next-cache-components-optimizer
Source: https://github.com/devsajad/next.js-starter-kit/tree/main/.claude/skills/next-best-practices
Command: npx skills add https://github.com/devsajad/next.js-starter-kit --skill next-cache-components-optimizer-devsajad

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @next/playwright, @playwright/test, next, and includes references (resource) components.

What problem does it solve? Next.js routes often block navigation on dynamic data reads, leaving users staring at blank screens while layouts and content load. This Skill provides a test-driven loop that makes a route's static shell commit immediately on both hard and soft navigations, then ships a regression test to keep it that way. ## Core Features & Use Cases - Test-driven optimization loop: Encodes the goal as a failing @next/playwright instant() e2e test, works it to green by pushing Suspense boundaries down to the data they guard, and ships the test as a regression guard. - Fix pattern library: Provides before/after recipes for common blockers including top-level awaits, cookies()/headers() reads, uncached fetches, searchParams, auth gates, and parallel routes. - RED verification gates: Includes a robustness checklist and differential testing procedure to ensure failing tests fail for the right reason before optimizing. - Use Case: A dashboard route waits on a charts query before painting anything. The Skill drives the navigation under an instant() lock, identifies the blocking Suspense boundary, hoists the layout into the static shell, and verifies the shell commits instantly at desktop and mobile widths. ## Quick Start Ask the agent to make a specific Next.js route's navigation instant using the cache components optimizer workflow.

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 make a Next.js route navigation instant?

Encode the goal as a failing @next/playwright instant() test, then push each Suspense boundary down to the specific data read it guards so the static shell prerenders. Run the test on a production build until it passes green, then ship it as a regression guard.

How to fix a Next.js route whose static shell is not prerendered?

Identify the blocking read with next build --debug-prerender, which prints an error linking to the specific blocker type. Common fixes include moving top-level awaits into Suspense-wrapped children, caching stable data with use cache, and deferring auth gates behind a boundary.

Does this workflow work with older Next.js versions?

No, it requires Next.js 16.3 or later with cacheComponents: true in next.config.ts, since earlier versions have no static shell to optimize. Upgrade first with npx @next/codemod upgrade and enable Cache Components before running the loop.

Why does my instant() test pass but the route is still slow?

A green instant() test can be vacuous if the build lacks experimental.exposeTestingApiInProductionBuild, since the lock silently no-ops. It can also pass with an empty fallback shell, so verify the shell renders real content at desktop and mobile widths.

Can I test instant navigation on next dev?

No, next dev does not prefetch and its lock is unreliable for blocking routes, so dev results are not valid verdicts. Always measure on a production build via next build && next start, a CI container, or a preview deploy.

What if a route depends entirely on URL params or searchParams?

When URL data cannot be pushed down, there may be no meaningful static shell to grow, so do not force one. Runtime prefetching with Partial Prefetching and Link prefetch={true} can make the soft navigation instant instead.