Unverified Commit 922d2e73 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: clarify ensureStatic levels from dogfooding (#99590)

## Summary

Follow-ups to the `ensureStatic` reference from dogfooding
`ensureStatic` on `vercel/shop` for 16.4.

- **`'shell'` costs:** with `'shell'`, a `<Link prefetch={true}>` into a
route that reads `cookies()`, `headers()`, or URL data still makes a
runtime per-link prefetch. Each visible link triggers a server render,
and nothing in the UI shows it. The `'shell'` section now says so and
points to `'prefetch'`.
- **Fallback shell on first visit:** under `'prefetch'`, a per-link
prefetch for params not returned by `generateStaticParams()` serves the
fallback shell until the page is generated in the background. On a fresh
deployment, the first navigation to those URLs can show the shell. The
`'prefetch'` section now explains this and links the ISR guide.
- **`ensureStatic` is not a stage API:** removing `await navigation()`
because the route set `'prefetch'` moved synchronous IO
(`crypto.randomUUID()` in a request helper) into earlier stages. A new
"How `ensureStatic` differs from `prefetch()` and `navigation()`"
section explains that `ensureStatic` validates which stages are static
but does not move code.

The changes are insertions only and merge cleanly with #99493, which
edits nearby lines in the same file.

## Verification

- `'shell'` deopt to runtime per-link prefetches:
`dynamic-rendering-utils.ts` clears `shouldAttemptStaticPrefetch` for
session and URL data unless the level is at least `Prefetch`, and the
client sends `next-router-prefetch: 2` (`FetchStrategy.PPRRuntime`) in
that case
- Fallback for unlisted params under `'prefetch'`: the
fallback-upgradeable branch in `dynamic-rendering-utils.ts` skips the
runtime request when the level is at least `Prefetch`
- Synchronous IO interrupting non-dynamic stages with Partial
Prefetching: `io-utils.tsx` and `SyncIOMode.AllowedInDynamic` in
`staged-rendering.ts`
- Prettier and `alex` pass on the changed file

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- NEXT_JS_LLM -->

---------
Co-authored-by: 's avatarClaude Opus 5.5 <noreply@anthropic.com>
parent 440487b0
......@@ -58,6 +58,8 @@ The shell can include static or cached content and `<Suspense>` fallbacks. Reque
For an individual subtree, [`await prefetch()`](/docs/app/api-reference/functions/prefetch) provides similar behavior by deferring code below the call to a per-link prefetch or navigation. Setting `'shell'` enforces that stage boundary across the route without adding `await prefetch()` to each request-specific subtree.
> **Good to know**: `'shell'` only covers the App Shell. If the route reads `cookies()`, `headers()`, or URL data anywhere that is not below [`await navigation()`](/docs/app/api-reference/functions/navigation), each visible [`<Link prefetch={true}>`](/docs/app/api-reference/components/link#prefetch) into it still renders its prefetch on the server, and the prefetched UI gives no sign of that work. Use [`'prefetch'`](#prefetch) when per-link prefetches must also come from static output.
### `'prefetch'`
Requires both the App Shell and per-link prefetches to be static. This only works with [Partial Prefetching](/docs/app/api-reference/config/next-config-js/partialPrefetching).
......@@ -97,6 +99,8 @@ With `'navigation'`, a dynamic route must export [`generateStaticParams()`](/doc
Values returned by `generateStaticParams()` are available during prerendering. When a request uses a value that was not prerendered at build time, Next.js waits for the static result to be generated before serving it.
With `'shell'` or `'prefetch'`, a value that was not prerendered serves the route's fallback shell instead, with `<Suspense>` fallbacks in place of its content, while Next.js generates the page in the background. See [ISR with Cache Components](/docs/app/guides/incremental-static-regeneration-cache-components#at-runtime).
The build fails when `generateStaticParams()` is missing or returns an incomplete parameter set. See the [`generateStaticParams` error guide](/docs/messages/generate-static-params#with-ensurestatic).
#### Client Components
......
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