next-partial-prefetching-adoption

SKILL.md

next-partial-prefetching-adoption

Enable Partial Prefetching and walk the app until every link reuses a shared App Shell. This skill sequences the work; per-insight recipes live in the dev overlay fix cards and their docs pages. The Adopting Partial Prefetching guide is the canonical reference for the concepts this skill applies.

The one thing that shapes everything below: these insights surface only in next dev, in the dev overlay's Insights tab. Nothing fails the build. There is no build-only fallback loop — confirming an insight is cleared means driving the running app in a browser. But a missing browser gates that verification, not the whole skill: the adoption work is static and runs from the guide, so do the static pass anyway and hand off the live shell check.

Talk to the user in terms of what they'll see — PRs, features, and how the app behaves after — never the insight slugs or step labels. Before you start, tell them briefly what Partial Prefetching changes: a <Link> loads a shared App Shell, and prefetch={true} no longer prefetches everything the old full prefetch did.

requires

Cache Components on (cacheComponents: true). This is the only hard requirement; partialPrefetching depends on it. Full Cache Components adoption is the ideal starting point but not a gate. Nothing in this skill blocks the build, and neither do the prerender insights an unadopted route surfaces, like a leftover unstable_noStore or a cookies() read outside <Suspense>: they are non-blocking dev signals, expected on any fresh branch off main, not a reason to stop. They replace the URL-data insight only on their own route in the step 3 sweep; the flag-off step 1 audit and its static adoption run regardless. The only thing that actually stops this skill is a build-blocking failure, and anything build-blocking would have been resolved before you reached here. Otherwise fix the prerender insights you hit as inline next-cache-components-adoption work, or hand them off, and keep going.

Next.js 16.3 or later. partialPrefetching, the prefetch route segment config, and the prefetch insights all land there.

A browser you can drive. Install next-dev-loop before starting, unless it is already available — it ships alongside this skill (npx skills add https://github.com/vercel/next.js/tree/canary/skills/next-dev-loop). Install it without asking — it's a tool, not a product change — and don't assume it's blocked: verify a real blocker (no network, no npm, read-only filesystem) before falling back, and name it in your report. Link prefetches fire when a link renders and enters the viewport, and shell validation fires on navigation — neither is reachable from curl or the build. If the app is webpack-pinned, drive a browser directly (agent-browser, Playwright) — you lose the framework cross-checks, not the insights; they're still in the overlay and the dev log.

A runnable app. Verification runs against next dev for the insight sweep and a production next build/next start for prefetching (prefetching is prod-only), so the app has to boot in both. If it reads a database or required env at import (e.g. an env.ts that throws on a missing DATABASE_URL), confirm it starts — with the real environment, or local data you stand up — before step 1. An app that won't run can't be swept or verified.

notes