skills.rest
yehezkieldio
yehezkieldioCOMMUNITY
Explore all skills by this author →
𝕏@yhezkieldioGitHub

next-cache-components-optimizer

Drives Next.js routes to instant navigation using test-driven Cache Components optimization loops.

Updated Aug 15, 2025
Search Tags:#suspense#next.js#performance optimization#playwright#e2e testing#cache components#instant navigation
One-click install
npx skills add https://github.com/yehezkieldio/topaz --skill next-cache-components-optimizer-yehezkieldio
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: next-cache-components-optimizer
Source: https://github.com/yehezkieldio/topaz/tree/main/.agents/skills/next-cache-components-optimizer
Command: npx skills add https://github.com/yehezkieldio/topaz --skill next-cache-components-optimizer-yehezkieldio

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Next.js routes under Cache Components often block navigation on top-level awaits, coarse Suspense boundaries, or uncached data reads, leaving users staring at blank screens. This Skill sets up a repeatable, test-driven loop that encodes instant navigation as a failing @next/playwright instant() e2e test, works it to green, and ships the test as a permanent regression guard. ## Core Features & Use Cases - Test-driven optimization loop: Encode the goal as a failing instant() test (RED), push Suspense boundaries down to the data they guard (FIX), and verify with a differential revert/re-apply check before shipping. - Fix pattern library: Reference guides cover before/after recipes for top-level awaits, cookies()/headers() reads, uncached fetches, searchParams, auth gates, parallel routes, and responsive skeleton mismatches. - Rig discovery and RED robustness: A one-time per-repo rig template captures build, deploy, auth, and test-user setup, plus a checklist and taxonomy for detecting untrustworthy RED tests (vacuous passes, guessed selectors, stale deploys). - Use Case: A dashboard route waits on a charts query before painting anything. The Skill drives a real <Link> click under instant(), confirms the shell is missing, defers the query behind a Suspense boundary reusing the route's existing skeleton, and ships the green test as the regression guard. ## Quick Start Ask the agent to make a specific Next.js route's navigation instant using the next-cache-components-optimizer skill, and it will set up the rig, write the failing instant() test, fix the route, and ship the guard.

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 with Cache Components?▼

Encode the goal as a failing @next/playwright instant() test, then push each Suspense boundary down to the single data read it guards while hoisting static layout UI into the shell. The route is done when the locked test passes green on a production build and a revert/re-apply differential confirms the test measures the fix.

How do I test instant navigation in Next.js with Playwright?▼

Use the instant() function from @next/playwright, which gates dynamic data so you can assert the static shell commits under the lock. Drive a real <Link> click for soft navigations or page.goto() with the baseURL option for initial loads, and never add custom timeouts since instant() is a ruler, not a stopwatch.

What Next.js version is required for Cache Components optimization?▼

Next.js 16.3 or later with cacheComponents: true in next.config.ts is required, since earlier versions have no static shell to optimize. The @next/playwright package must be on the same release line as the project's next package, and npx @next/codemod upgrade automates most of the upgrade.

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={null} shell, so use the self-validating test variant that asserts deferred content is gated under the lock.

Can I measure instant navigation on next dev?▼

No, next dev does not prefetch and its lock is unreliable for blocking routes, so a dev instant() result is never a valid verdict. Always measure on a production build such as next build && next start, a CI staging container, or a preview deploy.

What are the limitations of static shell optimization for URL-dependent routes?▼

When an entire page depends on params, searchParams, or the full URL, there may be no meaningful shared shell to grow, and forcing one is an anti-pattern. The alternative is per-link prefetching with <Link prefetch={true}>, which requires Partial Prefetching adoption and URL-keyed use cache content.

Related Skills

Explore More Software Engineering Skills→
vercelvercel
142.0k

next-cache-components-optimizer

Drive Next.js routes to instant navigation via test-driven Cache Components optimization.

Official
Advanced
sanity-iosanity-io
952

next-partial-prefetching-adoption

Enable Partial Prefetching in Next.js apps and resolve its dev-overlay insights.

Official
Advanced
WesleySmitsWesleySmits
6

profiling-performance

Audit web performance with Lighthouse and Core Web Vitals metrics.

Community
Advanced
sanity-iosanity-io
952

next-cache-components-adoption

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

Official
Advanced