Skill v1.0.0
currentTrusted Publisher100/100version: "1.0.0" name: next-cache-components-optimizer description: > Optimize a Next.js app that has cacheComponents: true — either the static shell on first paint, or the in-app navigation between routes. Picks the matching diagnostic loop and runs it.
next-cache-components-optimizer
Two loops, shared levers and primitives, different diagnostics:
- Page-render loop (ppr-loop.md) — grow the static shell of a single page. Rank Suspense fallback areas on a shell-only render.
- Nav loop (instant-nav-loop.md) — when the user clicks a link from A to B, show B's static layout immediately (chrome, structure, content-shaped fallbacks) instead of holding A's UI until B's data resolves. Capture B's suspended boundaries post-
pushstate, classify each bysuspended_by[].name, drop SSR-only client hooks.
Pick one and run it end-to-end.
requires
next-dev-loopinitiated for this session — it opens the headed browser, exposes theagent-browserCLI, and wires the dev MCP server that providesmcp get_logs.cacheComponents: trueinnext.config.ts. Refuse otherwise.
preflight (shared)
- Confirm
cacheComponents: true. - The user must already be at the page each loop needs in the headed browser (from
next-dev-loop) — logged in, with any state set up. This skill can't drive auth, SSO, or MFA; it takes the manual setup as the starting point. (Each sub-loop names which page it expects.) agent-browser get urlto anchor the current route.
Each loop sets the instant cookie as needed (see the shared instant cookie section below).
instant cookie (shared)
Both loops use the next-instant-navigation-testing cookie to freeze the framework's dynamic-data writes. Once set, visible content on the page is the static shell + Suspense fallbacks — that's what we capture to assess the optimization.
Set it with a pending-lock tuple [0, "<unique-id>"]. The id is any unique string; the convention is a p-prefixed random stamp so concurrent scopes don't collide:
agent-browser cookies set next-instant-navigation-testing '[0,"p<random>"]' \--url <origin>
Each loop's preflight specifies when to set it within the flow. Clear it at the end (see teardown below).
decide which loop
- Page-render when the complaint is about one route's initial load. Read ppr-loop.md.
- Nav when it's about navigating between two routes. Read instant-nav-loop.md.
Ambiguous → ask.
shared refactor levers
- Push down — extract I/O into a Suspense-wrapped child so the parent stays static and static siblings lift into the shell.
- Recurse, don't blind-wrap. If a Suspense boundary already wraps a component containing both static content and the I/O, read inside, extract the I/O-dependent JSX into a new leaf, and lift the static siblings up.
- Cache —
'use cache'+cacheLife(<profile>). Always ask the user for freshness; map to a preset (seconds/minutes/hours/days/weeks/max/default).
Push-down and cache compose: push-down lifts static structure, cache eliminates the remaining data gap.
propose via plan mode (shared)
Each refactor goes through plan mode before applying. Treat this as a signal: the application work is non-trivial agentic engineering, not a templated edit. This skill provides the framework — which lever to reach for, which candidate to fix, what the expected visible delta is — but the real work (which file to edit, how to cleanly extract the I/O, where to place the new Suspense boundary, which cacheLife profile to ask the user for) is a judgment call you have to think through. Plan mode forces a coherent proposal before touching code, and gives the user a chance to redirect on any of those decisions.
no-shell bailout (shared)
The levers presume a shell exists to grow or cache toward. If the route is fully blocking — HTTP 500 with blocking-route or NEXT_STATIC_GEN_BAILOUT in mcp get_logs, or zero Suspense boundaries on a visibly-rendered page — there's no shell. Surface the structural blocker and stop; the user has to wrap the offending dynamic access in <Suspense> before either loop can help.
verify requires a visible delta (shared)
Each loop captures a baseline screenshot of the shell before applying any change, then re-screenshots after. Report both paths in the final summary so the user can see what changed. The two captures must visibly differ — fallback area shrunk, content promoted to the static surface, target fallback gone or content-shaped. Identical-looking captures mean the refactor didn't land; undo. "Compiles cleanly" is not the bar.
Hide the dev overlay before each screenshot. The Next.js dev overlay (<nextjs-portal> at the document root) renders instant-nav guidance, build errors, and other dev chrome that pollute the before/after comparison. Hide it, screenshot, restore:
agent-browser eval "document.querySelector('nextjs-portal').style.display='none'"agent-browser screenshot <path>agent-browser eval "document.querySelector('nextjs-portal').style.display=''"
anti-patterns (shared)
Don't replace granular Suspense boundaries with a top-level loading skeleton. A loading.tsx for the whole segment, or a root-level <Suspense fallback={<Skeleton />}> (or worse, fallback={null} that blanks the UI), defeats this skill's optimization — which is to extract real static chrome above each granular boundary and use content-shaped fallbacks per region. A coarse "the page is loading" stand-in bypasses the work entirely.
gotchas (shared)
- Dev doesn't prefetch the way production does, and routes compile on first hit — so after a navigation or reload, the DOM keeps updating for noticeably longer than the eventual production experience. Wait patiently for the DOM to stabilize before capturing the React tree or taking a screenshot — e.g., poll
document.documentElement.innerHTML.lengthuntil it's unchanged across two consecutive reads. A fixed short delay risks sampling mid-render. - Don't try to verify nav prefetch by inspecting dev network traffic — dev doesn't fire prefetch requests at all, so the network tab, manual
router.prefetch()calls, and<Link prefetch={true}>will all look broken regardless of whether your code is correct. The cookie-locked SPA-nav recipe in instant-nav-loop.md underverifyis already the canonical recipe for this — it simulates what production would prerender into the prefetched RSC without requiring prefetch to actually fire. Use it; don't invent a network-tab alternative. - The diagnose pipeline can be flaky — DevTools attachment timing, DOM-settle races, and dev compilation effects can each produce inconsistent captures from one run to the next. When a result feels off (a candidate appears that you don't expect, or one you expect doesn't), re-run the diagnose 2–3 times and cross-check; boundaries that appear consistently are real, one-off appearances are noise.
reference (shared primitives)
agent-browser react suspense add --only-dynamic to filter--json server-side to actually-suspended boundaries. Eachentry has jsx_source +suspended_by[] with raw blockernames (usePathname, cookies,fetch, cache, ...); classify byname for per-loop rulesPOST /__nextjs_original-stack-frames body { frames: StackFrame[],isServer, isEdgeServer,isAppDirectory }; returns oneresult per frame withfile:line:columnmcp get_logs dev MCP tool fromnext-dev-loop; surfacesblocking-route /NEXT_STATIC_GEN_BAILOUT 500scacheLife('<profile>') default | seconds | minutes| hours | days | weeks | max
Per-loop primitives in instant-nav-loop.md.
teardown (shared)
Delete the cookie by name — overwrite with an expired stamp:
agent-browser cookies set next-instant-navigation-testing x \--url <origin> --expires 1
Never agent-browser cookies clear (no args) — wipes auth.
Sibling of next-dev-loop — initiate that first.