Add Instant Insights for prefetch() and navigation() (#97801)
Closes NAR-929 ## Summary - add render stages in validation so Instant Navigation validation can distinguish `prefetch()` from URL data - report `prefetch()` and `navigation()` consistently across route bodies, metadata, and viewport - show non-blocking findings as amber Instant Insights while keeping prerender failures as red errors - document navigation stages and cross-link the stable `prefetch()` and `navigation()` APIs from their references and the Optimizing Prefetching guide The DevTools cards, terminal guidance, and error pages use the same recommended fixes. Metadata guidance lets developers remove the stage API or confirm the delay from the page. Viewport guidance lets developers remove the API or disable validation with `instant = false`. ## Implementation notes Adds two new sub-stages that are only used for dynamic hole discrimination: - `PrefetchStatic_prefetch` (subset of `PrefetchStatic`) - `PrefetchRuntime_prefetch` (subset of `PrefetchRuntime`) The stages run before the semantic `PrefetchStatic` and `PrefetchRuntime` stages respectively. We resolve `prefetch()` resolves there in renders that produce validation error messages. the validation sequences map the stages to a prefetch() hole kind and produce a specialized error message, distinct from URL data. In non-validation renders, we skip the sub-stages and advance to `PrefetchStatic`/`PrefetchRuntime` directly, which resolves `prefetch()` in the same task as other URL data. We also reorganize `RENDER_STAGES_BY_DATA_KIND`. We have `staticUrlData['static' | 'runtime']` to separate data that is _semantically_ statically prerenderable (but may be deferred to a runtime stage for implementation reasons) from `runtimeUrlData`, which is never statically prerenderable. ## Preview scenarios - [`navigation()` outside of Suspense](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/119-navigation-body) - [`navigation()` in `generateMetadata()`](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/120-navigation-in-metadata) - [`navigation()` in `generateViewport()`](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/121-navigation-in-viewport) - [`prefetch()` outside of Suspense](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/122-prefetch-body) - [`prefetch()` in `generateMetadata()`](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/123-prefetch-in-metadata) - [`prefetch()` in `generateViewport()`](https://error-messages-overhaul-ibsl.labs.vercel.dev/scenario/124-prefetch-in-viewport) ## Verification - 145 focused DevTools unit tests - 108 Partial Prefetching Instant Validation tests, including 64 snapshots - 32 Instant Navigation DevTools tests - `pnpm --filter=next types` - `pnpm --filter=next build` - Documentation link validation passed <!-- NEXT_JS_LLM --> Co-authored-by:Janka Uryga <lolzatu2@gmail.com> Co-authored-by:
Claude Fable 5.1 <noreply@anthropic.com>
Showing
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Please
register
or
sign in
to comment