With the latest GA changes, when using Cache Components with Partial
Prefetching:
> prefetch={true} turns on prefetching
These changes try to align around that idea.
- runtime prefetching guide is now about optimizing
- various changes in prose across docs
- even fix an error page for pages router, which had a broad title
---------
Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
Removes the "allow-runtime" prefetch config, and turns its behavior on
implicitly wherever Partial Prefetching is enabled.
The original motivation for "allow-runtime" was to give apps more
control over server costs triggered by prefetches. Until a route
explicitly opts in, prefetches would only be served from the CDN, not
from the server. The problem, though, was it was very confusing to know
when to add or remove this configuration. The incentive for many apps
was to add it everywhere, with no clear signal for when to remove it.
Our updated thinking is that Partial Prefetching itself already provides
sufficient protection against runaway prefetching costs: per-link
prefetches only happen on Link components that explicitly opt in with
the prefetch prop.
The optimizations landed earlier in this stack also make allow-runtime
less necessary: on pages where all the content is statically renderable,
prefetches are served from the static cache and no runtime request is
ever issued; only a page that accesses non-static data is prefetched at
runtime.
The upshot of this decision is that runtime versus static becomes an
internal optimization; the same content gets prefetched regardless of
whether or how Next.js is able to optimize it.
## What
Follow-up to #95365. Documents adopting Partial Prefetching end to end:
- Restructures the [Adopting Partial Prefetching
guide](https://github.com/vercel/next.js/blob/canary/docs/01-app/02-guides/adopting-partial-prefetching.mdx)
around the two paths: enable `partialPrefetching` and audit every `<Link
prefetch={true}>` against a per-case decision table, or adopt
incrementally per route with the
[`instant-link-prefetch-partial`](https://nextjs.org/docs/messages/instant-link-prefetch-partial)
insight as the worklist. Adds `Auditing routes for URL data` and
`Prefetching URL data` sections.
- Adds the `remove-partial-prefetch` codemod, which strips the redundant
per-route `prefetch = 'partial'` exports once the flag is on while
preserving comments and other `prefetch` values.
- Adds the `next-partial-prefetching-adoption` skill that sequences the
guide for agents: audit, enable + codemod, URL-data sweep, verify,
optional runtime prefetching.
- Aligns the `instant-link-prefetch-partial` error page, `<Link>`
reference, glossary, and Interactive apps guide with the same prefetch
model.
## Why
With the flag on, `<Link prefetch={true}>` no longer delivers dynamic
content, and shell validation flags `params`/`searchParams` reads
outside `<Suspense>`. Adopters need one guide that sequences the audit,
the flag, and both insights, and an agent skill that follows it.
Stacked on #95365 (base: `codex/instant-shell-link-data`) since it links
to the `instant-shell-url-data` error page that PR introduces. GitHub
will retarget to `canary` when that merges.
<!-- NEXT_JS_LLM_PR -->
## What?
Adds the Instant Insight + rule page for the Partial Prefetching shell
validation (Janka's #95151): with `partialPrefetching` on, a route that
reads `params`/`searchParams` outside `<Suspense>` blocks the extraction
of the per-route **App Shell** that every link to the route shares.
Surfaced as an Instant insight (not a redbox), with two fix cards:
Stream (wrap in `<Suspense>`) · Allow blocking route (`instant =
false`).
The insight fires both at link-prefetch time and during a client-side
navigation, so it covers a `<Link prefetch>` into the route as well as a
plain client navigation to it.
Demos:
-
[99-link-params-gsp](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/99-link-params-gsp)
— `<Link prefetch>` to a `generateStaticParams` route that awaits
`params` unguarded.
-
[117-subnav-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/117-subnav-params)
— client-side navigation into a `[slug]` route that reads `params`
outside `<Suspense>`.
-
[118-subnav-search-params](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/118-subnav-search-params)
— client-side navigation into a route that reads `searchParams` outside
`<Suspense>`.
Follow-up: #95389 documents the route-side audit in the Adopting Partial
Prefetching guide (draft, to be coordinated).
## How?
- Family-wide polish across all 16 insight pages while aligning the new
one: consistent "Verifying the fix" wording, normalized `Learn more:`
link texts (target title for guides, bare code name for API references),
"App Shell" used consistently, CLS guidance reframed as "minimizing
layout shift", prose cleanups (no semicolons, no code-initial
sentences), and the insight-error-page skill updated to match.
- New `errors/instant-shell-url-data.mdx` rule page, structured like the
rest of the insight family (`blocking-prerender-client-hook`,
`instant-link-prefetch-partial`); added to every page's Related
Insights. New **URL data** glossary entry ("varies per link, not per
session"), linked from the page.
- `createLinkBodyErrorInNavigation` re-pointed to the page and
classified as a navigation-time insight (`inNavigation` → Instant tab)
using the shared `linkCards` fix cards.
- Common insight format for the message: headline "Next.js encountered
URL data outside of Suspense", consequence "may prevent the navigation
from being instant, leading to a slower user experience" ("may", since
boundaries or a runtime prefetch can still keep the navigation instant),
and the two fixes phrased as `[stream] Provide a placeholder with
<Suspense fallback={...}> around the data access` and `[block] Set
export const instant = false to allow a blocking route`. The shell
mechanics are explained on the docs page rather than in the headline.
- Second fix reframed from "Disable validation" (group `ignore`) to
**Allow blocking route** (group `block`), matching the
`blocking-prerender-*` family: `instant = false` marks the segment as
allowed to block rather than opting the route out of validation.
- Metadata/viewport variants: only the headline term is aligned ("link
data" → "URL data") plus a small grammar fix; framing, fix cards, and
docs URLs stay on the existing `-metadata-runtime`/`-viewport-runtime`
pages unchanged.
- `errors.json` regenerated append-only (codes 1407-1409), and the docs
opt-out wording updated to the new silence-free phrasing.
- e2e snapshots updated for all four configs (dev/start ×
default/partial-prefetching); unit tests for the matcher, cards,
classification, and `isInstantNavigationError`.
<!-- NEXT_JS_LLM_PR -->
## Why
Standardize the Insight fix UI across the dev overlay and docs, and
round out the docs side with a proper family index at the bottom of
every page.
## What
- Dev overlay: **Copy as prompt** -> **Copy prompt**; bumped the pill
padding to match the new docs button.
- Error pages (`errors/*.mdx`, 15 files): `<FixOption>` ->
`<FixCardGrid>`/`<FixCard>` with snippets copied verbatim from
`instant-guidance-data.ts`; all `https://preview.nextjs.org/docs/...`
URLs converted to relative `/docs/...`.
- Every Insight error page now ends with a `## Related Insights` index
listing the other 14 Insight pages (self omitted).
- `instant-navigation.mdx` and `migrating-to-cache-components.mdx`:
dropped the stray trailing `}` snippet line so guide cards match
dev-overlay heights; added a one-line Copy prompt note linking to
`#ai-workflow`.
- `insight-error-page` skill: replaced the "Useful links" guidance with
"Related Insights" (full family index, no API refs/guides) and matching
audit-checklist line.
- Minor cleanup in `instant-guidance-data.ts` (trimmed verbose JSDoc to
non-obvious bits).
## How
Paired with vercel/front#75443 which adds the Copy prompt button to
`<FixCard>` and deletes the legacy `<FixOption>`. `pnpm --filter=next
types` clean, 23 `instant-guidance-data` tests pass.
<!-- NEXT_JS_LLM_PR -->
### What?
Restructure the 15 Insight error pages
(`errors/blocking-prerender-*.mdx`, `errors/instant-*.mdx`) so they
orient the reader before diving into fixes, and point at the preview
docs for the new 16.3 Instant Navigations guide and APIs.
### Why?
These pages are the first thing devs see when they click the doc link
from the dev overlay or the build output for a blocking-route /
instant-navigation error. Previously they opened straight into the
technical explanation with no signal that this error is part of the new
16.3 Instant Navigations feature, and several callouts mixed unrelated
concerns (debug flags inside a top-of-page "Good to know", duplicated
"Useful links" footers).
### How?
- **Intro callout box** added to every page, pointing at the 16.3 launch
blog post and the migration guide so newcomers have an anchor before
reading the fix.
- **`## Verifying the fix` section** added near the bottom, gathering
the debug tips (empty-shell warning, `--debug-prerender`,
`--debug-build-paths`) that previously sat in a top-of-page "Good to
know" callout where they were misplaced.
- **Removed** duplicated "Useful links" footers (already cross-linked in
body), removed the misplaced top-of-page debug callout.
- **Switched all 473 doc links** to
`https://preview.nextjs.org/docs/...` so they resolve against the
unpublished 16.3 docs (the live nextjs.org docs don't have the Instant
Navigations guide or the route-segment-config/instant API reference
yet).
Split out of #95186 (Copy-as-prompt checklist) which was the same branch
but a separate feature.
Closes NEXT-
<!-- NEXT_JS_LLM_PR -->
Joseph