Unverified Commit 1d8e8381 authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Replicate production prefetch shells for instant navigations in dev (#95067)

The Instant Navigation lock makes a development render reflect the
route's prefetched state: while the lock is held, a navigation shows
only what was prefetched and keeps navigation-time data deferred. Both
the `instant()` testing API from `@next/playwright` and the Instant
Navigation devtools rely on it. The client side of that behavior,
restricting the navigation read to the prefetched shell unless the link
opts into a runtime prefetch and ignoring cache entries acquired before
the lock, landed separately in #95150, which this change builds on. What
remained were two ways the development app render diverged from what a
production build serves, both in `app-page.ts`, so this PR contains no
client-side router changes.

While the lock is held, the app render now permits an empty static
shell. A route that reads dynamic data such as `cookies()` outside any
`<Suspense>` boundary has no static shell, so the on-demand render
previously threw a static generation bailout, served an error page, and
entered a `/_tree` redirect loop that committed the blocked data.
Permitting an empty shell lets the render emit the shell instead. The
override is scoped to the prefetch render made while the lock is held, a
document request or a `'1'` static prefetch; a regular dynamic
navigation, including the one that commits once the lock releases, runs
without it. So the validation that flags a blocking route is not
weakened: production validation runs at build time, and the development
validation still runs and is shown in the dev overlay.

The development fallback-shell render now reads the per-URL
`fallbackParams` request meta that base-server derives for the requested
URL, so the instant shell defers exactly the params a production
prefetch would: `generateStaticParams`-covered params resolve in the
shell and only the uncovered ones are deferred. When the URL is fully
covered the meta is absent and nothing is deferred. That per-URL
computation landed in #95066, which this change depends on.

This suite now runs with App Shells enabled, which is the default under
Cache Components. #94516 had temporarily forced it back to `false` here
while the prefetch behavior settled and left the migration as a
follow-up; re-enabling it is what lets these tests exercise the
app-shell prefetch path the changes above target.

New end-to-end coverage exercises the cases this render path affects. A
deeper-segment blocking navigation must stay parked on the committed
parent while the lock is held. Two mixed routes pair a
`generateStaticParams`-covered param with an uncovered one: a plain
route where a normal navigation surfaces only the covered param while
the uncovered param and a request-time `connection()` sibling stay
deferred, and an `allow-runtime` route where a `prefetch={true}` link
additionally surfaces the uncovered param from the runtime prefetch. A
blocking route that reads request data outside any `<Suspense>` boundary
cannot be built for production, so it lives in a development-only
fixture, guarded so the production job registers only a placeholder. The
default fixture moves the dev-tools indicator to `bottom-right` so the
Instant Navigation panel does not overlap the left-aligned test links
during a navigation.

One client-navigation cookie case is marked `it.failing`: on a
non-partial route the speculative static prefetch is fuller than the
app-shell render and supersedes it in the segment cache, so the cookie
that only the app shell carries never reaches the instant shell.
#95150's shell handling only engages under partial prefetching. Closing
this needs a separate server-side change so that a route reading
`cookies()` during app-shell generation opts into either partial
prefetching, where only the app shell is fetched and nothing fuller can
supersede it, or a runtime prefetch, where the speculative prefetch
carries the cookie and no longer regresses what the app shell initially
showed.
parent 8c6cb0e0
......@@ -797,8 +797,10 @@ export async function handler(
postponed,
fallbackRouteParams,
forceStaticRender,
allowEmptyStaticShell,
}: {
span?: Span
allowEmptyStaticShell?: boolean
/**
* The postponed data for this render. This is only provided when resuming
......@@ -845,6 +847,7 @@ export async function handler(
routeModule,
page: srcPage,
postponed,
allowEmptyStaticShell,
shouldWaitOnAllReady,
serveStreamingMetadata,
supportsDynamicResponse:
......@@ -1171,22 +1174,33 @@ export async function handler(
fallbackRouteParams = null
}
} else {
// In dev, the prerender manifest isn't populated for ad-hoc
// prefetches. The outer `!isPrerendered` guard means every URL
// reaching this block has params not covered by
// `generateStaticParams`, so the worst-case fallback set —
// every dynamic segment from the loader tree — matches what a
// static prerender would use. This keeps the prefetch response
// from baking resolved param values into the shell.
//
// `isDebugStaticShell` covers the `?__nextppronly=1` query and
// the Instant Navigation testing cookie; `isDebugFallbackShell`
// is the explicit fallback-shell debug flow.
if (isDebugStaticShell || isDebugFallbackShell) {
// In dev the prerender manifest isn't populated for ad-hoc
// prefetches (`fallbackMode` is undefined for not-fully-generated
// routes, so the on-demand manifest write is skipped, and
// `getPrerenderManifest` is cached regardless). So
// `prerenderInfo` is unavailable here. Instead base-server
// derives the per-URL fallback set from the dev `getStaticPaths`
// result and threads it via the `fallbackParams` request meta —
// the most-specific prerendered route matching this URL, so
// `generateStaticParams`-covered params resolve in the shell and
// only the uncovered ones are deferred, matching what a
// production build serves. `isDebugFallbackShell` (the explicit
// fallback-shell debug flow) still forces the worst case.
if (isDebugFallbackShell) {
fallbackRouteParams = getFallbackRouteParams(
normalizedSrcPage,
routeModule
)
} else if (isDebugStaticShell) {
// base-server threads the per-URL fallback set via the
// `fallbackParams` meta for every dev Cache Components dynamic
// request, so reuse it as the fallback route params for this
// shell render. It only sets the meta for routes that still
// have uncovered params, so an absent meta means this URL is
// fully covered by `generateStaticParams` and there is nothing
// to defer (`null`).
fallbackRouteParams =
getRequestMeta(req, 'fallbackParams') ?? null
} else {
fallbackRouteParams = null
}
......@@ -1221,6 +1235,7 @@ export async function handler(
// more specific cache entry for later requests.
fallbackRouteParams,
forceStaticRender: true,
allowEmptyStaticShell: isInstantNavigationTest || undefined,
}),
waitUntil: ctx.waitUntil,
isMinimalMode,
......@@ -1499,6 +1514,7 @@ export async function handler(
postponed,
fallbackRouteParams,
forceStaticRender,
allowEmptyStaticShell: isInstantNavigationTest || undefined,
})
} catch (err) {
// if this is a background revalidate we need to report
......
import { cookies } from 'next/headers'
// A blocking route with a `generateStaticParams`-covered param. The page awaits
// `params` BEFORE reading `cookies()`. In the app-shell prefetch ('3') all
// params are withheld (app shells carry session data like cookies, but no
// params — not even static ones), so `await params` suspends here and the
// `cookies()` read is never reached — keeping the cookie value OUT of the app
// shell. (A cookie-only route with no preceding param access would instead
// include the cookie in the app shell, since cookies are allowed there — that
// would not be the blocking behavior we want to assert.)
//
// `cookies()` is still read outside any <Suspense>, so the route has no static
// shell and remains request-time blocking. It fails `next build`'s static-shell
// validation, which is why it lives in this dev-only fixture. Under instant()
// the cookie value must NOT commit while the lock is held; it only streams in
// after the lock releases.
export function generateStaticParams() {
return [{ id: 'x' }]
}
export default async function BlockingCookiesPage({
params,
}: {
params: Promise<{ id: string }>
}) {
await params
const cookieStore = await cookies()
const testCookie = cookieStore.get('testCookie')
return (
<div data-testid="blocking-cookie-value">
testCookie: {testCookie?.value ?? 'not set'}
</div>
)
}
import { ReactNode } from 'react'
export default function Root({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import Link from 'next/link'
export default function HomePage() {
return (
<div>
<h1 data-testid="home-title">Instant Navigation API Test (blocking)</h1>
<ul>
<li>
<Link href="/blocking-cookies/x" id="link-to-blocking-cookies">
Go to blocking cookies page
</Link>
</li>
</ul>
</div>
)
}
/**
* @type {import('next').NextConfig}
*/
const nextConfig = {
cacheComponents: true,
experimental: {
// Matches the `default` fixture: App Shells is implicit via
// `cacheComponents`, `prefetchInlining` stays `false`. This fixture holds
// routes with no static shell (a dynamic read outside any `<Suspense>`),
// which fail `next build`'s static-shell validation, so its suite runs in
// dev only and is never production-built.
exposeTestingApiInProductionBuild: true,
prefetchInlining: false,
},
}
module.exports = nextConfig
import { cookies } from 'next/headers'
// The deeper, blocking segment of the fallback route: reads request-time
// `cookies()` and has no <Suspense> of its own, so it has no static shell.
// Under instant() the navigation here must stay parked on the committed parent;
// the cookie value must not commit while the lock is held.
export default function ScopePage() {
return (
<div>
<h1 data-testid="blocking-scope-title">Scope</h1>
<Secret />
</div>
)
}
async function Secret() {
const cookieStore = await cookies()
return (
<div data-testid="blocking-secret">
testCookie: {cookieStore.get('testCookie')?.value ?? 'not set'}
</div>
)
}
import { ReactNode, Suspense } from 'react'
// `[lang]` is covered by generateStaticParams, so `/blocking-fallback/en` is a
// committed landing route. `[scope]` is not covered, so
// `/blocking-fallback/en/s1` is an on-demand fallback route. This layout owns
// the only <Suspense> boundary above that deeper segment, so its request-time
// work is held here rather than bailing the whole route.
export function generateStaticParams() {
return [{ lang: 'en' }]
}
export default function LangLayout({ children }: { children: ReactNode }) {
return (
<>
<p data-testid="blocking-parent">parent</p>
<Suspense fallback={<p data-testid="blocking-shell">shell</p>}>
{children}
</Suspense>
</>
)
}
import Link from 'next/link'
export default function LangHome() {
return (
<div>
<h1 data-testid="blocking-landing">Landing</h1>
<Link href="/blocking-fallback/en/s1" id="to-blocking-scope">
Go deeper
</Link>
</div>
)
}
import { Suspense } from 'react'
import { cookies } from 'next/headers'
// Same shape as `cookies-page` (cookies read inside a <Suspense>), but the
// component awaits a `generateStaticParams`-covered `params` BEFORE reading
// `cookies()`. The app-shell prefetch withholds all params, so it suspends at
// `await params` and never reaches the cookie read — keeping the cookie value
// OUT of the instant shell. Contrast with `cookies-page`, where the cookie (a
// session value carried by the app shell) appears in the instant shell because
// nothing gates it.
export function generateStaticParams() {
return [{ id: 'x' }]
}
export default function CookiesWithParamPage({
params,
}: {
params: Promise<{ id: string }>
}) {
return (
<div>
<h1 data-testid="cookies-param-title">Cookies With Param Page</h1>
<Suspense
fallback={
<div data-testid="cookies-param-fallback">Loading cookies...</div>
}
>
<CookieContent params={params} />
</Suspense>
</div>
)
}
async function CookieContent({ params }: { params: Promise<{ id: string }> }) {
await params
const cookieStore = await cookies()
const testCookie = cookieStore.get('testCookie')
return (
<div data-testid="cookies-param-value">
testCookie: {testCookie?.value ?? 'not set'}
</div>
)
}
import { Suspense } from 'react'
import { connection } from 'next/server'
// A route that mixes a `generateStaticParams`-covered param (`lang`, resolved
// in the static shell by the parent layout) with an uncovered one (`slug`).
// The route opts into runtime prefetching, so `slug` is resolved by the runtime
// prefetch rather than the static shell. Under instant() we expect both to
// surface — `lang` from the static shell, `slug` from the runtime prefetch —
// while the genuinely request-time `connection()` sibling stays deferred until
// the lock releases.
export const instant: {
unstable_samples: Array<{ params: { lang: string; slug: string } }>
} = {
unstable_samples: [{ params: { lang: 'en', slug: 'anything' } }],
}
export const prefetch = 'allow-runtime'
export default function MixedParamsRuntimePage({
params,
}: {
params: Promise<{ lang: string; slug: string }>
}) {
return (
<div>
<h1 data-testid="mixed-params-runtime-title">
Mixed Params Runtime Page
</h1>
<Suspense
fallback={<div data-testid="mixed-slug-fallback">Loading slug...</div>}
>
<SlugContent params={params} />
</Suspense>
<Suspense
fallback={
<div data-testid="mixed-dynamic-fallback">Loading dynamic...</div>
}
>
<DynamicContent />
</Suspense>
</div>
)
}
async function SlugContent({
params,
}: {
params: Promise<{ lang: string; slug: string }>
}) {
const { slug } = await params
return <div data-testid="mixed-slug-value">slug: {slug}</div>
}
async function DynamicContent() {
await connection()
return <div data-testid="mixed-dynamic-value">dynamic content</div>
}
import { ReactNode } from 'react'
// `lang` IS covered by `generateStaticParams`, so it is part of the static
// shell. The layout awaits it OUTSIDE <Suspense>; under instant() the per-URL
// shell must resolve the covered `lang` here (not defer it), exactly like the
// build's prebuilt `en/[slug]` shell.
export function generateStaticParams() {
return [{ lang: 'en' }]
}
export default async function MixedLangLayout({
children,
params,
}: {
children: ReactNode
params: Promise<{ lang: string }>
}) {
const { lang } = await params
return (
<>
<p data-testid="mixed-lang">lang: {lang}</p>
{children}
</>
)
}
import { Suspense } from 'react'
import { connection } from 'next/server'
// A route mixing a `generateStaticParams`-covered param (`lang`, resolved in
// the static shell by the parent layout) with an uncovered one (`slug`). Unlike
// `mixed-params-runtime`, this route does NOT opt into runtime prefetching, so
// a normal (no `prefetch` prop) navigation carries only the covered `lang` in
// the shell; the uncovered `slug` and the request-time `connection()` sibling
// stay deferred behind their Suspense fallbacks until the navigation completes.
export default function MixedParamsPage({
params,
}: {
params: Promise<{ lang: string; slug: string }>
}) {
return (
<div>
<h1 data-testid="mixed-params-title">Mixed Params Page</h1>
<Suspense
fallback={<div data-testid="mixed-slug-fallback">Loading slug...</div>}
>
<SlugContent params={params} />
</Suspense>
<Suspense
fallback={
<div data-testid="mixed-dynamic-fallback">Loading dynamic...</div>
}
>
<DynamicContent />
</Suspense>
</div>
)
}
async function SlugContent({
params,
}: {
params: Promise<{ lang: string; slug: string }>
}) {
const { slug } = await params
return <div data-testid="mixed-slug-value">slug: {slug}</div>
}
async function DynamicContent() {
await connection()
return <div data-testid="mixed-dynamic-value">dynamic content</div>
}
import { ReactNode } from 'react'
// `lang` IS covered by `generateStaticParams`, so it is part of the static
// shell. The layout awaits it OUTSIDE <Suspense>; under instant() the per-URL
// shell resolves the covered `lang` here (not deferred), exactly like the
// build's prebuilt `en/[slug]` shell.
export function generateStaticParams() {
return [{ lang: 'en' }]
}
export default async function MixedLangLayout({
children,
params,
}: {
children: ReactNode
params: Promise<{ lang: string }>
}) {
const { lang } = await params
return (
<>
<p data-testid="mixed-lang">lang: {lang}</p>
{children}
</>
)
}
......@@ -4,71 +4,139 @@ export default function HomePage() {
return (
<div>
<h1 data-testid="home-title">Instant Navigation API Test</h1>
<Link href="/target-page" id="link-to-target">
Go to target page
</Link>
<Link
href="/runtime-prefetch-target?myParam=testValue"
id="link-to-runtime-prefetch"
>
Go to runtime prefetch target
</Link>
<Link
href="/full-prefetch-target"
prefetch={true}
id="link-to-full-prefetch"
>
Go to full prefetch target
</Link>
<Link href="/cookies-page" id="link-to-cookies-page">
Go to cookies page
</Link>
<Link href="/dynamic-params/unknown" id="link-to-dynamic-params">
Go to dynamic params page
</Link>
<Link href="/dynamic-params/hello" id="link-to-static-dynamic-params">
Go to static dynamic params page
</Link>
<Link href="/ungenerated-params/anything" id="link-to-ungenerated-params">
Go to ungenerated params page
</Link>
<Link
href="/ungenerated-params-runtime/anything"
id="link-to-ungenerated-params-runtime"
>
Go to ungenerated params runtime page
</Link>
<Link href="/search-params-page?foo=bar" id="link-to-search-params">
Go to search params page
</Link>
{/* Plain anchor for MPA navigation testing (bypasses client-side routing) */}
<a href="/target-page" id="plain-link-to-target">
Go to target page (MPA)
</a>
<a href="/cookies-page" id="plain-link-to-cookies-page">
Go to cookies page (MPA)
</a>
<a href="/dynamic-params/unknown" id="plain-link-to-dynamic-params">
Go to dynamic params page (MPA)
</a>
<a href="/dynamic-params/hello" id="plain-link-to-static-dynamic-params">
Go to static dynamic params page (MPA)
</a>
<a href="/search-params-page?foo=bar" id="plain-link-to-search-params">
Go to search params page (MPA)
</a>
<Link href="/client-fetch-page" id="link-to-client-fetch">
Go to client fetch page
</Link>
<a href="/client-fetch-page" id="plain-link-to-client-fetch">
Go to client fetch page (MPA)
</a>
<Link href="/root-blocking-page" id="link-to-root-blocking">
Go to blocking route (no static shell)
</Link>
<a href="/root-blocking-page" id="plain-link-to-root-blocking">
Go to blocking route (no static shell) (MPA)
</a>
<ul>
<li>
<Link href="/target-page" id="link-to-target">
Go to target page
</Link>
</li>
<li>
<Link
href="/runtime-prefetch-target?myParam=testValue"
id="link-to-runtime-prefetch"
prefetch
>
Go to runtime prefetch target
</Link>
</li>
<li>
<Link
href="/full-prefetch-target"
prefetch={true}
id="link-to-full-prefetch"
>
Go to full prefetch target
</Link>
</li>
<li>
<Link href="/cookies-page" id="link-to-cookies-page">
Go to cookies page
</Link>
</li>
<li>
<Link href="/cookies-with-param/x" id="link-to-cookies-with-param">
Go to cookies-with-param page
</Link>
</li>
<li>
<Link href="/dynamic-params/unknown" id="link-to-dynamic-params">
Go to dynamic params page
</Link>
</li>
<li>
<Link href="/dynamic-params/hello" id="link-to-static-dynamic-params">
Go to static dynamic params page
</Link>
</li>
<li>
<Link
href="/ungenerated-params/anything"
id="link-to-ungenerated-params"
>
Go to ungenerated params page
</Link>
</li>
<li>
<Link
href="/ungenerated-params-runtime/anything"
id="link-to-ungenerated-params-runtime"
prefetch
>
Go to ungenerated params runtime page
</Link>
</li>
<li>
<Link
href="/mixed-params-runtime/en/anything"
id="link-to-mixed-params-runtime"
prefetch
>
Go to mixed params runtime page
</Link>
</li>
<li>
<Link href="/mixed-params/en/anything" id="link-to-mixed-params">
Go to mixed params page (no runtime)
</Link>
</li>
<li>
<Link href="/search-params-page?foo=bar" id="link-to-search-params">
Go to search params page
</Link>
</li>
{/* Plain anchor for MPA navigation testing (bypasses client-side routing) */}
<li>
<a href="/target-page" id="plain-link-to-target">
Go to target page (MPA)
</a>
</li>
<li>
<a href="/cookies-page" id="plain-link-to-cookies-page">
Go to cookies page (MPA)
</a>
</li>
<li>
<a href="/dynamic-params/unknown" id="plain-link-to-dynamic-params">
Go to dynamic params page (MPA)
</a>
</li>
<li>
<a
href="/dynamic-params/hello"
id="plain-link-to-static-dynamic-params"
>
Go to static dynamic params page (MPA)
</a>
</li>
<li>
<a
href="/search-params-page?foo=bar"
id="plain-link-to-search-params"
>
Go to search params page (MPA)
</a>
</li>
<li>
<Link href="/client-fetch-page" id="link-to-client-fetch">
Go to client fetch page
</Link>
</li>
<li>
<a href="/client-fetch-page" id="plain-link-to-client-fetch">
Go to client fetch page (MPA)
</a>
</li>
<li>
<Link href="/root-blocking-page" id="link-to-root-blocking">
Go to blocking route (no static shell)
</Link>
</li>
<li>
<a href="/root-blocking-page" id="plain-link-to-root-blocking">
Go to blocking route (no static shell) (MPA)
</a>
</li>
</ul>
</div>
)
}
......@@ -3,10 +3,14 @@
*/
const nextConfig = {
cacheComponents: true,
// The Instant Navigation devtools panel defaults to the dev tools position
// (bottom-left). This suite's links are a left-aligned vertical list, so a
// bottom-left panel overlaps them and intercepts clicks; move it aside.
devIndicators: { position: 'bottom-right' },
experimental: {
// TODO(appShells): migrate this test to the two-phase (app shell +
// per-page data) prefetch behavior, then remove this override. See #94516.
appShells: false,
// App Shells is enabled implicitly by `cacheComponents`. `prefetchInlining`
// is kept `false` so the non-inlined (speculative per-segment) static
// prefetch path is exercised alongside the app-shell prefetch.
// Enable the testing API in production builds for these tests
exposeTestingApiInProductionBuild: true,
prefetchInlining: false,
......
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