## 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 -->
Rewrites the `io()` API reference around what it expresses: with Cache
Components `await io()` keeps the operation that follow afterward out of
the static shell.
Adds Server/Client usage examples and a composition note, a "When you
don't need `io()`" section, and reframes the `connection()` comparison
around prefetching.
---------
Co-authored-by: Aurora Scharff <66901228+aurorascharff@users.noreply.github.com>
Co-authored-by: Aurora Scharff <aurora.sofie@gmail.com>
### What?
Docs-only follow-ups for Cache Components and Partial Prefetching, from
agent migration friction logs and Joseph's review of
[#95082](https://github.com/vercel/next.js/pull/95082).
- **`adopting-partial-prefetching.mdx`** — reframe the `allow-runtime`
row in the audit table (it's an enhancement, not the `<Link
prefetch={true}>` warning fix; the per-route opt-in is `prefetch =
'partial'`).
- **`migrating-to-cache-components.mdx`** — split the `## Enable Cache
Components` section into before-flag (remove `dynamic` / `revalidate` /
`fetchCache`) and after-flag (translate `revalidate`, `fetchCache`,
`unstable_cache`, `fetch` cache options) steps. Flag the `revalidateTag`
second-argument requirement, with a Before / After example. Add two
Good-to-know callouts: off-grid `revalidate` values map to the closest
`cacheLife` profile; `instant = false` is allowed-to-block, not
forced-dynamic.
- **`blocking-prerender-current-time` / `-random` / `-crypto`** (and
their `-client` siblings) — drop the misleading "Don't want this
validation?" opt-out section. `instant = false` is an instant-navigation
knob and doesn't suppress sync-IO prerender errors.
- **Remaining `blocking-prerender-*` pages** — standardize the CLS
fallback callout so they all link the canonical section.
### Why?
Friction logs surfaced four recurring misreads:
1. Devs expected `prefetch = 'allow-runtime'` to silence the `<Link
prefetch={true}>` warning. The docs implied it would.
2. The migration guide mixed `dynamic` removal with `unstable_cache`
translation, so it wasn't clear which had to happen before the flag and
which after.
3. `revalidateTag` now requires a cache profile, but the on-demand
revalidation section didn't say so.
4. Sync-IO error pages still carried a "Don't want this validation?"
opt-out that doesn't actually work for those errors.
### What
The dev-overlay fix cards' `Copy AI prompt` button used to copy a
multi-paragraph instruction string baked into each card (71 prompts
across docs + runtime). This PR replaces that with a dynamic template
the button builds at click time:
```
Apply the [Stream] "Wrap in or move into Suspense" fix to the Next.js Insight raised in this project.
Steps:
1. The failing code is in the error block below — it may be a data-access call, a hook call, a metadata or viewport export, or a component. The fix applies to that exact code; don't touch unrelated files.
2. Read the rule docs at <rule-url> for the full Insight explanation, then read the fix section at <fix-url>. Pick the pattern under "### Patterns" that matches the failing code, then read "### Gotchas" before editing — they list constraints that are easy to miss. Use the canonical imports and code shape from the page; don't improvise variations.
3. Apply the chosen pattern to the code identified in step 1.
## Error Type
Blocking Route
## Error Message
Route "/01-cookies-body": ...
at Page (app/01-cookies-body/page.tsx:4:26)
## Code Frame
> 4 | const c = await cookies();
| ^
...
Next.js version: 16.3.0-canary.47 (Turbopack)
```
### Why
Old verbatim prompts repeated what the docs already say and never
anchored the fix to the actual error. The new template:
- Names the chosen fix (group badge + title) so the agent picks the
right pattern.
- Points at the rule docs AND the specific fix anchor, with explicit
instructions to read `### Patterns` and `### Gotchas`.
- Prepends the live error block (same shape the existing 'Copy error
info' button emits) so the agent has the failing file, line, code frame,
and stack inline — no need to re-fetch the dev overlay.
### Changes
- `FixCard` type: `prompt?: string` → `copyable?: boolean`
- `CopyPromptButton`: takes `title + group + link + generateErrorInfo`,
builds the prompt
- Refactored `generateErrorInfo` from `errors.tsx` into a shared
`utils/generate-error-info.ts` so the existing 'Copy error info' button
and the fix-card 'Copy AI prompt' button format the error block
identically
- 14 error MDX pages: every `prompt={...}` removed (36 strings)
- `instant-guidance-data.ts`: every `prompt: '...'` → `copyable: true`
(35 strings)
- Skill (`.agents/skills/insight-error-page/SKILL.md`): updated
### Pairs with
vercel/front#73087 — same template in the docs-site `<FixOption>`
(without the error block, since there's no live error on a docs page).
<!-- NEXT_JS_LLM_PR -->
### What?
Removes `unstable_disableValidation` recommendations from all 14
insight-kind error pages and the `generateViewport` API reference. The
key on `unstable_instant`'s object form is not going to ship as a
recommended public API.
### Why?
Each error page's **"Don't want this validation?"** block previously
listed three opt-out levels:
1. **One segment** — `export const unstable_instant = false`
2. ~~**Layout and its children** — `export const unstable_instant = {
unstable_disableValidation: true }`~~ ← dropped
3. **Entire app** — `experimental.instantInsights.validationLevel:
'manual-warning'`
Dropping the middle bullet aligns the docs with the public-API surface
we intend to keep.
### How?
- Removed the `Layout and its children` bullet across 14 `errors/*.mdx`
pages.
- Removed the now-broken `See [Don't want this validation?] for the
subtree-wide opt-out` reference in the in-body **Gotchas** sections.
- Updated the `generate-viewport.mdx` API reference to drop the same
dangling reference.
- Framework source (`unstable_disableValidation` parsing in
`app-segment-config.ts` and runtime handling in `instant-config.tsx`) is
unchanged — that's a separate framework concern.
<!-- NEXT_JS_LLM_PR -->
### What?
Moves 14 insight-kind error pages from
`vercel/front/apps/next-site/content/errors-extra/` into this repo's
`errors/` directory.
### Why?
`nextjs.org`'s sync pipeline already clones `errors/` from canary on
every deploy. `errors-extra/` is meant for in-flight drafts. These pages
have stabilized, so they belong with the framework code they describe.
This unblocks Docs Link Validation in #94496: cross-links from this
repo's API docs (`cookies.mdx`, `headers.mdx`, `use-params.mdx`,
`use-pathname.mdx`, `generate-metadata.mdx`, `generate-viewport.mdx`,
etc.) to `/docs/messages/blocking-prerender-*` now resolve.
### How?
Copied each `.mdx` verbatim. No content changes. Frontmatter (`kind:
insight`) routes them through the FixOption renderer. Follow-up PR in
`vercel/front` will remove the `errors-extra/` copies; until then the
override wins on slug collision but the content is byte-identical.
<!-- NEXT_JS_LLM_PR -->
Joseph