### What?
- Rename cards to plain English: `Prerender params if known`, `Mark the
route as dynamic`, `For telemetry, use a timing API`.
- Remove `Wrap body in Suspense` card from viewport variants.
- Body errors: `during the initial render` → `during prerendering`;
`blocking navigation` → `blocking the page load`.
- Server sync IO leads with `the unstable value <expression>`.
- Client sync IO drops `fixed at build time`.
- New loading-state icon for the `block` group.
### Demo
- [Fix
Overview](https://error-messages-overhaul-ibsl.labs.vercel.dev/fix-overview)
<!-- NEXT_JS_LLM_PR -->
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
### What?
Redesigns the blocking-route error overlay for instant navigation errors
with a distinct "Instant" overlay path, visual technique cards, and
updated error wording framed around navigation impact.
### Why?
The current overlay dumps every possible cause and fix in one block of
text. The new design is friendlier — amber "Instant" badge, a short
headline framed around navigation, and responsive code snippet cards
showing each fix pattern.
### Demo
- **Runtime template** (e.g. `cookies()`):
https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/26-cookies-ssr-no-instant
- **Dynamic template** (e.g. uncached `fetch`):
https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/27-fetch-ssr-no-instant
### How?
**Overlay**
- New early-return path in `errors.tsx` for `blocking-route` errors
without refinement — renders `InstantRuntimeError` with CodeFrame →
description → technique cards → CallStack → ErrorCause
- `InstantGuidance` component with responsive CSS grid of fix technique
cards (3 per variant)
- Color-coded cards with colored borders and matching highlight text
(blue, purple, red)
- "Make route params static" card (runtime only) has a dashed border
indicating it's conditional
**Build & CLI messages**
- Build output messages extracted into `blocking-route-messages.ts` and
deduplicated across `dynamic-rendering.ts`
- `dynamicOrRuntimeBodyMessage` added for build-time static validation
where the specific cause can't be pinpointed — lists all APIs
(`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`,
`connection()`)
- `isRuntimeVariant()` replaces the old `includes('cookies()')`
heuristic which broke because both templates mention `cookies()`
- `logBuildDebugHint()` extracted and shared between
`logDisallowedDynamicError` and instant validation — adds "run `next
dev`" and "`next build --debug-prerender`" hints to instant validation
build output
Results:
<img width="2094" height="1478" alt="Google Chrome 2026-04-17 16 37 00"
src="https://github.com/user-attachments/assets/04f126c5-250c-4e6e-bad0-d6960496cd13"
/>
<img width="1978" height="1512" alt="Google Chrome 2026-04-17 16 36 37"
src="https://github.com/user-attachments/assets/46a502d8-9500-4055-814b-3efb739949db"
/>
---------
Co-authored-by: Janka Uryga <lolzatu2@gmail.com>
This moves `experimental.cacheComponents` to a top level config. As part
of this, I disabled some tests in `build-output-prerender` that assert
on `cacheComponents` appearing in the experimental list. In a separate
PR, I'm going to show that Cache Components is enabled next to the
bundler info.
This also updates some docs pages to remove "experimental" language.
## What?
Rename `experimental.dynamicIO` to `experimental.cacheComponents` across
the Next.js codebase.
## Why?
We're going to be merging the functionality of the `ppr`, `dynamicIO`
and `useCache` experimental flags into the singular `cacheComponents`
flag to reduce complexity of the codebase and simplify adoption for
users wanting to experiment with experimental features.
## How?
- Renamed the configuration option from `experimental.dynamicIO` to
`experimental.cacheComponents`
- Added deprecation handling with automatic migration for the old option
name
- Updated all documentation, tests, and internal references
- Updated Rust code in SWC transforms and Turbopack
- Maintained backward compatibility with deprecation warnings
NAR-158
Aurora Scharff