skills.rest
Foodshareclub
FoodshareclubOFFICIAL
Explore all skills by this author →
Website𝕏@foodshareclubGitHub

next-cache-components-optimizer

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

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

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 sets up a repeatable, test-driven loop that makes a route's static shell commit immediately on both hard and soft navigations, and ships a regression test so it stays that way. ## Core Features & Use Cases - Test-driven optimization loop: Encodes the goal as a failing @next/playwright instant() e2e test (RED), 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 every blocker type — top-level awaits, cookies()/headers() reads, uncached fetches, searchParams, non-deterministic values, dynamic metadata, and auth gates. - Trustworthiness gates: Includes a RED-verification checklist, differential testing (revert the fix, confirm RED returns), and parity checks so the refactor changes only whether the route is instant. - Use Case: A dashboard route waits on a charts query before anything paints. The Skill drives the browser to confirm the gap, hoists the layout into the static shell, defers the charts behind a Suspense boundary with the existing skeleton, and proves the fix with a locked instant() test. ## Quick Start Ask the agent to make a specific route's navigation instant using the next-cache-components-optimizer workflow, for example: make navigating to the dashboard route instant and add the instant() e2e 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 dynamic 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 reverting the fix turns it red again.

What is the @next/playwright instant() test in Next.js?▼

instant() is a testing API from @next/playwright that gates dynamic data during a navigation so you can assert the static shell commits. It acts as a ruler rather than a stopwatch: an instant route's shell appears under the lock, while a blocking route's content never commits.

Does this optimization work on Next.js versions before 16.3?▼

No. The workflow requires Next.js 16.3 or newer with cacheComponents: true in next.config, because without Cache Components there is no static shell to optimize. Upgrade first with the @next/codemod upgrade command, then enable the flag.

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 that commits a blank shell, so use the self-validating test variant and give every boundary a real loading skeleton.

How do I fix a top-level await blocking my Next.js layout?▼

Render children unconditionally and move the await into a Suspense-wrapped child component. For auth gates, wrap the gate in Suspense with fallback null so the redirect still happens at request time while the rest of the layout prerenders into the static shell.

When should I use per-link prefetching instead of growing the static shell?▼

Use per-link prefetching only when the whole route depends on URL data like params or searchParams that cannot move behind a boundary. It requires Partial Prefetching adoption, a Link with prefetch={true}, and URL-dependent content behind use cache; otherwise prefer the cheaper static shell approach.

Related Skills

Explore More Software Engineering Skills→
sanity-iosanity-io
952

next-cache-components-optimizer

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

Official
Advanced
ri-ruri-ru

next-partial-prefetching-adoption

Enable Partial Prefetching in Next.js 16.3 applications via route-level configuration.

Community
Advanced
KevinKE93KevinKE93
42

performance-optimization

Measure bottlenecks, apply targeted fixes, and verify Core Web Vitals improvements.

Community
Advanced
yehezkieldioyehezkieldio

next-cache-components-adoption

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

Community
Advanced