Unverified Commit 4195e9ed authored by David Alexandru Ilie's avatar David Alexandru Ilie Committed by GitHub

docs: distinguish instant from request-time rendering

parent 83b3d01e
...@@ -83,7 +83,9 @@ A validation insight or error tells you a route won't render instantly. Resolve ...@@ -83,7 +83,9 @@ A validation insight or error tells you a route won't render instantly. Resolve
export const instant = false export const instant = false
``` ```
> **Good to know**: `instant = false` marks a segment as _allowed to block_. It does not force the route to be dynamic, so a genuinely prerenderable route still ships a static shell. It also does not clear synchronous IO build errors: calls like `new Date()`, `Math.random()`, and `crypto.randomUUID()` still fail the prerender. See [Adopting incrementally](#adopting-incrementally). Export `instant` from the segment's Server Component file (`page`, `layout`, or `default`). If that file has a `'use client'` directive, move the client code into a child component and keep the route file as a Server Component.
> **Good to know**: `instant = false` skips instant-navigation validation and marks a segment as _allowed to block_. It does not opt the segment out of prerendering or force it to be dynamic, so a genuinely prerenderable route still ships a static shell. By contrast, [`connection()`](/docs/app/api-reference/functions/connection) defers the code below it until an actual request. Use `connection()` below a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary when the work itself must not run during prerendering. These APIs are not interchangeable.
## Adopting incrementally ## Adopting incrementally
......
...@@ -55,11 +55,11 @@ This typically happens when a layout conditionally omits `{children}` or a paral ...@@ -55,11 +55,11 @@ This typically happens when a layout conditionally omits `{children}` or a paral
/> />
<FixCard <FixCard
group="ignore" group="ignore"
title="Skip validation on the segment" title="Skip only this validation"
href="#skip-validation-on-the-segment" href="#skip-validation-on-the-segment"
snippets={[ snippets={[
{ text: '// page.tsx or layout.tsx' }, { text: '// Server page.tsx or layout.tsx' },
{ text: '' }, { text: '// Prerendering still runs' },
{ text: 'export const instant = false', highlight: true }, { text: 'export const instant = false', highlight: true },
]} ]}
/> />
...@@ -142,7 +142,7 @@ The segment is always in the render tree, which means Next.js validates it on ev ...@@ -142,7 +142,7 @@ The segment is always in the render tree, which means Next.js validates it on ev
## Skip validation on the segment ## Skip validation on the segment
Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip validation for it. Choose this fix when the segment is intentionally not rendered in certain states (a modal that only appears on interaction, a slot gated by authentication). Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` on the dropped segment tells Next.js to skip this validation. It does not opt the segment out of prerendering or make it request-time rendered.
### Patterns ### Patterns
...@@ -160,6 +160,29 @@ export default function ModalPage() { ...@@ -160,6 +160,29 @@ export default function ModalPage() {
Learn more: [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant). Learn more: [Route segment `instant` config](/docs/app/api-reference/file-conventions/route-segment-config/instant).
#### Keep the route config in a Server Component
Route segment config must be exported from the segment's Server Component file. If the page or layout is currently a Client Component, move its client code into a child and keep the route file as a Server Component:
```jsx filename="app/dashboard/@modal/page.js"
import { Modal } from './modal'
export const instant = false
export default function ModalPage() {
return <Modal />
}
```
```jsx filename="app/dashboard/@modal/modal.js"
'use client'
export function Modal() {
// Client state and browser APIs can stay here.
return <div>Modal</div>
}
```
### Trade-off ### Trade-off
The segment is exempt from instant-navigation validation. If it has issues that would block navigation (uncached data outside Suspense, runtime APIs), those issues won't be caught during development. The segment is exempt from instant-navigation validation. If it has issues that would block navigation (uncached data outside Suspense, runtime APIs), those issues won't be caught during development.
...@@ -167,7 +190,8 @@ The segment is exempt from instant-navigation validation. If it has issues that ...@@ -167,7 +190,8 @@ The segment is exempt from instant-navigation validation. If it has issues that
### Gotchas ### Gotchas
- The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins. - The export must be on the **dropped segment's own file** (page or layout), not on a parent. The framework walks top-down and the first explicit config wins.
- Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](/docs/app/glossary#prerendering). The segment still prerenders if it can. It only disables the validation error. - The export must be in the segment's Server Component file. Do not add it to a file with the `'use client'` directive.
- Setting [`instant`](/docs/app/api-reference/file-conventions/route-segment-config/instant) to `false` does not disable [prerendering](/docs/app/glossary#prerendering). The segment still prerenders if it can. It only disables the validation error. To defer work until an actual request, use [`connection()`](/docs/app/api-reference/functions/connection) in a component below a [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary instead.
## Verifying the fix ## Verifying the fix
......
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