Next Partial Prefetching Adoption

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 (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

• Offline docs. Guide links have offline copies under node_modules/next/dist/docs/ (bundled since Next.js 16.2), with the directory layout numbered for ordering (e.g. node_modules/next/dist/docs/01-app/02-guides/adopting-partial-prefetching.md). If you can't predict the numbered prefix, find node_modules/next/dist/docs -name '<slug>.md' resolves it. The /docs/messages/* error pages are not bundled.

• Older versions without bundled docs. Suggest npx @next/codemod@latest agents-md to the user before starting: it downloads a version-matched copy to .next-docs/ and writes an index into AGENTS.md / CLAUDE.md. It touches files in their repo, so ask first and run it only if they want it.

background

Adopting Partial Prefetching means every route still delivers what its links prefetched before, now split between the shared App Shell and any extra per-link data a link explicitly asks for. The guide is the canonical reference for what a prefetch contains and how to decide each case; this skill sequences that work against a running app.

The catch that decides most of the sweep: a default link warms only the shared App Shell. A route keyed by params or searchParams can prefetch more only after it has adopted Partial Prefetching and a specific link uses <Link prefetch={true}>; then Next.js resolves the URL data and any cached content behind it before the click (the guide's URL data section).

working surfaces

• The dev server terminal — your primary record. Each validated route's insights are logged as Error: Route "...": Next.js encountered ... lines with the https://nextjs.org/docs/messages/<slug> link. Tail the dev log during the sweep; it's the greppable record of what fired where, and it works the same on Turbopack and webpack.
• The dev overlay Insights tab. Insights are the amber, non-blocking tab. It appears only once an insight has fired, so a route that surfaces nothing shows no tab at all — that's the clean state, not a missing feature. Don't hunt for the tab on a quiet route; confirm clean from the dev log above, which is the reliable signal. The precondition is no blocking-prerender errors — those replace the insight on their route (see requires). An unrelated Issue (a hydration error, a console error) doesn't block the sweep; don't stall on it. When the tab is present, the overlay pill shows the count and each insight has fix cards linking its docs page. The overlay renders inside a shadow root (nextjs-portal), so accessibility-tree snapshots don't see it — evaluate into shadowRoot when you need to read or click it programmatically.
• next-dev-loop to drive navigations and read the overlay. Prefer it over hand-rolled browser automation for the same reasons as in the Cache Components skill (webpack apps: see requires). When browsing its /_next/mcp tools, the prefetch insights surface through get_errors and the overlay, not the similarly-named get_request_insights. That one is the span and performance recorder (gated behind experimental.requestInsights) and reports nothing about prefetching.

Every insight has a docs page — open it. Fetch the linked page for every distinct insight you encounter; the inline message is a summary, the page is the recipe.

step 1: audit <Link prefetch={true}> (before enabling)

If partialPrefetching: true is already set in next.config.ts, the app is adopted — skip to step 3. Otherwise work the audit with the global flag off, adopting each destination with export const prefetch = 'partial' — enabling the flag first would mark every route adopted and silence the link-prefetch-partial insight this audit runs on. Ask the user how to ship it, in the language of PRs:

• One branch — the whole audit in one change, with the flag enabled and the codemod run at the end (step 2).
• Route by route — each adopted destination ships as its own PR. The insight still fires for the destinations you haven't reached, a live worklist, and step 2 comes after the last one.

The work is identical either way — only the commit boundaries differ. Default by app size: one branch for a handful of links, route by route when the audit is big enough that reviewers need smaller diffs. Note the choice in your report.

Enumerate the prefetch sites across the whole source tree, not only app/ — they often live in src/components or shared UI packages: rg -n '\bprefetch\b|router\.prefetch' -g '*.tsx' -g '*.jsx' .. Keep the <Link prefetch={true}> and bare-prop matches (a bare prop is true) as the over-prefetching links this audit adopts destinations for, and drop prefetch={false} and other values. Also audit existing imperative router.prefetch() call sites with the same table, because they can be preserving the same "fetch before navigation" behavior and have no dev insight. For new navigation prefetching, prefer <Link>, which the docs call the primary navigation API; use router.prefetch() only for manual prefetching. If the app already passes an internal kind option, treat that as existing implementation detail, not a pattern to spread. If nothing matches, check for a custom link wrapper before calling the audit empty. If there's still nothing, say so in your report and move on to step 2.

Then, for each one:

1. Click each <Link> in next dev. The insight fires at navigation time, not when the link prefetches, so a link sitting in the viewport won't trip it — you have to navigate through it. This click is verification: it confirms the insight fires before you adopt and clears after. Imperative router.prefetch() sites have no equivalent insight, so audit them from source and verify them in production (step 4). Without a browser, skip the click and adopt from link-prefetch-partial and the audit table below — the destination's structure tells you the row, and type-check gates the edit — then leave the live confirmation for the hand-off.

2. Adopt the destination. Add the temporary route config with a link to the migration guide. That clears the insight for every link pointing at it:

   // See: https://nextjs.org/docs/app/guides/adopting-partial-prefetching
   export const prefetch = 'partial'

   If the route reads URL data (params, searchParams), the default link still warms only its skeleton (the guide's URL data section), so it's a runtime-prefetch candidate for step 5, not a finished adoption. Keep prefetch={true} on its links and mark the route:

   // TODO(runtime-prefetch): assess with the user whether URL data should resolve before click.
   // See: https://nextjs.org/docs/app/guides/runtime-prefetching
   export const prefetch = 'partial'

   Use that exact prefix so step 5 can grep them back. Don't cache or decide anything for these routes now.

3. Preserve what that prefetch delivered. The guide's audit table is the canonical decision — fetch it and apply the matching row. Caching uncached content is the judgment call in that table: trace where the data comes from and what freshness and revalidation it needs, per the use cache docs, and ask the user when the answer isn't clear-cut. The URL-data routes you marked in the previous item wait for step 5.

If you add use cache, verify under next start, not only the build. A cookies()/headers()/session read anywhere in the cached call tree throws at request time while next build passes clean. See use cache.

step 2: enable the flag

Once every audited destination has prefetch = 'partial', finish in two moves.

1. Enable the flag globally. Set partialPrefetching: true in next.config.ts (alongside cacheComponents: true). Every route is adopted now, so every link is good.

2. Strip the redundant prefetch = 'partial' exports. Run the first-party remove-partial-prefetch codemod rather than a text find-and-replace. It removes only export const prefetch = 'partial' and its generated Partial Prefetching guide comment. It leaves other values such as prefetch = 'force-disabled' in place, along with your TODO(runtime-prefetch) markers and their Runtime Prefetching guide links, which wait for step 5.

   npx @next/codemod@latest remove-partial-prefetch ./app

   The codemod refuses to run on a dirty working tree. Commit or stash unrelated work first, or pass --force to let its edits land alongside your WIP. If the codemod isn't available (older @next/codemod, sandboxed environment, offline run), reproduce it by hand by removing export const prefetch = 'partial' and its generated Partial Prefetching guide comment from every app/**/{page,layout}.{js,jsx,ts,tsx} — leave other prefetch values in place, and leave the TODO(runtime-prefetch) markers and Runtime Prefetching guide links where they are. Don't hand-edit when the codemod can run.