Unverified Commit 6c5f3d57 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

Rename Copy as prompt to Copy prompt, convert FixOption to FixCard (#95309)

## 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 -->
parent 8cbc9269
--- ---
name: insight-error-page name: insight-error-page
description: Write or audit an insight-kind error page for the Next.js dev overlay. Use when creating a new `errors/<slug>.mdx` page, auditing an existing one, or checking that a page matches the framework fix cards. Covers page structure, title alignment, FixOption cards with Copy AI prompt button, code snippets, terminology verification against canonical docs, and Vercel technical writing style. description: Write or audit an insight-kind error page for the Next.js dev overlay. Use when creating a new `errors/<slug>.mdx` page, auditing an existing one, or checking that a page matches the framework fix cards. Covers page structure, title alignment, FixCard cards with Copy prompt button, code snippets, terminology verification against canonical docs, and Vercel technical writing style.
metadata: metadata:
internal: true internal: true
--- ---
...@@ -56,7 +56,7 @@ kind: insight ...@@ -56,7 +56,7 @@ kind: insight
## Ways to fix this ## Ways to fix this
<FixOption /> cards — one per framework card, in framework order <FixCardGrid> wrapping one <FixCard /> per framework card, in framework order
## <Card 1 title> ## <Card 1 title>
Choose this fix when ... Choose this fix when ...
...@@ -76,7 +76,8 @@ kind: insight ...@@ -76,7 +76,8 @@ kind: insight
## Don't want this validation? ## Don't want this validation?
(canonical opt-out block — see "Don't want this validation?" rule below) (canonical opt-out block — see "Don't want this validation?" rule below)
## Useful links ## Related Insights
(full list of every other insight-kind error page, current page omitted)
``` ```
## Rules (hard requirements) ## Rules (hard requirements)
...@@ -91,14 +92,16 @@ kind: insight ...@@ -91,14 +92,16 @@ kind: insight
- **Always the same canonical block** across all insight pages (the `--debug-prerender` tip). Never put page-specific content here. - **Always the same canonical block** across all insight pages (the `--debug-prerender` tip). Never put page-specific content here.
- Useful page-specific tips go in Gotchas under the relevant fix section. - Useful page-specific tips go in Gotchas under the relevant fix section.
### `<FixOption>` cards ### `<FixCard>` cards
- One per framework card, in the same order as the framework `FixCard[]` array. - Wrap all cards in a single `<FixCardGrid>` (the same component used in `docs/01-app/02-guides/instant-navigation.mdx`).
- One `<FixCard />` per framework card, in the same order as the framework `FixCard[]` array.
- `title` = card title from framework, **verbatim**. If it reads awkward as a heading, change the framework first — never the docs. - `title` = card title from framework, **verbatim**. If it reads awkward as a heading, change the framework first — never the docs.
- `href` = `#` + the auto-slug of the title (e.g. "Generate on every request" → `#generate-on-every-request`). This must match what the heading auto-generates. - `href` = `#` + the auto-slug of the title (e.g. "Generate on every request" → `#generate-on-every-request`). This must match what the heading auto-generates.
- `group` = card group from framework (`dynamic`, `cache`, `client`, `stream`, `defer`, `measure`, `block`, `render`, `silence`). - `group` = card group from framework (`dynamic`, `cache`, `client`, `stream`, `defer`, `measure`, `block`, `render`, `ignore`, `upgrade`, `disable`, `static`).
- Children = one-sentence plain-prose summary. **No inline code**, no API names in backticks, no snippets. Save technical detail for the section body. - `snippets` = the same `snippets` array as the matching framework `FixCard` in `instant-guidance-data.ts`. Copy it verbatim. No description prose lives on the card — the snippets carry the visual.
- **No `prompt` prop.** The "Copy AI prompt" button builds the prompt dynamically at click time from the page URL and the card's `title` + `href`. The agent receives a prompt that points at the rule docs and names the fix — it then reads the docs page (the same one the user is on) for every constraint and code shape. That is why this skill exists: the docs page itself **is** the prompt's source of truth. - Self-close the tag (`<FixCard ... />`). The card has no children.
- **No `prompt` prop.** The "Copy prompt" button builds the prompt dynamically at click time from the page URL and the card's `title` + `href`. The agent receives a prompt that points at the rule docs and names the fix — it then reads the docs page (the same one the user is on) for every constraint and code shape. That is why this skill exists: the docs page itself **is** the prompt's source of truth.
### `## <Fix>` sections ### `## <Fix>` sections
...@@ -124,8 +127,8 @@ kind: insight ...@@ -124,8 +127,8 @@ kind: insight
- Framing paragraph: link to sibling pages (client ↔ server counterpart, parallel API families). - Framing paragraph: link to sibling pages (client ↔ server counterpart, parallel API families).
- Gotchas: link to the `-client` page when warning about inline render in Client Components. - Gotchas: link to the `-client` page when warning about inline render in Client Components.
- Useful links: keep it short (typically 2–6 entries). Sibling error pages + the canonical [Ensuring instant navigations](/docs/app/guides/instant-navigation) guide + 1–3 API references central to the fixes but not already inline-linked throughout the body. Do not re-list every API the body mentions — those are inline-linked at first use and the section is for follow-on navigation, not an index. - Related Insights: the full list of every other insight-kind error page, current page omitted. This is an index of the Insight family, not a curated short list. Order: body errors → metadata/viewport → unstable-value errors (server then client) → navigation Insights. Do not add API references or guides to this section; those belong inline in the body where relevant.
- Every API reference and file convention must be inline-linked throughout, not reserved for Useful Links. - Every API reference and file convention must be inline-linked throughout, not reserved for the Related Insights section.
- **Cross-page pattern linking**: When a fix on one page is covered in depth on a sibling page, show only the most common pattern inline and link out to the sibling for the full set. For example, a server page's "Render on the client" fix shows one client pattern and links to the `-client` page; a client page's "Other options" section bridges to the server page's cache fix. Don't duplicate entire sections across sibling pages — keep each page lean and let the sibling be the canonical reference. - **Cross-page pattern linking**: When a fix on one page is covered in depth on a sibling page, show only the most common pattern inline and link out to the sibling for the full set. For example, a server page's "Render on the client" fix shows one client pattern and links to the `-client` page; a client page's "Other options" section bridges to the server page's cache fix. Don't duplicate entire sections across sibling pages — keep each page lean and let the sibling be the canonical reference.
- **First-party only**: link only to `nextjs.org/docs/*`, `react.dev/*`, `developer.mozilla.org/*`, and other canonical first-party references. **Never** link to personal blogs, community write-ups, conference talks, X/Bluesky posts, GitHub gists, or any third-party source — including the page author's own blog. If a third-party post inspired a pattern, internalize the idea and write it in our own voice without citation. Sibling error pages, our own docs, and primary API specs are the only acceptable destinations. - **First-party only**: link only to `nextjs.org/docs/*`, `react.dev/*`, `developer.mozilla.org/*`, and other canonical first-party references. **Never** link to personal blogs, community write-ups, conference talks, X/Bluesky posts, GitHub gists, or any third-party source — including the page author's own blog. If a third-party post inspired a pattern, internalize the idea and write it in our own voice without citation. Sibling error pages, our own docs, and primary API specs are the only acceptable destinations.
...@@ -166,7 +169,7 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list ( ...@@ -166,7 +169,7 @@ After the pattern snippets, include a "Use either pattern when:" bulleted list (
### Don't want this validation? ### Don't want this validation?
Every insight page ends (just before `## Useful links`) with the canonical opt-out block. It teaches the reader how to silence validation per-segment, subtree-wide, and app-wide, since instant-navigation validation runs by default in Cache Components apps. Copy verbatim: Every insight page ends (just before `## Related Insights`) with the canonical opt-out block. It teaches the reader how to silence validation per-segment, subtree-wide, and app-wide, since instant-navigation validation runs by default in Cache Components apps. Copy verbatim:
```mdx ```mdx
## Don't want this validation? ## Don't want this validation?
...@@ -196,12 +199,14 @@ When auditing an existing page, check every item: ...@@ -196,12 +199,14 @@ When auditing an existing page, check every item:
- [ ] `title` = literal dev-overlay headline (from factory function), no period - [ ] `title` = literal dev-overlay headline (from factory function), no period
- [ ] `kind: insight` in frontmatter - [ ] `kind: insight` in frontmatter
- [ ] Good to Know = the canonical `--debug-prerender` block (no page-specific content) - [ ] Good to Know = the canonical `--debug-prerender` block (no page-specific content)
- [ ] One `<FixOption>` per framework card, in framework order - [ ] All cards wrapped in a single `<FixCardGrid>`
- [ ] Every `<FixOption>` `title` = card title verbatim - [ ] One `<FixCard />` per framework card, in framework order
- [ ] Every `<FixOption>` `href` = auto-slug of the heading - [ ] Every `<FixCard />` `title` = card title verbatim
- [ ] Every `<FixOption>` `group` matches framework card group - [ ] Every `<FixCard />` `href` = `#` + auto-slug of the heading
- [ ] No `prompt` prop on any `<FixOption>` — the copy button generates the prompt from `title` + `href` + the page URL - [ ] Every `<FixCard />` `group` matches framework card group
- [ ] `<FixOption>` children: plain prose, no backticks, no inline code - [ ] Every `<FixCard />` `snippets` = the framework card's `snippets` array, verbatim
- [ ] No `prompt` prop on any `<FixCard />` — the copy button generates the prompt from `title` + `href` + the page URL
- [ ] `<FixCard />` is self-closing (no children, no description prose)
- [ ] Every `## <Fix>` heading = card title verbatim - [ ] Every `## <Fix>` heading = card title verbatim
- [ ] Every fix section has `### Patterns`, `### Trade-off`, `### Gotchas` - [ ] Every fix section has `### Patterns`, `### Trade-off`, `### Gotchas`
- [ ] No "Default." labels on patterns - [ ] No "Default." labels on patterns
...@@ -210,9 +215,9 @@ When auditing an existing page, check every item: ...@@ -210,9 +215,9 @@ When auditing an existing page, check every item:
- [ ] Code snippets are valid React (no inline `Math.random()` during render in Client Components) - [ ] Code snippets are valid React (no inline `Math.random()` during render in Client Components)
- [ ] `useState(() => Math.random())` warned against in Gotchas - [ ] `useState(() => Math.random())` warned against in Gotchas
- [ ] All API references inline-linked throughout - [ ] All API references inline-linked throughout
- [ ] Sibling pages cross-linked in framing paragraph + Useful links - [ ] Sibling pages cross-linked in framing paragraph (inline body links carry the bulk of API references)
- [ ] Useful links section is short (typically 2–6 entries). Does not re-list APIs that are already inline-linked in the body.
- [ ] `## Don't want this validation?` section present, verbatim per the canonical block - [ ] `## Don't want this validation?` section present, verbatim per the canonical block
- [ ] `## Related Insights` section present, listing every other insight-kind error page (current page omitted)
- [ ] Upstream `errors/<slug>.mdx` content preserved (relocated to Gotchas or Other options if needed) - [ ] Upstream `errors/<slug>.mdx` content preserved (relocated to Gotchas or Other options if needed)
- [ ] Terminology matches canonical docs (verified, not assumed) - [ ] Terminology matches canonical docs (verified, not assumed)
- [ ] Vercel technical writing style applied (no banned words, active voice, sentence-case headings) - [ ] Vercel technical writing style applied (no banned words, active voice, sentence-case headings)
......
...@@ -177,7 +177,6 @@ Cache Components validates this route automatically in development. If something ...@@ -177,7 +177,6 @@ Cache Components validates this route automatically in development. If something
{ text: 'async function Posts() {' }, { text: 'async function Posts() {' },
{ text: ' "use cache"', highlight: true }, { text: ' "use cache"', highlight: true },
{ text: ' return <List items={…} />' }, { text: ' return <List items={…} />' },
{ text: '}' },
]} ]}
/> />
<FixCard <FixCard
...@@ -192,7 +191,7 @@ Cache Components validates this route automatically in development. If something ...@@ -192,7 +191,7 @@ Cache Components validates this route automatically in development. If something
/> />
</FixCardGrid> </FixCardGrid>
> **Good to know:** Each fix card links to a detailed walkthrough with patterns, code samples, and trade-offs. Click a card to dive in. > **Good to know:** Each fix card links to a detailed walkthrough with patterns, code samples, and trade-offs. Click a card to dive in, or use **Copy prompt** to hand the fix to your agent. See [AI workflow](#ai-workflow) for the loop.
Validation runs on every page load using the real request from your browser, so dynamic params like `[slug]` are checked against actual values as you navigate. Validation runs on every page load using the real request from your browser, so dynamic params like `[slug]` are checked against actual values as you navigate.
......
...@@ -249,7 +249,6 @@ Cache Components validates your routes in development and surfaces errors and in ...@@ -249,7 +249,6 @@ Cache Components validates your routes in development and surfaces errors and in
{ text: 'async function Posts() {' }, { text: 'async function Posts() {' },
{ text: ' "use cache"', highlight: true }, { text: ' "use cache"', highlight: true },
{ text: ' return <List items={…} />' }, { text: ' return <List items={…} />' },
{ text: '}' },
]} ]}
/> />
<FixCard <FixCard
......
...@@ -27,27 +27,31 @@ During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering) ...@@ -27,27 +27,31 @@ During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering)
`useSearchParams` triggers this error on any prerendered route because search params come from the request URL. The other four hooks trigger it when the route has dynamic params and is rendered per-request. `useSearchParams` triggers this error on any prerendered route because search params come from the request URL. The other four hooks trigger it when the route has dynamic params and is rendered per-request.
Server-side request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers)) have different fixes. See [Next.js encountered runtime data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-runtime). For unstable values like [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in Client Components, see [Next.js encountered the unstable value Math.random() in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-random-client). Server-side request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers)) have different fixes. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime). For unstable values like [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in Client Components, see [Next.js encountered the unstable value Math.random() in a Client Component](/docs/messages/blocking-prerender-random-client).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="stream" <FixCard
href="#wrap-in-or-move-into-suspense" group="stream"
title="Wrap in or move into Suspense" title="Wrap in or move into Suspense"
> href="#wrap-in-or-move-into-suspense"
Wrap the component that calls the hook in a Suspense boundary so Next.js can snippets={[
prerender a fallback while the runtime value loads. { text: '<Suspense fallback={…}>', highlight: true },
</FixOption> { text: ' <SidebarNav />' },
{ text: '</Suspense>', highlight: true },
<FixOption ]}
group="block" />
href="#allow-blocking-route" <FixCard
title="Allow blocking route" group="block"
> title="Allow blocking route"
Opt the segment out of instant-navigation validation. The route renders on href="#allow-blocking-route"
every request. snippets={[
</FixOption> { text: '// page.tsx or layout.tsx' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Wrap in or move into Suspense ## Wrap in or move into Suspense
...@@ -264,3 +268,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -264,3 +268,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -23,29 +23,34 @@ kind: insight ...@@ -23,29 +23,34 @@ kind: insight
validates them, then come back here for the specific fix. validates them, then come back here for the specific fix.
</div> </div>
A [Client Component](https://preview.nextjs.org/docs/app/getting-started/server-and-client-components#using-client-components) called a synchronous [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) API that produces a random value ([`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID), [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)) inline during render, and the surrounding tree had no [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary. Client Components are server-side rendered on first load, so Next.js can't bake an unpredictable value into the prerendered HTML. The SSR value won't match the value the client computes on hydration, so you need to choose: defer the value behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary so SSR can stream it, or move the call into [`useEffect`](https://react.dev/reference/react/useEffect) (or an event handler) so it only runs on the client. A [Client Component](/docs/app/getting-started/server-and-client-components#using-client-components) called a synchronous [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) API that produces a random value ([`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID), [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)) inline during render, and the surrounding tree had no [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary. Client Components are server-side rendered on first load, so Next.js can't bake an unpredictable value into the prerendered HTML. The SSR value won't match the value the client computes on hydration, so you need to choose: defer the value behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary so SSR can stream it, or move the call into [`useEffect`](https://react.dev/reference/react/useEffect) (or an event handler) so it only runs on the client.
The Server Component case is handled at [Crypto APIs during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-crypto). Other unpredictable client-side APIs ([`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now)) have parallel error pages: [`Math.random()` in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-random-client) and [`Date.now()` in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-current-time-client). The Server Component case is handled at [Crypto APIs during prerendering](/docs/messages/blocking-prerender-crypto). Other unpredictable client-side APIs ([`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now)) have parallel error pages: [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client) and [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="stream" <FixCard
href="#wrap-in-or-move-into-suspense" group="stream"
title="Wrap in or move into Suspense" title="Wrap in or move into Suspense"
> href="#wrap-in-or-move-into-suspense"
Wrap the component in a Suspense boundary so the shell ships instantly and the snippets={[
value streams in. { text: '<Suspense fallback={…}>', highlight: true },
</FixOption> { text: ' <TokenId />' },
{ text: '</Suspense>', highlight: true },
<FixOption ]}
group="defer" />
href="#move-into-effect-or-event-handler" <FixCard
title="Move into effect or event handler" group="defer"
> title="Move into effect or event handler"
Defer the crypto call until after hydration so SSR and the browser agree on href="#move-into-effect-or-event-handler"
the initial render. snippets={[
</FixOption> { text: '<button onClick={() => {', highlight: true },
{ text: ' setId(crypto.randomUUID())' },
{ text: '}} />' },
]}
/>
</FixCardGrid>
## Wrap in or move into Suspense ## Wrap in or move into Suspense
...@@ -88,7 +93,7 @@ The component shows the fallback during SSR and the first paint. For above-the-f ...@@ -88,7 +93,7 @@ The component shows the fallback during SSR and the first paint. For above-the-f
### Gotchas ### Gotchas
- Any UI rendered as part of the prerender shell must be deterministic, including [`<Suspense>`](https://react.dev/reference/react/Suspense) fallbacks, [`loading.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/loading), [`error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error), [`not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found), and [`global-error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error#global-error). Calling a crypto API in any of them raises this same error. Use stable placeholder content. - Any UI rendered as part of the prerender shell must be deterministic, including [`<Suspense>`](https://react.dev/reference/react/Suspense) fallbacks, [`loading.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/loading), [`error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error), [`not-found.js`](/docs/app/api-reference/file-conventions/not-found), and [`global-error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error#global-error). Calling a crypto API in any of them raises this same error. Use stable placeholder content.
- The inner Client Component still runs during SSR, behind the boundary. If you need to guarantee the value only runs in the browser, use [Move into effect or event handler](#move-into-effect-or-event-handler) instead. - The inner Client Component still runs during SSR, behind the boundary. If you need to guarantee the value only runs in the browser, use [Move into effect or event handler](#move-into-effect-or-event-handler) instead.
- A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary only fixes the prerender/hydration mismatch, not client re-renders. If the component using the crypto API re-renders on the client (a parent state change, a context update), it produces a new value each time. To stabilize the value across re-renders, call the crypto API once in a [`useState`](https://react.dev/reference/react/useState) initializer or [`useRef`](https://react.dev/reference/react/useRef), or compute it on the server and pass it down as a prop. - A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary only fixes the prerender/hydration mismatch, not client re-renders. If the component using the crypto API re-renders on the client (a parent state change, a context update), it produces a new value each time. To stabilize the value across re-renders, call the crypto API once in a [`useState`](https://react.dev/reference/react/useState) initializer or [`useRef`](https://react.dev/reference/react/useRef), or compute it on the server and pass it down as a prop.
...@@ -189,7 +194,7 @@ The user sees the placeholder briefly before the real value. For interactions th ...@@ -189,7 +194,7 @@ The user sees the placeholder briefly before the real value. For interactions th
- Don't compute the value inline during render with a lazy initializer like `useState(() => crypto.randomUUID())`. The initializer still runs during SSR and triggers the error. - Don't compute the value inline during render with a lazy initializer like `useState(() => crypto.randomUUID())`. The initializer still runs during SSR and triggers the error.
- If the value needs to be hydration-stable, use [Wrap in or move into Suspense](#wrap-in-or-move-into-suspense) instead. - If the value needs to be hydration-stable, use [Wrap in or move into Suspense](#wrap-in-or-move-into-suspense) instead.
- Only [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) ships to the browser. Node-only APIs (`crypto.randomBytes`, `crypto.generateKeyPairSync`) are not available on the client. If you're seeing this error for one of those, the call lives on the server: see [Crypto APIs during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-crypto). - Only [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Crypto) ships to the browser. Node-only APIs (`crypto.randomBytes`, `crypto.generateKeyPairSync`) are not available on the client. If you're seeing this error for one of those, the call lives on the server: see [Crypto APIs during prerendering](/docs/messages/blocking-prerender-crypto).
- When you call `setState` from inside [`useEffect`](https://react.dev/reference/react/useEffect), wrap it in [`startTransition`](https://react.dev/reference/react/startTransition). Cascading state updates during hydration can cause an outer [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary's fallback to briefly flash. `startTransition` marks the update as non-blocking so React keeps the existing UI in place while the new value resolves. - When you call `setState` from inside [`useEffect`](https://react.dev/reference/react/useEffect), wrap it in [`startTransition`](https://react.dev/reference/react/startTransition). Cascading state updates during hydration can cause an outer [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary's fallback to briefly flash. `startTransition` marks the update as non-blocking so React keeps the existing UI in place while the new value resolves.
## Other options ## Other options
...@@ -235,3 +240,20 @@ In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next- ...@@ -235,3 +240,20 @@ In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next-
## Why `instant = false` doesn't clear this error ## Why `instant = false` doesn't clear this error
This error fires from the prerender, not from instant-navigation validation. `crypto.randomUUID()` and related APIs return a different value on every call, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above. This error fires from the prerender, not from instant-navigation validation. `crypto.randomUUID()` and related APIs return a different value on every call, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
This diff is collapsed.
...@@ -23,38 +23,44 @@ kind: insight ...@@ -23,38 +23,44 @@ kind: insight
validates them, then come back here for the specific fix. validates them, then come back here for the specific fix.
</div> </div>
A [Client Component](https://preview.nextjs.org/docs/app/getting-started/server-and-client-components#using-client-components) called [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now), [`Date()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), or [`new Date()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) inline during render, and the surrounding tree had no [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary. Client Components are server-side rendered on first load, so Next.js can't bake "now" into the prerendered HTML. The SSR timestamp won't match the value the client computes on hydration, so you need to choose: defer the value behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary so SSR can stream it, or move the call into [`useEffect`](https://react.dev/reference/react/useEffect) (or an event handler) so it only runs on the client. A [Client Component](/docs/app/getting-started/server-and-client-components#using-client-components) called [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now), [`Date()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), or [`new Date()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) inline during render, and the surrounding tree had no [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary. Client Components are server-side rendered on first load, so Next.js can't bake "now" into the prerendered HTML. The SSR timestamp won't match the value the client computes on hydration, so you need to choose: defer the value behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary so SSR can stream it, or move the call into [`useEffect`](https://react.dev/reference/react/useEffect) (or an event handler) so it only runs on the client.
The Server Component case is handled at [`Date.now()` during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-current-time). Other unpredictable client-side APIs ([`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)) have parallel error pages: [`Math.random()` in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-random-client) and [Crypto APIs in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-crypto-client). The Server Component case is handled at [`Date.now()` during prerendering](/docs/messages/blocking-prerender-current-time). Other unpredictable client-side APIs ([`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random), [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)) have parallel error pages: [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client) and [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="stream" <FixCard
href="#wrap-in-or-move-into-suspense" group="stream"
title="Wrap in or move into Suspense" title="Wrap in or move into Suspense"
> href="#wrap-in-or-move-into-suspense"
Wrap the component in a Suspense boundary so the shell ships instantly and the snippets={[
timestamp streams in. { text: '<Suspense fallback={…}>', highlight: true },
</FixOption> { text: ' <DateDisplay />' },
{ text: '</Suspense>', highlight: true },
<FixOption ]}
group="defer" />
href="#move-into-effect-or-event-handler" <FixCard
title="Move into effect or event handler" group="defer"
> title="Move into effect or event handler"
Defer the timestamp read until after hydration so SSR and the browser agree on href="#move-into-effect-or-event-handler"
the initial render. snippets={[
</FixOption> { text: '<button onClick={() => {', highlight: true },
{ text: ' setT(Date.now())' },
<FixOption { text: '}} />' },
group="measure" ]}
href="#for-telemetry-use-a-timing-api" />
title="For telemetry, use a timing API" <FixCard
> group="measure"
When the timestamp is only used for measuring durations, switch to title="For telemetry, use a timing API"
performance.now(). href="#for-telemetry-use-a-timing-api"
</FixOption> snippets={[
{ text: 'const start = performance.now()', highlight: true },
{ text: 'doWork()' },
{ text: 'const ms = performance.now() - start' },
]}
/>
</FixCardGrid>
## Wrap in or move into Suspense ## Wrap in or move into Suspense
...@@ -100,7 +106,7 @@ The component shows the fallback during SSR and the first paint. For above-the-f ...@@ -100,7 +106,7 @@ The component shows the fallback during SSR and the first paint. For above-the-f
### Gotchas ### Gotchas
- Any UI rendered as part of the prerender shell must be deterministic, including [`<Suspense>`](https://react.dev/reference/react/Suspense) fallbacks, [`loading.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/loading), [`error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error), [`not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found), and [`global-error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error#global-error). Calling [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) in any of them raises this same error. Use stable placeholder content. - Any UI rendered as part of the prerender shell must be deterministic, including [`<Suspense>`](https://react.dev/reference/react/Suspense) fallbacks, [`loading.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/loading), [`error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error), [`not-found.js`](/docs/app/api-reference/file-conventions/not-found), and [`global-error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error#global-error). Calling [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) in any of them raises this same error. Use stable placeholder content.
- The inner Client Component still runs during SSR, behind the boundary. If you need to guarantee the timestamp only runs in the browser, use [Move into effect or event handler](#move-into-effect-or-event-handler) instead. - The inner Client Component still runs during SSR, behind the boundary. If you need to guarantee the timestamp only runs in the browser, use [Move into effect or event handler](#move-into-effect-or-event-handler) instead.
- A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary only fixes the prerender/hydration mismatch, not client re-renders. If the component using [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) re-renders on the client (a parent state change, a context update), it reads a fresh timestamp each time. To stabilize the value across re-renders, capture [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) once in a [`useState`](https://react.dev/reference/react/useState) initializer or [`useRef`](https://react.dev/reference/react/useRef), or compute it on the server and pass it down as a prop. - A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary only fixes the prerender/hydration mismatch, not client re-renders. If the component using [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) re-renders on the client (a parent state change, a context update), it reads a fresh timestamp each time. To stabilize the value across re-renders, capture [`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now) once in a [`useState`](https://react.dev/reference/react/useState) initializer or [`useRef`](https://react.dev/reference/react/useRef), or compute it on the server and pass it down as a prop.
...@@ -233,7 +239,7 @@ export default async function Layout({ children }) { ...@@ -233,7 +239,7 @@ export default async function Layout({ children }) {
} }
``` ```
Learn more: [`Date.now()` during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-current-time). Learn more: [`Date.now()` during prerendering](/docs/messages/blocking-prerender-current-time).
### Suspend with `use(io())` ### Suspend with `use(io())`
...@@ -276,3 +282,20 @@ In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next- ...@@ -276,3 +282,20 @@ In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next-
## Why `instant = false` doesn't clear this error ## Why `instant = false` doesn't clear this error
This error fires from the prerender, not from instant-navigation validation. `new Date()` and `Date.now()` return a different value on every render, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above. This error fires from the prerender, not from instant-navigation validation. `new Date()` and `Date.now()` return a different value on every render, so the prerender can't bake them into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
This diff is collapsed.
...@@ -25,38 +25,43 @@ kind: insight ...@@ -25,38 +25,43 @@ kind: insight
During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), a [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) request, database call, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection), or other asynchronous IO ran outside of [`<Suspense>`](https://react.dev/reference/react/Suspense). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js can't prerender the part of the tree that depends on this data, so navigations to this route block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation). During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), a [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch) request, database call, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection), or other asynchronous IO ran outside of [`<Suspense>`](https://react.dev/reference/react/Suspense). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js can't prerender the part of the tree that depends on this data, so navigations to this route block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation).
Request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)) have different fixes. See [Next.js encountered runtime data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-runtime). Request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)) have different fixes. See [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime).
This error can also appear during a client-side navigation when the data access sits inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary from a parent layout but that boundary is too high. It wraps the entire segment instead of only the dynamic part, so the navigation still blocks. Push the boundary closer to the data access so the rest of the segment stays in the [static shell](https://preview.nextjs.org/docs/app/glossary#static-shell). See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary). This error can also appear during a client-side navigation when the data access sits inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary from a parent layout but that boundary is too high. It wraps the entire segment instead of only the dynamic part, so the navigation still blocks. Push the boundary closer to the data access so the rest of the segment stays in the [static shell](https://preview.nextjs.org/docs/app/glossary#static-shell). See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="stream" <FixCard
href="#wrap-in-or-move-into-suspense" group="stream"
title="Wrap in or move into Suspense" title="Wrap in or move into Suspense"
> href="#wrap-in-or-move-into-suspense"
Wrap the data-accessing component in a Suspense boundary. The shell ships snippets={[
instantly and the data streams in. { text: '<Suspense fallback={…}>', highlight: true },
</FixOption> { text: ' <DataChild />' },
{ text: '</Suspense>', highlight: true },
<FixOption ]}
group="cache" />
href="#cache-the-component-or-data" <FixCard
title="Cache the component or data" group="cache"
> title="Cache the component or data"
Move the data access into a cached function so the result is reused and the href="#cache-the-component-or-data"
route stays prerenderable. snippets={[
</FixOption> { text: 'async function Posts() {' },
{ text: ' "use cache"', highlight: true },
<FixOption { text: ' return <List items={…} />' },
group="block" ]}
href="#allow-blocking-route" />
title="Allow blocking route" <FixCard
> group="block"
Opt this segment out of instant navigation. The route has no static shell and title="Allow blocking route"
every navigation blocks until the render completes. href="#allow-blocking-route"
</FixOption> snippets={[
{ text: '// page.tsx or layout.tsx' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Wrap in or move into Suspense ## Wrap in or move into Suspense
...@@ -221,7 +226,7 @@ Learn more: [Caching with `use cache`](https://preview.nextjs.org/docs/app/api-r ...@@ -221,7 +226,7 @@ Learn more: [Caching with `use cache`](https://preview.nextjs.org/docs/app/api-r
#### Tag the cache for targeted invalidation #### Tag the cache for targeted invalidation
Choose this when you want control over when the cached value is refreshed. Tag the entry with [`cacheTag`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheTag) and invalidate it on demand: call [`updateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/updateTag) from a [Server Action](https://preview.nextjs.org/docs/app/getting-started/mutating-data) when the user performed the mutation and should see fresh data on the next request, or [`revalidateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/revalidateTag) from a route handler, cron, admin tool, or incoming webhook for stale-while-revalidate refreshes. Tags add an on-demand invalidation path on top of the [`cacheLife`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheLife) expiration window; the two are independent. Choose this when you want control over when the cached value is refreshed. Tag the entry with [`cacheTag`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheTag) and invalidate it on demand: call [`updateTag`](/docs/app/api-reference/functions/updateTag) from a [Server Action](https://preview.nextjs.org/docs/app/getting-started/mutating-data) when the user performed the mutation and should see fresh data on the next request, or [`revalidateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/revalidateTag) from a route handler, cron, admin tool, or incoming webhook for stale-while-revalidate refreshes. Tags add an on-demand invalidation path on top of the [`cacheLife`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheLife) expiration window; the two are independent.
```jsx filename="app/dashboard/page.js" ```jsx filename="app/dashboard/page.js"
import { cacheTag } from 'next/cache' import { cacheTag } from 'next/cache'
...@@ -253,7 +258,7 @@ Learn more: [How to configure cache lifetimes](https://preview.nextjs.org/docs/a ...@@ -253,7 +258,7 @@ Learn more: [How to configure cache lifetimes](https://preview.nextjs.org/docs/a
### Trade-off ### Trade-off
Freshness becomes a property of the cache configuration, not the data source. The cached response is reused until [`cacheLife`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheLife) revalidates or expires, or until [`cacheTag`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheTag) is invalidated. Plan invalidations alongside the code that mutates the data. Call [`updateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/updateTag) from a [Server Action](https://preview.nextjs.org/docs/app/getting-started/mutating-data) when the user performed the mutation and should see fresh data on the next request, or [`revalidateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/revalidateTag) from a route handler, cron, or webhook for stale-while-revalidate refreshes. Freshness becomes a property of the cache configuration, not the data source. The cached response is reused until [`cacheLife`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheLife) revalidates or expires, or until [`cacheTag`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheTag) is invalidated. Plan invalidations alongside the code that mutates the data. Call [`updateTag`](/docs/app/api-reference/functions/updateTag) from a [Server Action](https://preview.nextjs.org/docs/app/getting-started/mutating-data) when the user performed the mutation and should see fresh data on the next request, or [`revalidateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/revalidateTag) from a route handler, cron, or webhook for stale-while-revalidate refreshes.
### Gotchas ### Gotchas
...@@ -333,3 +338,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -333,3 +338,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -25,27 +25,35 @@ kind: insight ...@@ -25,27 +25,35 @@ kind: insight
During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateMetadata()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-metadata) performed an uncached data access ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database call, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js expects metadata to be prerenderable when the rest of the route is. This route's metadata is blocked, but the rest of its content can be prerendered. During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateMetadata()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-metadata) performed an uncached data access ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database call, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js expects metadata to be prerenderable when the rest of the route is. This route's metadata is blocked, but the rest of its content can be prerendered.
Request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)) in `generateMetadata()` have different fixes. See [Next.js encountered runtime data in `generateMetadata()`](https://preview.nextjs.org/docs/messages/blocking-prerender-metadata-runtime). Request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)) in `generateMetadata()` have different fixes. See [Next.js encountered runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime).
The viewport equivalent is handled at [Uncached data in `generateViewport()`](https://preview.nextjs.org/docs/messages/blocking-prerender-viewport-dynamic). The viewport equivalent is handled at [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic).
For errors in the page body rather than metadata, see [Next.js encountered uncached data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-dynamic). For errors in the page body rather than metadata, see [Next.js encountered uncached data during prerendering](/docs/messages/blocking-prerender-dynamic).
## Ways to fix this ## Ways to fix this
<FixOption group="cache" href="#cache-the-metadata" title="Cache the metadata"> <FixCardGrid>
Cache the metadata function so the result is reused and the route stays <FixCard
prerenderable. group="cache"
</FixOption> title="Cache the metadata"
href="#cache-the-metadata"
<FixOption snippets={[
group="dynamic" { text: 'async function generateMetadata() {' },
href="#mark-the-route-as-dynamic" { text: ' "use cache"', highlight: true },
title="Mark the route as dynamic" { text: ' return await cms.getMeta(…)' },
> ]}
Tell Next.js the page itself has dynamic content, so the dynamic metadata is />
allowed. <FixCard
</FixOption> group="dynamic"
title="Mark the route as dynamic"
href="#mark-the-route-as-dynamic"
snippets={[
{ text: '// page.tsx or layout.tsx' },
{ text: 'await connection()', highlight: true },
]}
/>
</FixCardGrid>
## Cache the metadata ## Cache the metadata
...@@ -86,7 +94,7 @@ Learn more: [Caching with `use cache`](https://preview.nextjs.org/docs/app/api-r ...@@ -86,7 +94,7 @@ Learn more: [Caching with `use cache`](https://preview.nextjs.org/docs/app/api-r
#### Tag the metadata for invalidation #### Tag the metadata for invalidation
When you publish new content and want the metadata to refresh, tag the entry with [`cacheTag`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheTag). Invalidate from a Server Action with [`updateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/updateTag) (read-your-own-writes: the next request waits for fresh data) or from a Route Handler with [`revalidateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/revalidateTag). When you publish new content and want the metadata to refresh, tag the entry with [`cacheTag`](https://preview.nextjs.org/docs/app/api-reference/functions/cacheTag). Invalidate from a Server Action with [`updateTag`](/docs/app/api-reference/functions/updateTag) (read-your-own-writes: the next request waits for fresh data) or from a Route Handler with [`revalidateTag`](https://preview.nextjs.org/docs/app/api-reference/functions/revalidateTag).
```jsx filename="app/blog/[slug]/page.js" ```jsx filename="app/blog/[slug]/page.js"
import { cacheTag } from 'next/cache' import { cacheTag } from 'next/cache'
...@@ -163,7 +171,7 @@ The metadata and the dynamic marker run on every request, so the route cannot be ...@@ -163,7 +171,7 @@ The metadata and the dynamic marker run on every request, so the route cannot be
- The `DynamicMarker` must be wrapped in [`<Suspense>`](https://react.dev/reference/react/Suspense). Without the boundary, the dynamic marker propagates up and the entire page is treated as blocking, surfacing the same blocking-route error this fix is meant to address. - The `DynamicMarker` must be wrapped in [`<Suspense>`](https://react.dev/reference/react/Suspense). Without the boundary, the dynamic marker propagates up and the entire page is treated as blocking, surfacing the same blocking-route error this fix is meant to address.
- This pattern is intentionally verbose. If you find yourself adding a dynamic marker, reconsider whether the metadata can be cached instead. Most metadata doesn't need to be per-request. - This pattern is intentionally verbose. If you find yourself adding a dynamic marker, reconsider whether the metadata can be cached instead. Most metadata doesn't need to be per-request.
- If the page already has a genuinely dynamic component (one that reads [`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies) or uncached data inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary), you won't see this error. The page is already partially dynamic. - If the page already has a genuinely dynamic component (one that reads [`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies) or uncached data inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary), you won't see this error. The page is already partially dynamic.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateMetadata` and must be statically prerendered. The dynamic marker doesn't help here, because these routes don't have a page body where you can place a Suspense'd marker. If your root layout's `generateMetadata` depends on uncached data, [Cache the metadata](#cache-the-metadata) instead, or move to [`global-not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateMetadata`. - Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateMetadata` and must be statically prerendered. The dynamic marker doesn't help here, because these routes don't have a page body where you can place a Suspense'd marker. If your root layout's `generateMetadata` depends on uncached data, [Cache the metadata](#cache-the-metadata) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateMetadata`.
## Verifying the fix ## Verifying the fix
...@@ -179,3 +187,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -179,3 +187,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -25,31 +25,35 @@ kind: insight ...@@ -25,31 +25,35 @@ kind: insight
During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateMetadata()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-metadata) or file-based metadata read a per-request value ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js expects metadata to be prerenderable when the rest of the route is. This route's metadata is blocked, but the rest of its content can be prerendered. During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateMetadata()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-metadata) or file-based metadata read a per-request value ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js expects metadata to be prerenderable when the rest of the route is. This route's metadata is blocked, but the rest of its content can be prerendered.
Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)) in `generateMetadata()` have different fixes. See [Next.js encountered uncached data in `generateMetadata()`](https://preview.nextjs.org/docs/messages/blocking-prerender-metadata-dynamic). Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)) in `generateMetadata()` have different fixes. See [Next.js encountered uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic).
The viewport equivalent is handled at [Runtime data in `generateViewport()`](https://preview.nextjs.org/docs/messages/blocking-prerender-viewport-runtime). The viewport equivalent is handled at [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime).
For errors in the page body rather than metadata, see [Next.js encountered runtime data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-runtime). For errors in the page body rather than metadata, see [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="static" <FixCard
href="#use-static-metadata" group="static"
title="Use static metadata" title="Use static metadata"
> href="#use-static-metadata"
Replace the dynamic function with a static export so the metadata is known at snippets={[
build time. { text: 'export const metadata = {', highlight: true },
</FixOption> { text: ' title: "My Page"' },
{ text: '}' },
<FixOption ]}
group="dynamic" />
href="#mark-the-route-as-dynamic" <FixCard
title="Mark the route as dynamic" group="dynamic"
> title="Mark the route as dynamic"
Tell Next.js the page itself has dynamic content, so the dynamic metadata is href="#mark-the-route-as-dynamic"
allowed. snippets={[
</FixOption> { text: '// page.tsx or layout.tsx' },
{ text: 'await connection()', highlight: true },
]}
/>
</FixCardGrid>
## Use static metadata ## Use static metadata
...@@ -99,7 +103,7 @@ Static metadata can't reflect per-request values like the visitor's locale, A/B ...@@ -99,7 +103,7 @@ Static metadata can't reflect per-request values like the visitor's locale, A/B
### Gotchas ### Gotchas
- File-based metadata (e.g. an [`icon.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/metadata/app-icons) or [`opengraph-image.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image) inside a dynamic segment) implicitly depends on `params`. If the segment is dynamic, Next.js treats the metadata function as dynamic too. Pair with [`generateStaticParams`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-static-params) or switch to a static file (e.g. `icon.png`). - File-based metadata (e.g. an [`icon.js`](/docs/app/api-reference/file-conventions/metadata/app-icons) or [`opengraph-image.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image) inside a dynamic segment) implicitly depends on `params`. If the segment is dynamic, Next.js treats the metadata function as dynamic too. Pair with [`generateStaticParams`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-static-params) or switch to a static file (e.g. `icon.png`).
- A [`template`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-metadata#template) in a parent layout's metadata applies at build time. It doesn't introduce a dynamic dependency. - A [`template`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-metadata#template) in a parent layout's metadata applies at build time. It doesn't introduce a dynamic dependency.
## Mark the route as dynamic ## Mark the route as dynamic
...@@ -156,7 +160,7 @@ The metadata and the dynamic marker run on every request, so the route cannot be ...@@ -156,7 +160,7 @@ The metadata and the dynamic marker run on every request, so the route cannot be
- The `DynamicMarker` must be wrapped in [`<Suspense>`](https://react.dev/reference/react/Suspense). Without the boundary, the dynamic marker propagates up and the entire page is treated as blocking, surfacing the same blocking-route error this fix is meant to address. - The `DynamicMarker` must be wrapped in [`<Suspense>`](https://react.dev/reference/react/Suspense). Without the boundary, the dynamic marker propagates up and the entire page is treated as blocking, surfacing the same blocking-route error this fix is meant to address.
- This pattern is intentionally verbose. If you find yourself adding a dynamic marker, reconsider whether the metadata can be cached instead. Most metadata doesn't need to be per-request. - This pattern is intentionally verbose. If you find yourself adding a dynamic marker, reconsider whether the metadata can be cached instead. Most metadata doesn't need to be per-request.
- If the page already has a genuinely dynamic component (one that reads [`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies) or [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers) inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary), you won't see this error. The page is already partially dynamic. - If the page already has a genuinely dynamic component (one that reads [`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies) or [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers) inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary), you won't see this error. The page is already partially dynamic.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateMetadata` and must be statically prerendered. The dynamic marker doesn't help here, because these routes don't have a page body where you can place a Suspense'd marker. If your root layout's `generateMetadata` depends on request data, [Use static metadata](#use-static-metadata) instead, or move to [`global-not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateMetadata`. - Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateMetadata` and must be statically prerendered. The dynamic marker doesn't help here, because these routes don't have a page body where you can place a Suspense'd marker. If your root layout's `generateMetadata` depends on request data, [Use static metadata](#use-static-metadata) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateMetadata`.
## Verifying the fix ## Verifying the fix
...@@ -172,3 +176,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -172,3 +176,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -23,29 +23,34 @@ kind: insight ...@@ -23,29 +23,34 @@ kind: insight
validates them, then come back here for the specific fix. validates them, then come back here for the specific fix.
</div> </div>
A [Client Component](https://preview.nextjs.org/docs/app/getting-started/server-and-client-components#using-client-components) called [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) inline during render, and the surrounding tree had no [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary. Client Components are server-side rendered on first load, so Next.js can't bake an unpredictable value into the prerendered HTML. The SSR value won't match the value the client computes on hydration, so you need to choose: defer the value behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary so SSR can stream it, or move the call into [`useEffect`](https://react.dev/reference/react/useEffect) (or an event handler) so it only runs on the client. A [Client Component](/docs/app/getting-started/server-and-client-components#using-client-components) called [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) inline during render, and the surrounding tree had no [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary. Client Components are server-side rendered on first load, so Next.js can't bake an unpredictable value into the prerendered HTML. The SSR value won't match the value the client computes on hydration, so you need to choose: defer the value behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary so SSR can stream it, or move the call into [`useEffect`](https://react.dev/reference/react/useEffect) (or an event handler) so it only runs on the client.
The Server Component case is handled at [`Math.random()` during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-random). Other unpredictable client-side APIs ([`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now), [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)) have parallel error pages: [`Date.now()` in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-current-time-client) and [Crypto APIs in a Client Component](https://preview.nextjs.org/docs/messages/blocking-prerender-crypto-client). The Server Component case is handled at [`Math.random()` during prerendering](/docs/messages/blocking-prerender-random). Other unpredictable client-side APIs ([`Date.now()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now), [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)) have parallel error pages: [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client) and [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="stream" <FixCard
href="#wrap-in-or-move-into-suspense" group="stream"
title="Wrap in or move into Suspense" title="Wrap in or move into Suspense"
> href="#wrap-in-or-move-into-suspense"
Wrap the component in a Suspense boundary so the shell ships instantly and the snippets={[
random value streams in. { text: '<Suspense fallback={…}>', highlight: true },
</FixOption> { text: ' <RandomId />' },
{ text: '</Suspense>', highlight: true },
<FixOption ]}
group="defer" />
href="#move-into-effect-or-event-handler" <FixCard
title="Move into effect or event handler" group="defer"
> title="Move into effect or event handler"
Defer the random read until after hydration so SSR and the browser agree on href="#move-into-effect-or-event-handler"
the initial render. snippets={[
</FixOption> { text: '<button onClick={() => {', highlight: true },
{ text: ' setId(Math.random())' },
{ text: '}} />' },
]}
/>
</FixCardGrid>
## Wrap in or move into Suspense ## Wrap in or move into Suspense
...@@ -89,7 +94,7 @@ The component shows the fallback during SSR and the first paint. For above-the-f ...@@ -89,7 +94,7 @@ The component shows the fallback during SSR and the first paint. For above-the-f
### Gotchas ### Gotchas
- Any UI rendered as part of the prerender shell must be deterministic, including [`<Suspense>`](https://react.dev/reference/react/Suspense) fallbacks, [`loading.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/loading), [`error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error), [`not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found), and [`global-error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error#global-error). Calling [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in any of them raises this same error. Use stable placeholder content. - Any UI rendered as part of the prerender shell must be deterministic, including [`<Suspense>`](https://react.dev/reference/react/Suspense) fallbacks, [`loading.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/loading), [`error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error), [`not-found.js`](/docs/app/api-reference/file-conventions/not-found), and [`global-error.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/error#global-error). Calling [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) in any of them raises this same error. Use stable placeholder content.
- The inner Client Component still runs during SSR, behind the boundary. If you need to guarantee the random value only runs in the browser, use [Move into effect or event handler](#move-into-effect-or-event-handler) instead. - The inner Client Component still runs during SSR, behind the boundary. If you need to guarantee the random value only runs in the browser, use [Move into effect or event handler](#move-into-effect-or-event-handler) instead.
- A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary only fixes the prerender/hydration mismatch, not client re-renders. If the component using [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) re-renders on the client (a parent state change, a context update), it produces a new value each time. To stabilize the value across re-renders, call [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) once in a [`useState`](https://react.dev/reference/react/useState) initializer or [`useRef`](https://react.dev/reference/react/useRef), or compute it on the server and pass it down as a prop. - A [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary only fixes the prerender/hydration mismatch, not client re-renders. If the component using [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) re-renders on the client (a parent state change, a context update), it produces a new value each time. To stabilize the value across re-renders, call [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) once in a [`useState`](https://react.dev/reference/react/useState) initializer or [`useRef`](https://react.dev/reference/react/useRef), or compute it on the server and pass it down as a prop.
...@@ -228,3 +233,20 @@ In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next- ...@@ -228,3 +233,20 @@ In [`next dev`](https://preview.nextjs.org/docs/app/api-reference/cli/next#next-
## Why `instant = false` doesn't clear this error ## Why `instant = false` doesn't clear this error
This error fires from the prerender, not from instant-navigation validation. `Math.random()` returns a different value on every render, so the prerender can't bake it into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above. This error fires from the prerender, not from instant-navigation validation. `Math.random()` returns a different value on every render, so the prerender can't bake it into a static shell regardless of the segment's `instant` config or [`experimental.instantInsights.validationLevel`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant#configuring-validation-defaults). Use one of the fixes above.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
This diff is collapsed.
...@@ -25,29 +25,33 @@ kind: insight ...@@ -25,29 +25,33 @@ kind: insight
During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional) was read outside of [`<Suspense>`](https://react.dev/reference/react/Suspense). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js can't prerender any part of the tree that depends on a per-request value, so navigations to this route block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation). During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), or [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional) was read outside of [`<Suspense>`](https://react.dev/reference/react/Suspense). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, Next.js can't prerender any part of the tree that depends on a per-request value, so navigations to this route block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation).
Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)) have different fixes. See [Next.js encountered uncached data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-dynamic). Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)) have different fixes. See [Next.js encountered uncached data during prerendering](/docs/messages/blocking-prerender-dynamic).
This error can also appear during a client-side navigation when the data access sits inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary from a parent layout but that boundary is too high. It wraps the entire segment instead of only the dynamic part, so the navigation still blocks. Push the boundary closer to the data access so the rest of the segment stays in the [static shell](https://preview.nextjs.org/docs/app/glossary#static-shell). See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary). This error can also appear during a client-side navigation when the data access sits inside a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary from a parent layout but that boundary is too high. It wraps the entire segment instead of only the dynamic part, so the navigation still blocks. Push the boundary closer to the data access so the rest of the segment stays in the [static shell](https://preview.nextjs.org/docs/app/glossary#static-shell). See [Choosing where to place the boundary](#choosing-where-to-place-the-boundary).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="stream" <FixCard
href="#wrap-in-or-move-into-suspense" group="stream"
title="Wrap in or move into Suspense" title="Wrap in or move into Suspense"
> href="#wrap-in-or-move-into-suspense"
Wrap the component that reads the request-time value in a Suspense boundary, snippets={[
or push the read down to the leaf that needs it. { text: '<Suspense fallback={…}>', highlight: true },
</FixOption> { text: ' <DataChild />' },
{ text: '</Suspense>', highlight: true },
<FixOption ]}
group="block" />
href="#allow-blocking-route" <FixCard
title="Allow blocking route" group="block"
> title="Allow blocking route"
Opt this segment out of instant navigation. The route has no static shell and href="#allow-blocking-route"
every navigation blocks until the render completes. snippets={[
</FixOption> { text: '// page.tsx or layout.tsx' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Wrap in or move into Suspense ## Wrap in or move into Suspense
...@@ -256,3 +260,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -256,3 +260,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -25,27 +25,31 @@ kind: insight ...@@ -25,27 +25,31 @@ kind: insight
During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateViewport()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-viewport) performed an uncached data access ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database call, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, viewport metadata can't be deferred behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary because it affects the initial page load. The page can't be prerendered, so navigations block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation). During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateViewport()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-viewport) performed an uncached data access ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database call, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, viewport metadata can't be deferred behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary because it affects the initial page load. The page can't be prerendered, so navigations block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation).
Request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)) in `generateViewport()` have different fixes. See [Next.js encountered runtime data in `generateViewport()`](https://preview.nextjs.org/docs/messages/blocking-prerender-viewport-runtime). The metadata equivalent is handled at [Uncached data in `generateMetadata()`](https://preview.nextjs.org/docs/messages/blocking-prerender-metadata-dynamic). For errors in the page body rather than viewport, see [Next.js encountered uncached data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-dynamic). Request-bound reads ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)) in `generateViewport()` have different fixes. See [Next.js encountered runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime). The metadata equivalent is handled at [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic). For errors in the page body rather than viewport, see [Next.js encountered uncached data during prerendering](/docs/messages/blocking-prerender-dynamic).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="cache" <FixCard
href="#cache-the-viewport-data" group="cache"
title="Cache the viewport data" title="Cache the viewport data"
> href="#cache-the-viewport-data"
Cache the viewport function so the result is reused and the route stays snippets={[
prerenderable. { text: 'async function generateViewport() {' },
</FixOption> { text: ' "use cache"', highlight: true },
{ text: ' return await db.getViewport(…)' },
<FixOption ]}
group="block" />
href="#allow-blocking-route" <FixCard
title="Allow blocking route" group="block"
> title="Allow blocking route"
Opt this segment out of instant navigation. The route renders on every request href="#allow-blocking-route"
and every navigation blocks. snippets={[
</FixOption> { text: '// page.tsx or layout.tsx' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Cache the viewport data ## Cache the viewport data
...@@ -132,7 +136,7 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -132,7 +136,7 @@ Navigations to this route are not instant. The user waits for the full server re
- Setting [`instant`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. - Setting [`instant`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default.
- This export does not disable [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`instant = false`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Cache the viewport data](#cache-the-viewport-data) instead, or move to [`global-not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`. - Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`instant = false`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Cache the viewport data](#cache-the-viewport-data) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`.
## Verifying the fix ## Verifying the fix
...@@ -148,3 +152,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -148,3 +152,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -25,27 +25,31 @@ kind: insight ...@@ -25,27 +25,31 @@ kind: insight
During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateViewport()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-viewport) read a per-request value ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, viewport metadata can't be deferred behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary because it affects the initial page load. The page can't be prerendered, so navigations block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation). During [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering), [`generateViewport()`](https://preview.nextjs.org/docs/app/api-reference/functions/generate-viewport) read a per-request value ([`cookies()`](https://preview.nextjs.org/docs/app/api-reference/functions/cookies), [`headers()`](https://preview.nextjs.org/docs/app/api-reference/functions/headers), [`params`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#params-optional), [`searchParams`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/page#searchparams-optional)). With [Cache Components](https://preview.nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents) enabled, viewport metadata can't be deferred behind a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary because it affects the initial page load. The page can't be prerendered, so navigations block instead of being [instant](https://preview.nextjs.org/docs/app/guides/instant-navigation).
Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)) in `generateViewport()` have different fixes. See [Next.js encountered uncached data in `generateViewport()`](https://preview.nextjs.org/docs/messages/blocking-prerender-viewport-dynamic). The metadata equivalent is handled at [Runtime data in `generateMetadata()`](https://preview.nextjs.org/docs/messages/blocking-prerender-metadata-runtime). For errors in the page body rather than viewport, see [Next.js encountered runtime data during prerendering](https://preview.nextjs.org/docs/messages/blocking-prerender-runtime). Uncached data accesses ([`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch), database calls, [`await connection()`](https://preview.nextjs.org/docs/app/api-reference/functions/connection)) in `generateViewport()` have different fixes. See [Next.js encountered uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic). The metadata equivalent is handled at [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime). For errors in the page body rather than viewport, see [Next.js encountered runtime data during prerendering](/docs/messages/blocking-prerender-runtime).
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="static" <FixCard
href="#use-static-viewport" group="static"
title="Use static viewport" title="Use static viewport"
> href="#use-static-viewport"
Replace the dynamic function with a static export so the viewport is known at snippets={[
build time. { text: 'export const viewport = {', highlight: true },
</FixOption> { text: ' themeColor: "#000"' },
{ text: '}' },
<FixOption ]}
group="block" />
href="#allow-blocking-route" <FixCard
title="Allow blocking route" group="block"
> title="Allow blocking route"
Opt this segment out of instant navigation. The route renders on every request href="#allow-blocking-route"
and every navigation blocks. snippets={[
</FixOption> { text: '// page.tsx or layout.tsx' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Use static viewport ## Use static viewport
...@@ -131,7 +135,7 @@ Navigations to this route are not instant. The user waits for the full server re ...@@ -131,7 +135,7 @@ Navigations to this route are not instant. The user waits for the full server re
- Setting [`instant`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default. - Setting [`instant`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` opts only the segment that exports it out. Descendant segments are still validated by the global default.
- This export does not disable [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error. - This export does not disable [prerendering](https://preview.nextjs.org/docs/app/glossary#prerendering). The route still prerenders if it can. It only silences the instant-navigation validation error.
- If the dynamic viewport is the only reason the route blocks, consider whether a static default covers most users. A static `themeColor` with a client-side correction after hydration may give a better experience than blocking the entire navigation. - If the dynamic viewport is the only reason the route blocks, consider whether a static default covers most users. A static `themeColor` with a client-side correction after hydration may give a better experience than blocking the entire navigation.
- Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`instant = false`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Use static viewport](#use-static-viewport) instead, or move to [`global-not-found.js`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`. - Framework-synthesized routes (`/_not-found`, `/_global-error`) inherit the root layout's `generateViewport` and must be statically prerendered. [`instant = false`](https://preview.nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant) silences the validation error but does not let those routes through, so the build still fails when they prerender. If your root layout's `generateViewport` depends on request data, [Use static viewport](#use-static-viewport) instead, or move to [`global-not-found.js`](/docs/app/api-reference/file-conventions/not-found#global-not-foundjs-experimental), which bypasses the root layout entirely and avoids inheriting its `generateViewport`.
## Verifying the fix ## Verifying the fix
...@@ -147,3 +151,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -147,3 +151,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -29,32 +29,36 @@ Routes that opt into Partial Prefetching skip the dynamic data at prefetch time, ...@@ -29,32 +29,36 @@ Routes that opt into Partial Prefetching skip the dynamic data at prefetch time,
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="upgrade" <FixCard
href="#opt-into-partial-prefetching" group="upgrade"
title="Opt into Partial Prefetching" title="Opt into Partial Prefetching"
> href="#opt-into-partial-prefetching"
Adopt Partial Prefetching for the target route so the link prefetches only the snippets={[
App Shell. After adopting, layer on further prefetch optimizations. { text: '// page.tsx or layout.tsx' },
</FixOption> { text: "export const prefetch = 'partial'", highlight: true },
]}
<FixOption />
group="disable" <FixCard
href="#use-the-default-prefetch" group="disable"
title="Use the default prefetch" title="Use the default prefetch"
> href="#use-the-default-prefetch"
Drop the prefetch prop from the link so it falls back to the default prefetch snippets={[
behavior, which does not include dynamic data. { text: '<Link href="/dashboard">', highlight: true },
</FixOption> { text: ' Dashboard' },
{ text: '</Link>' },
<FixOption ]}
group="ignore" />
href="#disable-validation-on-this-route" <FixCard
title="Disable validation on this route" group="ignore"
> title="Disable validation on this route"
Opt the target route out of instant-navigation validation and keep the legacy href="#disable-validation-on-this-route"
full prefetch. snippets={[
</FixOption> { text: '// page.tsx or layout.tsx' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Opt into Partial Prefetching ## Opt into Partial Prefetching
...@@ -148,7 +152,7 @@ The link continues to do a full prefetch, including dynamic data, and the warnin ...@@ -148,7 +152,7 @@ The link continues to do a full prefetch, including dynamic data, and the warnin
### Gotchas ### Gotchas
- `instant = false` disables all instant-navigation checks for the route, not only this one. [Blocking-route](https://preview.nextjs.org/docs/messages/blocking-prerender-runtime) and [unrendered-segment](https://preview.nextjs.org/docs/messages/instant-unrendered-segment) warnings, and other Insights for the route are silenced too. - `instant = false` disables all instant-navigation checks for the route, not only this one. [Blocking-route](/docs/messages/blocking-prerender-runtime) and [unrendered-segment](/docs/messages/instant-unrendered-segment) warnings, and other Insights for the route are silenced too.
## Verifying the fix ## Verifying the fix
...@@ -164,3 +168,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -164,3 +168,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Unrendered segment](/docs/messages/instant-unrendered-segment)
...@@ -29,22 +29,42 @@ This typically happens when a layout conditionally omits `{children}`, a paralle ...@@ -29,22 +29,42 @@ This typically happens when a layout conditionally omits `{children}`, a paralle
## Ways to fix this ## Ways to fix this
<FixOption <FixCardGrid>
group="render" <FixCard
href="#render-the-dropped-segment" group="render"
title="Render the dropped segment" title="Render the dropped segment"
> href="#render-the-dropped-segment"
Include the segment in the render tree so Next.js can validate it for instant snippets={[
navigation. {
</FixOption> text: 'function Layout({ children }) {',
parts: [
<FixOption { text: 'function Layout({ ' },
group="ignore" { text: 'children', highlight: true },
href="#skip-validation-on-the-segment" { text: ' }) {' },
title="Skip validation on the segment" ],
> },
Opt the dropped segment out of instant-navigation validation. {
</FixOption> text: ' return <><Nav />{children}</>',
parts: [
{ text: ' return <><Nav />{' },
{ text: 'children', highlight: true },
{ text: '}</>' },
],
},
{ text: '}' },
]}
/>
<FixCard
group="ignore"
title="Skip validation on the segment"
href="#skip-validation-on-the-segment"
snippets={[
{ text: '// page.tsx or layout.tsx' },
{ text: '' },
{ text: 'export const instant = false', highlight: true },
]}
/>
</FixCardGrid>
## Render the dropped segment ## Render the dropped segment
...@@ -82,7 +102,7 @@ export default function DashboardLayout({ children, modal }) { ...@@ -82,7 +102,7 @@ export default function DashboardLayout({ children, modal }) {
} }
``` ```
Learn more: [Parallel Routes](https://preview.nextjs.org/docs/app/api-reference/file-conventions/parallel-routes). Learn more: [Parallel Routes](/docs/app/api-reference/file-conventions/parallel-routes).
#### Move auth or guard checks into the page #### Move auth or guard checks into the page
...@@ -164,3 +184,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev ...@@ -164,3 +184,20 @@ Instant-navigation validation runs by default in [Cache Components](https://prev
- **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`. - **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`.
See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model. See [Ensuring instant navigations](https://preview.nextjs.org/docs/app/guides/instant-navigation) for the full model.
## Related Insights
- [Runtime data during prerendering](/docs/messages/blocking-prerender-runtime)
- [Uncached data during prerendering](/docs/messages/blocking-prerender-dynamic)
- [URL data in a Client Component outside of Suspense](/docs/messages/blocking-prerender-client-hook)
- [Runtime data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-runtime)
- [Uncached data in `generateMetadata()`](/docs/messages/blocking-prerender-metadata-dynamic)
- [Runtime data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-runtime)
- [Uncached data in `generateViewport()`](/docs/messages/blocking-prerender-viewport-dynamic)
- [`Math.random()` while prerendering](/docs/messages/blocking-prerender-random)
- [`Math.random()` in a Client Component](/docs/messages/blocking-prerender-random-client)
- [`Date.now()` while prerendering](/docs/messages/blocking-prerender-current-time)
- [`Date.now()` in a Client Component](/docs/messages/blocking-prerender-current-time-client)
- [Crypto APIs while prerendering](/docs/messages/blocking-prerender-crypto)
- [Crypto APIs in a Client Component](/docs/messages/blocking-prerender-crypto-client)
- [Partial Prefetch link with dynamic data](/docs/messages/instant-link-prefetch-partial)
...@@ -47,14 +47,14 @@ export const FIX_CARD_GROUPS: Record< ...@@ -47,14 +47,14 @@ export const FIX_CARD_GROUPS: Record<
} }
export type FixCard = { export type FixCard = {
/** Stable docs-anchor id for this fix card. */ /** Docs anchor for this card. */
id: string id: string
title: string title: string
group: FixCardGroup group: FixCardGroup
/** Docs URL the card links to, or `null` for no link. */ /** Docs URL, or null for no link. */
link: string | null link: string | null
snippets: Snippet[] snippets: Snippet[]
/** Whether to render the "Copy AI prompt" button on this card. */ /** Show the Copy prompt button on this card. */
copyable?: boolean copyable?: boolean
} }
...@@ -66,9 +66,7 @@ export type SnippetPart = { ...@@ -66,9 +66,7 @@ export type SnippetPart = {
export type Snippet = { export type Snippet = {
text: string text: string
highlight?: boolean highlight?: boolean
// When present, render the line with inline highlighted parts instead of /** Inline highlights within the line; takes precedence over the line-level `highlight` flag. */
// applying the line-level `highlight` flag. `text` is still kept for any
// tooling that reads the full line content.
parts?: SnippetPart[] parts?: SnippetPart[]
} }
......
...@@ -107,7 +107,7 @@ function CopyPromptButton({ ...@@ -107,7 +107,7 @@ function CopyPromptButton({
const info = await generateErrorInfo() const info = await generateErrorInfo()
return info ? `${fixHeader}\n\n${info}` : fixHeader return info ? `${fixHeader}\n\n${info}` : fixHeader
}} }}
actionLabel="Copy as prompt" actionLabel="Copy prompt"
successLabel="Copied" successLabel="Copied"
icon={<CopyPromptIcon />} icon={<CopyPromptIcon />}
showLabel showLabel
...@@ -116,7 +116,7 @@ function CopyPromptButton({ ...@@ -116,7 +116,7 @@ function CopyPromptButton({
) : ( ) : (
<CopyButton <CopyButton
content={fixHeader} content={fixHeader}
actionLabel="Copy as prompt" actionLabel="Copy prompt"
successLabel="Copied" successLabel="Copied"
icon={<CopyPromptIcon />} icon={<CopyPromptIcon />}
showLabel showLabel
...@@ -601,9 +601,10 @@ export const INSTANT_GUIDANCE_STYLES = css` ...@@ -601,9 +601,10 @@ export const INSTANT_GUIDANCE_STYLES = css`
font-family: var(--font-stack-sans); font-family: var(--font-stack-sans);
font-size: var(--size-11); font-size: var(--size-11);
font-weight: 500; font-weight: 500;
gap: 4px; gap: 6px;
height: auto; height: auto;
padding: 3px 8px 3px 7px; line-height: 1;
padding: 5px 10px;
position: absolute; position: absolute;
right: 10px; right: 10px;
top: -10px; top: -10px;
......
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