Unverified Commit 5ad38b43 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs(insights): restructure error pages and link to preview docs (#95193)

### 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 -->
parent 6a5dde61
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
...@@ -3,11 +3,29 @@ title: Next.js could not validate that a segment in your UI has instant navigati ...@@ -3,11 +3,29 @@ title: Next.js could not validate that a segment in your UI has instant navigati
kind: insight kind: insight
--- ---
During [prerendering](/docs/app/glossary#prerendering), a segment in the route tree was dropped from rendering. With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js validates that every segment can produce an [instant navigation](/docs/app/guides/instant-navigation). When a segment is not rendered, that validation can't run and issues that would prevent instant navigation go undetected. <div
style={{
padding: '1.25rem 1.5rem',
border: '1px solid var(--ds-gray-400)',
borderRadius: '12px',
background: 'var(--ds-background-200)',
margin: '1.5rem 0 2rem',
fontSize: '0.95rem',
lineHeight: '1.6',
}}
>
This Insight is part of the [Instant
Navigations](https://nextjs.org/blog/next-16-3-instant-navigations) feature
introduced in Next.js 16.3. If you're new to it, start with the [Ensuring
instant
navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation)
guide for an overview of what instant navigations are and how Next.js
validates them, then come back here for the specific fix.
</div>
This typically happens when a layout conditionally omits `{children}`, a parallel route slot is not rendered, or a Client Component opts out of rendering during SSR. During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), a segment in the route tree was dropped from rendering. With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js validates that every segment can produce an [instant navigation](https://preview.nextjs.org/docs/app/guides/instant-navigation). When a segment is not rendered, that validation can't run and issues that would prevent instant navigation go undetected.
> **Good to know**: In [`next dev`](/docs/app/api-reference/cli/next#next-dev-options), the error overlay points at the failing component. Run `next build --debug-prerender` to get the full list of blocking routes with stack traces. When iterating on specific routes, use `next build --debug-build-paths /dashboard /settings` to rebuild only those pages. This typically happens when a layout conditionally omits `{children}`, a parallel route slot is not rendered, or a Client Component opts out of rendering during SSR.
## Ways to fix this ## Ways to fix this
...@@ -64,7 +82,7 @@ export default function DashboardLayout({ children, modal }) { ...@@ -64,7 +82,7 @@ export default function DashboardLayout({ children, modal }) {
} }
``` ```
Learn more: [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes). Learn more: [Parallel Routes](https://preview.nextjs.org/docs/app/api-reference/file-conventions/parallel-routes).
#### Move auth or guard checks into the page #### Move auth or guard checks into the page
...@@ -92,7 +110,7 @@ export default async function DashboardPage() { ...@@ -92,7 +110,7 @@ export default async function DashboardPage() {
} }
``` ```
Learn more: [Authentication](/docs/app/guides/authentication). Learn more: [Authentication](https://preview.nextjs.org/docs/app/guides/authentication).
### Trade-off ### Trade-off
...@@ -105,7 +123,7 @@ The segment is always in the render tree, which means Next.js validates it on ev ...@@ -105,7 +123,7 @@ The segment is always in the render tree, which means Next.js validates it on ev
## Skip validation on the segment ## Skip validation on the segment
Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip validation for it. Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`instant`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip validation for it.
### Patterns ### Patterns
...@@ -121,7 +139,7 @@ export default function ModalPage() { ...@@ -121,7 +139,7 @@ export default function ModalPage() {
} }
``` ```
Learn more: [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant). Learn more: [Route segment `instant` config](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant).
### Trade-off ### Trade-off
...@@ -130,19 +148,19 @@ The segment is exempt from instant-navigation validation. If it has issues that ...@@ -130,19 +148,19 @@ The segment is exempt from instant-navigation validation. If it has issues that
### Gotchas ### Gotchas
- The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins. - The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins.
- Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](/docs/app/glossary#prerendering). The segment still prerenders if it can. It only silences the validation error. - Setting [`instant`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering). The segment still prerenders if it can. It only silences the validation error.
## Don't want this validation? ## Verifying the fix
After applying a fix, reload the route to confirm the [static shell](https://preview.nextjs.org/docs/app/glossary#static-shell) renders real content. A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary placed around the whole page body can pass validation with an empty shell, which defeats the point of an instant navigation.
Instant-navigation validation runs by default in [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents) apps and is what surfaces this error. In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next-dev-options), the error overlay points at the failing component with file paths and line numbers. When working from a build instead, the default [`next build`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next-build-options) output is more abbreviated; run `next build --debug-prerender` for full user-frame stack traces and `next build --debug-build-paths /dashboard /settings` to iterate on specific routes.
- **One segment**: add [`export const instant = false`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations. ## Don't want this validation?
- **Entire app**: set [`experimental.instantInsights.validationLevel`](/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. This limits validation to segments that explicitly export `instant`.
See [Ensuring instant navigations](/docs/app/guides/instant-navigation) for the full model. Instant-navigation validation runs by default in [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) apps and is what surfaces this error.
## Useful links - **One segment**: add [`export const instant = false`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to the page or layout file. This opts out the segment itself. Child segments are still validated during client navigations.
- **Entire app**: set [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults) to `'manual-warning'` in `next.config`. This limits validation to segments that explicitly export `instant`.
- [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes) See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
- [Ensuring instant navigations](/docs/app/guides/instant-navigation)
- [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment