Unverified Commit ba55bd63 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

Refine Cache Components and Partial Prefetching adoption skills (#95817)

Refinements to the Cache Components and Partial Prefetching adoption
skills from running them cold against real apps, plus the doc changes
they lean on.

**Skills**
- PPF: URL-data sweep reworked to feature-by-feature with a resumable
hand-off, and the requires section now says unfinished Cache Components
adoption doesn't gate the skill. Prerender insights are non-blocking dev
signals expected on a fresh branch; only a build-blocking failure stops
the run.
- PPF: install `next-dev-loop` without asking, and verify a real blocker
before falling back.
- CC: dropped the hard-coded `agent-browser` version pin; updated the
PPF cross-reference to the current enable-first flow.

**Docs**
- `runtime-prefetching`: the per-card server cost of `allow-runtime`
grids is specific to `prefetch={true}`, with hover-triggered prefetch as
the mitigation.
- `use-cache`: the request-API restriction follows the call stack
(`next-request-in-use-cache`, can pass build and fail under `next
start`), and the nested-`cacheLife` build error with its fix.
- `instant` route segment config: removed a stale `version: draft` so
the page publishes.

<!-- NEXT_JS_LLM_PR -->
parent c3d5b927
...@@ -20,16 +20,6 @@ Along the way, Next.js surfaces [instant navigation](/docs/app/guides/instant-na ...@@ -20,16 +20,6 @@ Along the way, Next.js surfaces [instant navigation](/docs/app/guides/instant-na
> **Good to know**: Partial Prefetching only works when [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled. > **Good to know**: Partial Prefetching only works when [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled.
## What changes for `<Link>`
| `<Link>` prop | Before (Cache Components default) | After Partial Prefetching |
| ----------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `<Link href="/x">` | Prefetched the cached page render. | Loads the shared App Shell for `/x`. |
| `<Link href="/x" prefetch>` | Prefetched the cached page render **and** any dynamic content. | Loads the App Shell. If `/x` opts into [runtime prefetching](/docs/app/guides/runtime-prefetching), also prefetches per-link runtime data. |
| `<Link href="/x" prefetch={false}>` | Disabled prefetching for this link. | Unchanged. Still disabled. |
The App Shell is shared across every link to a given route, regardless of dynamic params, so rendering many `<Link>`s to the same destination doesn't multiply the work.
## Use the adoption skill (recommended) ## Use the adoption skill (recommended)
The [`next-partial-prefetching-adoption`](https://github.com/vercel/next.js/tree/canary/skills/next-partial-prefetching-adoption) skill drives this adoption with a coding agent. It audits your `<Link prefetch={true}>` calls with you, enables the flag, and sweeps every route for the insights this guide covers. The [`next-partial-prefetching-adoption`](https://github.com/vercel/next.js/tree/canary/skills/next-partial-prefetching-adoption) skill drives this adoption with a coding agent. It audits your `<Link prefetch={true}>` calls with you, enables the flag, and sweeps every route for the insights this guide covers.
...@@ -73,6 +63,16 @@ export default nextConfig ...@@ -73,6 +63,16 @@ export default nextConfig
After enabling the flag, every `<Link>` prefetches its destination's App Shell, and `<Link prefetch={true}>` no longer includes the route's dynamic content. Audit those links next to preserve what they delivered. A new project has no legacy links to audit and is done here. After enabling the flag, every `<Link>` prefetches its destination's App Shell, and `<Link prefetch={true}>` no longer includes the route's dynamic content. Audit those links next to preserve what they delivered. A new project has no legacy links to audit and is done here.
## What changes for `<Link>`
| `<Link>` prop | Before (Cache Components default) | After Partial Prefetching |
| ----------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `<Link href="/x">` | Prefetched the cached page render. | Loads the shared App Shell for `/x`. |
| `<Link href="/x" prefetch>` | Prefetched the cached page render **and** any dynamic content. | Loads the App Shell. If `/x` opts into [runtime prefetching](/docs/app/guides/runtime-prefetching), also prefetches per-link runtime data. |
| `<Link href="/x" prefetch={false}>` | Disabled prefetching for this link. | Unchanged. Still disabled. |
The App Shell is shared across every link to a given route, regardless of dynamic params, so rendering many `<Link>`s to the same destination doesn't multiply the work.
## Auditing `<Link prefetch={true}>` calls ## Auditing `<Link prefetch={true}>` calls
Each `<Link prefetch={true}>` used to prefetch its destination's dynamic content along with the page. With the flag on it loads the App Shell like every other link, which can be thinner than the old full prefetch. Go through each one and decide what the destination should still prefetch: Each `<Link prefetch={true}>` used to prefetch its destination's dynamic content along with the page. With the flag on it loads the App Shell like every other link, which can be thinner than the old full prefetch. Go through each one and decide what the destination should still prefetch:
...@@ -308,7 +308,7 @@ Each card is clickable and opens a page with patterns, code samples, and trade-o ...@@ -308,7 +308,7 @@ Each card is clickable and opens a page with patterns, code samples, and trade-o
} }
``` ```
2. Deploy the change. Links to the adopted destination load the App Shell, and the insight keeps firing for the destinations you haven't reached. 2. Deploy the change. Links to the adopted destination load the App Shell, and the insight keeps surfacing for the destinations you haven't reached.
3. Repeat until every destination in scope is adopted, then [enable the flag](#enable-partial-prefetching). 3. Repeat until every destination in scope is adopted, then [enable the flag](#enable-partial-prefetching).
The per-route `prefetch = 'partial'` exports are now redundant. Remove them in one pass with the [`remove-partial-prefetch`](/docs/app/guides/upgrading/codemods#remove-partial-prefetch) codemod, which strips `export const prefetch = 'partial'` from every `page` and `layout`: The per-route `prefetch = 'partial'` exports are now redundant. Remove them in one pass with the [`remove-partial-prefetch`](/docs/app/guides/upgrading/codemods#remove-partial-prefetch) codemod, which strips `export const prefetch = 'partial'` from every `page` and `layout`:
......
...@@ -36,7 +36,7 @@ This is also why client-side hooks behave differently. `useSearchParams()` suspe ...@@ -36,7 +36,7 @@ This is also why client-side hooks behave differently. `useSearchParams()` suspe
</details> </details>
Runtime prefetching extends the static shell with request-specific content like the user's name from a cookie, by invoking the route at prefetch time. Ensuring navigations are instant is the foundation: a route that doesn't navigate instantly without runtime prefetching won't navigate instantly with it either. See [Runtime prefetching](/docs/app/guides/runtime-prefetching) for the patterns. Runtime prefetching extends the static shell with a link's URL data (`searchParams` and `params`) by invoking the route at prefetch time. Ensuring navigations are instant is the foundation: a route that doesn't navigate instantly without runtime prefetching won't navigate instantly with it either. See [Runtime prefetching](/docs/app/guides/runtime-prefetching) for the patterns.
## The tools ## The tools
...@@ -277,7 +277,7 @@ Toggle **Pause on navigations** off when you're done inspecting loading states. ...@@ -277,7 +277,7 @@ Toggle **Pause on navigations** off when you're done inspecting loading states.
Validation catches structural problems during development, but as the codebase grows, the structural checks can only tell you that a shell exists. They can't tell you whether the right content is in it. E2E tests close that gap: they assert on what the user actually sees when the navigation completes, catching regressions before they ship. Validation catches structural problems during development, but as the codebase grows, the structural checks can only tell you that a shell exists. They can't tell you whether the right content is in it. E2E tests close that gap: they assert on what the user actually sees when the navigation completes, catching regressions before they ship.
The `@next/playwright` package includes an `instant()` helper for this. Install it alongside `@playwright/test`: The [`@next/playwright`](https://www.npmjs.com/package/@next/playwright) package includes an `instant()` helper for this. Install it alongside `@playwright/test`:
```bash package="pnpm" ```bash package="pnpm"
pnpm add -D @next/playwright @playwright/test pnpm add -D @next/playwright @playwright/test
...@@ -468,14 +468,13 @@ Agents working on a Cache Components route typically reach for three levers: ...@@ -468,14 +468,13 @@ Agents working on a Cache Components route typically reach for three levers:
- **Push down**: extract I/O into a Suspense-wrapped child so the parent stays static and static siblings lift into the shell. - **Push down**: extract I/O into a Suspense-wrapped child so the parent stays static and static siblings lift into the shell.
- **Cache**: pair `'use cache'` with [`cacheLife`](/docs/app/api-reference/functions/cacheLife) to assign a freshness profile. - **Cache**: pair `'use cache'` with [`cacheLife`](/docs/app/api-reference/functions/cacheLife) to assign a freshness profile.
- **Runtime prefetching** (nav-only): when I/O depends on `cookies()`, `headers()`, or `searchParams`, opt the route into [runtime prefetching](/docs/app/guides/runtime-prefetching) so the framework prerenders it at link-prefetch time. - **Runtime prefetching** (nav-only): when a route reads URL data (`searchParams` or `params`), opt it into [runtime prefetching](/docs/app/guides/runtime-prefetching) so the framework resolves that data at link-prefetch time. Session data from `cookies()` or `headers()` already lands in the App Shell without it.
Each refactor should pair with a before/after capture to verify the change actually landed. Identical-looking captures mean the refactor didn't take effect. Each refactor should pair with a before/after capture to verify the change actually landed. Identical-looking captures mean the refactor didn't take effect.
For agents to see what their changes actually render, pair this with [agent-browser](https://github.com/vercel-labs/agent-browser). It exposes the Next.js DevTools (including PPR shells) as shell commands agents can read and drive, so the loop becomes: make a change, snapshot the shell, check what's in it, adjust. For agents to see what their changes actually render, pair this with [agent-browser](https://github.com/vercel-labs/agent-browser). With React DevTools enabled it reports the component tree and which `<Suspense>` boundaries are still pending, so an agent can make a change, snapshot the shell, check what landed, and adjust. See [Runtime visibility](/docs/app/guides/ai-agents#runtime-visibility) in the AI agents guide for the setup.
{/* TODO: distribution of the skill/plugin */} The [`next-cache-components-optimizer`](/docs/app/guides/ai-agents#next-cache-components-optimizer) skill packages this loop: it encodes the goal as a failing `@next/playwright` `instant()` test and works it to green one route at a time, for both initial load (hard navigation) and client-side navigation (soft navigation), then ships the test as a regression guard.
The [`next-cache-components-optimizer`](https://github.com/vercel/next.js/tree/canary/skills/next-cache-components-optimizer) skill packages this loop: it encodes the goal as a failing `@next/playwright` `instant()` test and works it to green one route at a time, for both initial load (hard navigation) and client-side navigation (soft navigation), then ships the test as a regression guard.
## Opting out ## Opting out
...@@ -503,12 +502,12 @@ export const instant = false ...@@ -503,12 +502,12 @@ export const instant = false
With `false` on `/dashboard/layout.tsx`, validation no longer flags navigations into `/dashboard` from outside; navigations between `/dashboard/a` and `/dashboard/b` are still checked. With `false` on `/dashboard/layout.tsx`, validation no longer flags navigations into `/dashboard` from outside; navigations between `/dashboard/a` and `/dashboard/b` are still checked.
For opted-out segments, the navigation blocks on the server. If the content depends on cookies or headers but has a known cache lifetime, [runtime prefetching](/docs/app/guides/runtime-prefetching) can prerender it ahead of click instead of opting out. For opted-out segments, the navigation blocks on the server. If the content depends on cookies or headers but has a known cache lifetime, caching it with [`use cache: private`](/docs/app/api-reference/directives/use-cache-private) lets the App Shell carry it ahead of the click instead of opting out.
## Next steps ## Next steps
- [Adopting Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) for the recommended `<Link>` defaults and the migration path off `unstable_eager` - [Adopting Partial Prefetching](/docs/app/guides/adopting-partial-prefetching) for the recommended `<Link>` defaults and the migration path off `unstable_eager`
- [`instant` API reference](/docs/app/api-reference/file-conventions/route-segment-config/instant) for the full configuration - [`instant` API reference](/docs/app/api-reference/file-conventions/route-segment-config/instant) for the full configuration
- [Runtime prefetching](/docs/app/guides/runtime-prefetching) when parts of your route depend on cookies or headers and you want those in the shell - [Runtime prefetching](/docs/app/guides/runtime-prefetching) when parts of your route depend on URL data (`searchParams` or `params`) and you want it in the shell
- [Caching](/docs/app/getting-started/caching) for background on `use cache`, Suspense, and Partial Prerendering - [Caching](/docs/app/getting-started/caching) for background on `use cache`, Suspense, and Partial Prerendering
- [Revalidating](/docs/app/getting-started/revalidating) for how to expire cached data with `cacheLife` and `updateTag` - [Revalidating](/docs/app/getting-started/revalidating) for how to expire cached data with `cacheLife` and `updateTag`
...@@ -201,7 +201,7 @@ Use it on routes where: ...@@ -201,7 +201,7 @@ Use it on routes where:
- That part of the tree has a known cache lifetime (it can be expressed with `"use cache"` or `"use cache: private"`) - That part of the tree has a known cache lifetime (it can be expressed with `"use cache"` or `"use cache: private"`)
- The traffic justifies the per-link server invocation - The traffic justifies the per-link server invocation
Skip it when the prefetch can't produce a better UI than the App Shell. Each visible `<Link>` to a route with `'allow-runtime'` wakes a server, and that cost only pays off if more of the page is ready before the click: Skip it when the prefetch can't produce a better UI than the App Shell. Each visible `<Link prefetch={true}>` to a route with `'allow-runtime'` makes its own request to the server to render that link, and that cost only pays off if more of the page is ready before the click:
- The route has little or no URL-data dependency. The App Shell already makes the navigation instant. - The route has little or no URL-data dependency. The App Shell already makes the navigation instant.
- The dependent content has to be fresh on every request. The prerender stops at the same `<Suspense>` fallback, so the user sees the same UI either way. - The dependent content has to be fresh on every request. The prerender stops at the same `<Suspense>` fallback, so the user sees the same UI either way.
...@@ -209,6 +209,8 @@ Skip it when the prefetch can't produce a better UI than the App Shell. Each vis ...@@ -209,6 +209,8 @@ Skip it when the prefetch can't produce a better UI than the App Shell. Each vis
A per-link runtime prefetch is best-effort. It only helps the navigations where it completes before the click. On a slow connection, on a feed of many links, or on a direct visit, it may not be ready when the user navigates, and the navigation falls back to the App Shell. That shell is the reliable baseline, and runtime prefetching only layers on top when it arrives in time. A per-link runtime prefetch is best-effort. It only helps the navigations where it completes before the click. On a slow connection, on a feed of many links, or on a direct visit, it may not be ready when the user navigates, and the navigation falls back to the App Shell. That shell is the reliable baseline, and runtime prefetching only layers on top when it arrives in time.
When many links to an `allow-runtime` route are visible at once, such as a grid of cards, each `<Link prefetch={true}>` prefetches that link's content as it enters the viewport, so the grid makes one such server request per card. Prefetch on intent instead: a [hover-triggered prefetch](/docs/app/guides/prefetching#hover-triggered-prefetch) fetches only the links the user is likely to click. The default `<Link>` (without `prefetch={true}`) prefetches just the App Shell, so it doesn't carry this cost.
| | App Shell | Per-link runtime prefetch with `allow-runtime` | | | App Shell | Per-link runtime prefetch with `allow-runtime` |
| ------- | ------------------------------------------- | ---------------------------------------------- | | ------- | ------------------------------------------- | ---------------------------------------------- |
| Scope | One per route | One per visible `<Link prefetch={true}>` | | Scope | One per route | One per visible `<Link prefetch={true}>` |
......
...@@ -193,7 +193,7 @@ Cached functions execute in an isolated environment. The following constraints e ...@@ -193,7 +193,7 @@ Cached functions execute in an isolated environment. The following constraints e
### Request-time APIs ### Request-time APIs
Cached functions and components **cannot** directly access runtime APIs like `cookies()`, `headers()`, or `searchParams`. Instead, read these values outside the cached scope and pass them as arguments. Cached functions and components **cannot** access runtime APIs like `cookies()`, `headers()`, or `searchParams`, and the restriction follows the call stack: a helper the cached function calls that reads one of these fails the same way, with the [`next-request-in-use-cache`](/docs/messages/next-request-in-use-cache) error. On a dynamically rendered route this surfaces when the route runs, so it can pass `next build` and fail under `next start`. Read these values outside the cached scope and pass them as arguments.
### Runtime caching considerations ### Runtime caching considerations
...@@ -314,6 +314,8 @@ async function getData() { ...@@ -314,6 +314,8 @@ async function getData() {
} }
``` ```
Nesting a short-lived use cache inside one without an explicit [cacheLife](/docs/app/api-reference/functions/cacheLife) fails the build during prerendering. See [Nested short-lived caches](/docs/app/api-reference/functions/cacheLife#nested-short-lived-caches) for the rule and fix.
### On-demand revalidation ### On-demand revalidation
Use [`cacheTag`](/docs/app/api-reference/functions/cacheTag), [`updateTag`](/docs/app/api-reference/functions/updateTag), or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) for on-demand cache invalidation: Use [`cacheTag`](/docs/app/api-reference/functions/cacheTag), [`updateTag`](/docs/app/api-reference/functions/updateTag), or [`revalidateTag`](/docs/app/api-reference/functions/revalidateTag) for on-demand cache invalidation:
......
--- ---
title: instant title: instant
description: API reference for the instant route segment config. description: API reference for the instant route segment config.
version: draft
related: related:
title: Next Steps title: Next Steps
description: Learn how to use instant navigations in practice. description: Learn how to use instant navigations in practice.
......
...@@ -10,7 +10,9 @@ If you're unsure which fix fits, the right call usually depends on what this par ...@@ -10,7 +10,9 @@ If you're unsure which fix fits, the right call usually depends on what this par
## security gates and other code you can't infer ## security gates and other code you can't infer
If the blocking code looks like it's there for a _reason you can't infer_ — a security gate at the page top (`await verifyAccess()`, an auth redirect, a feature-flag check) where moving it inside `<Suspense>` would change what the code guarantees — stop and ask the user before refactoring. The build error wants `<Suspense>`, but wrapping a gate in `<Suspense>` defeats the gate. Only the person who wrote it knows whether to keep the route blocking (`instant = false` as a documented Block), restructure the page so the gate runs differently, or move the check to [Proxy](https://nextjs.org/docs/app/api-reference/file-conventions/proxy). If the blocking code looks like it's there for a _reason you can't infer_ — a security gate at the page top (`await verifyAccess()`, an auth redirect, a feature-flag check) where moving it inside `<Suspense>` would change what the code guarantees — stop and ask the user before refactoring. The build error wants `<Suspense>`, but wrapping a gate in `<Suspense>` defeats the gate. Only the person who wrote it knows whether to keep the route blocking (`instant = false` as a documented Block), restructure the page so the gate runs differently, move the check to [Proxy](https://nextjs.org/docs/app/api-reference/file-conventions/proxy), or — if the gate duplicates protection the app already relies on elsewhere (platform auth such as Vercel Deployment Protection, a Proxy check, a Data Access Layer) — remove it.
Relocating a read (`await connection()`, Proxy) only changes _where_ it runs, never _whether it should run at all_ — so a gate that's redundant or broken looks identical to a correctly-placed one through the fix card's lens. If a gate looks strange, redundant, or out of place, say so plainly — "this looks like it might be unnecessary here — are you sure it belongs?" — instead of quietly relocating it. Surfacing the doubt is the agent's job; deciding is the user's.
If _every_ route under a layout is gated this way, a documented Block on the layout is the correct end state. Moving the gate to [Proxy](https://nextjs.org/docs/app/api-reference/file-conventions/proxy) is the architectural fix, not a Cache Components one, and that's a follow-up rather than something to hold the migration on. If _every_ route under a layout is gated this way, a documented Block on the layout is the correct end state. Moving the gate to [Proxy](https://nextjs.org/docs/app/api-reference/file-conventions/proxy) is the architectural fix, not a Cache Components one, and that's a follow-up rather than something to hold the migration on.
......
...@@ -19,10 +19,11 @@ Set up an agentic optimization loop that drives a Next.js route from "not ...@@ -19,10 +19,11 @@ Set up an agentic optimization loop that drives a Next.js route from "not
instant" to "instant" and keeps it there. The loop is test-driven: encode the instant" to "instant" and keeps it there. The loop is test-driven: encode the
goal as a failing `@next/playwright` `instant()` test, work it to green, and goal as a failing `@next/playwright` `instant()` test, work it to green, and
ship the test as the regression guard. Run it once per target route. Work the ship the test as the regression guard. Run it once per target route. Work the
phases P → G in order; each ends in a gate. Production shapes (parallel routes, phases P → G in order; each ends in a gate. Fix recipes live in two lazily-read
auth gates, the empty-shell and responsive-skeleton failure modes) live in a references — `reference/patterns.md` (before→after for each blocker type) and
lazily-read reference, `reference/real-app-patterns.md`; read it only when phase `reference/real-app-patterns.md` (parallel routes, auth gates, the empty-shell
D points there. and responsive-skeleton failure modes). Read one only when its phase points
there.
## What is invariant, and what is yours ## What is invariant, and what is yours
...@@ -119,7 +120,7 @@ those words. ...@@ -119,7 +120,7 @@ those words.
- [ ] B BASELINE unlocked: the marker renders for the test user → test-template.md - [ ] B BASELINE unlocked: the marker renders for the test user → test-template.md
- [ ] C RED locked instant(): the shell does not commit → test-template.md - [ ] C RED locked instant(): the shell does not commit → test-template.md
- [ ] C-gate VERIFY-RED: stop until the RED is trustworthy → reference/red-test-robustness.md - [ ] C-gate VERIFY-RED: stop until the RED is trustworthy → reference/red-test-robustness.md
- [ ] D FIX push each Suspense boundary down to the data it guards → below - [ ] D FIX push each Suspense boundary down to the data it guards → reference/patterns.md
- [ ] D1 reuse the route's existing loading UI; do not hand-build skeletons - [ ] D1 reuse the route's existing loading UI; do not hand-build skeletons
- [ ] D2 the shell matches the real render at every breakpoint → reference/real-app-patterns.md - [ ] D2 the shell matches the real render at every breakpoint → reference/real-app-patterns.md
- [ ] E PARITY the refactor changed only whether the route is instant - [ ] E PARITY the refactor changed only whether the route is instant
...@@ -283,10 +284,11 @@ Render `children` unconditionally; move the top-level `await` into a ...@@ -283,10 +284,11 @@ Render `children` unconditionally; move the top-level `await` into a
`<Suspense fallback={null}>`-wrapped child. Mechanism and before→after: `<Suspense fallback={null}>`-wrapped child. Mechanism and before→after:
`reference/real-app-patterns.md`, "Deferring an auth gate". `reference/real-app-patterns.md`, "Deferring an auth gate".
The page that consumes the shell should be sync (no top-level `await`), with **Fix the page below the shell too, not only the layout.** A page-level
its dynamic data behind `<Suspense>`. `fallback={null}` is correct only when top-level `await` (commonly `await params`) blocks the same way the layout's
the gate renders nothing on success. For data, the fallback must be a real does, so make the page sync and push its dynamic reads into a
loading skeleton (see D1). `<Suspense>`-wrapped leaf as well. `fallback={null}` is correct only when a gate renders nothing on
success; for data, the fallback must be a real loading skeleton (see D1).
Every other blocker shape — `cookies()`/`headers()`, uncached fetch or database Every other blocker shape — `cookies()`/`headers()`, uncached fetch or database
reads, `searchParams`, metadata, viewport, non-deterministic values (`Date.now()`, reads, `searchParams`, metadata, viewport, non-deterministic values (`Date.now()`,
...@@ -296,8 +298,12 @@ default build output is often abbreviated and may carry no usable stack trace; ...@@ -296,8 +298,12 @@ default build output is often abbreviated and may carry no usable stack trace;
add `--debug-prerender` for the full failing frame and to report every blocker add `--debug-prerender` for the full failing frame and to report every blocker
past the first. Scope the build to the route you're on with past the first. Scope the build to the route you're on with
`next build --debug-build-paths "app/<route>/**"` rather than rebuilding the app. `next build --debug-build-paths "app/<route>/**"` rather than rebuilding the app.
Open that page and apply its recipe; don't improvise from the inline message. A few things those Open that page and apply its recipe; don't improvise from the inline message.
per-error pages don't stress for the instant-navigation goal:
The before→after recipe for each shape is in `reference/patterns.md`, which maps it to the insight
that explains it.
A few things those per-error pages don't stress for the instant-navigation goal:
- **A boundary in the root layout isn't enough for client navigations.** It - **A boundary in the root layout isn't enough for client navigations.** It
passes a page-load check but leaves sibling client navigations blocking; put passes a page-load check but leaves sibling client navigations blocking; put
......
This diff is collapsed.
...@@ -107,13 +107,19 @@ await instant(page, async () => { ...@@ -107,13 +107,19 @@ await instant(page, async () => {
await expect(page.getByTestId('<b>-content')).toBeVisible() // streams after release await expect(page.getByTestId('<b>-content')).toBeVisible() // streams after release
``` ```
The same three assertions apply to the initial-load `page.goto()` form. The cookie gates the The two **gated-half** assertions (shell visible, deferred content `toHaveCount(0)`) apply to the
deferred content identically for both: on a soft navigation the client lock gates dynamic-data initial-load `page.goto()` form too. The cookie gates the deferred content identically for both:
writes; on an initial load the server honors the cookie on the document request (set via on a soft navigation the client lock gates dynamic-data writes; on an initial load the server
`addCookies()` before navigation, scoped by `baseURL`) and suspends dynamic data, independent of honors the cookie on the document request (set via `addCookies()` before navigation, scoped by
whether the route was previously rendered or cached. So the initial-load `toHaveCount(0)` gated `baseURL`) and suspends dynamic data, independent of whether the route was previously rendered or
half is as valid as the soft-nav one; it needs no fresh browser context and no cache-busting cached. So the initial-load `toHaveCount(0)` gated half is as valid as the soft-nav one; it needs
query param. The mechanism is in `reference/red-test-robustness.md`. no fresh browser context and no cache-busting query param.
The **post-release** assertion (`getByTestId('<b>-content').toBeVisible()` after the `instant()`
block) is soft-nav only. On an initial load the document was already emitted under the lock, so
nothing streams in after release; drop that assertion from the initial-load test, or
`page.reload()` first to fetch an unlocked document. The mechanism is in
`reference/red-test-robustness.md`.
## Baseline scaffold: do not ship ## Baseline scaffold: do not ship
......
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