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 by
```
suspended_by[].name
```
, drop SSR-only client hooks.

Pick one and run it end-to-end.

requires

```
next-dev-loop
```
initiated for this session — it opens the headed browser, exposes the
```
agent-browser
```
CLI, and wires the dev MCP server that provides
```
mcp get_logs
```
.
```
cacheComponents: true
```
in
```
next.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 url
```
to 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

-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

NEXT_STATIC_GEN_BAILOUT

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.length
```
until 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 under
```
verify
```
is 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. Each
                                      entry has jsx_source +
                                      suspended_by[] with raw blocker
                                      names (usePathname, cookies,
                                      fetch, cache, ...); classify by
                                      name for per-loop rules

POST /__nextjs_original-stack-frames  body { frames: StackFrame[],
                                      isServer, isEdgeServer,
                                      isAppDirectory }; returns one
                                      result per frame with
                                      file:line:column

mcp get_logs                          dev MCP tool from
                                      next-dev-loop; surfaces
                                      blocking-route /
                                      NEXT_STATIC_GEN_BAILOUT 500s

cacheLife('<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.

next-cache-components-optimizer

NPX Install

Tags

SKILL.md Content

next-cache-components-optimizer

requires

preflight (shared)

instant cookie (shared)

decide which loop

shared refactor levers

propose via plan mode (shared)

no-shell bailout (shared)

verify requires a visible delta (shared)

anti-patterns (shared)

gotchas (shared)

reference (shared primitives)

teardown (shared)