Unverified Commit a0446c5a authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

[Segment Bundling] Bundle static prefetches based on size (#91439)

This is the final step in the segment bundling system. The first commit
ensured correctness when inlining hints are stale or unavailable. The
second taught the build-time hint computation to identify which segments
can be omitted and how parent data flows through disabled segments to
static descendants. This commit makes the server and client act on those
decisions: small static segments are combined into a single prefetch
response rather than fetched individually.

This step is inherently larger than the previous ones. We moved as much
complexity as possible into the earlier commits — the hint bits, the
pass-through logic, the metadata assignment, the safety invariants — but
the server output changes and the client scheduling changes need to land
together to keep behavior coherent.

### Unified response model

The brute-force inlining path that previously existed is removed. Both
the old per-segment behavior and the brute-force "inline everything"
mode are now modeled in terms of the size-based system:

- **Per-segment (flag off):** each segment's response contains only its
own data. This is the behavior when `prefetchInlining` is not enabled,
or when a segment exceeds the size threshold.
- **Size-based (flag on):** setting `prefetchInlining: true` uses
default thresholds (2KB per-segment, 10KB total budget). Segments below
the threshold are bundled into their children's responses. Segments
above it get standalone responses.
- **Brute-force (infinite thresholds):** setting the thresholds to
infinity means every segment is bundled into a single response for the
entire route. The size-based heuristics should make this unnecessary.

There is no separate code path for any of these modes. The same server
and client logic handles all three — the only difference is the hint
bits computed at build time.

### Metadata bundling

The metadata (head/viewport) is bundled into the response of whichever
segment is responsible for it, avoiding a separate metadata fetch in
most cases.

On routes with runtime prefetch, the first runtime segment is
responsible — its response already includes the metadata. On purely
static routes, the first page terminal with budget room gets the
metadata. If no terminal has room, the metadata is fetched separately.

### Independent metadata prefetching

When navigating between sibling routes under a shared runtime layout,
the layout is already cached and no runtime segment request is needed.
But the metadata (head) may differ between siblings. This commit ensures
the metadata is always prefetched independently via a runtime request
when `SubtreeHasRuntimePrefetch` is set on the route tree, even when no
runtime segments need fetching.

### Skipping unnecessary static output

Segments with `instant = false` or runtime prefetch enabled don't
benefit from static prefetch responses. Now the server skips generating
static output for these segments entirely, reducing build output size.
The client also skips creating cache entries for them. They still
participate in the bundle chain as null placeholders — parent data flows
through them to static descendants — but no actual data is produced or
fetched.

This skipping is NOT gated by the `prefetchInlining` feature flag. The
hints that drive it (`HasRuntimePrefetch`, `PrefetchDisabled`) are
computed at build time and embedded in the route tree regardless of
bundling.

### Test plan

The prefetch-inlining test suite covers: basic inlining chains, large
segments that break chains, deep chains, parallel routes, dynamic routes
with concrete params, runtime prefetch boundaries (both leaf and
pass-through), `instant = false` segments, stale hint recovery, metadata
assignment, the `instant = false` at root fallback, independent metadata
prefetching for routes with runtime data in the head, and runtime
parallel slot pass-through. Each test verifies both the hint computation
(via snapshot assertions) and the actual navigation behavior (prefetch
via link accordion, then navigate to confirm data was prefetched).
parent 56993a6c
...@@ -55,6 +55,16 @@ export default function Page() { ...@@ -55,6 +55,16 @@ export default function Page() {
Runtime parallel Runtime parallel
</LinkAccordion> </LinkAccordion>
</li> </li>
<li>
<LinkAccordion href="/test-independent-head/a">
Independent head A
</LinkAccordion>
</li>
<li>
<LinkAccordion href="/test-independent-head/b">
Independent head B
</LinkAccordion>
</li>
</ul> </ul>
</div> </div>
) )
......
export default function Page() { export default function Page() {
return <p>Deep page</p> return <p id="page-deep">Deep page</p>
} }
...@@ -4,7 +4,7 @@ export default async function Page({ ...@@ -4,7 +4,7 @@ export default async function Page({
params: Promise<{ slug: string }> params: Promise<{ slug: string }>
}) { }) {
const { slug } = await params const { slug } = await params
return <p>Dynamic page: {slug}</p> return <p id="page-dynamic">{`Dynamic page: ${slug}`}</p>
} }
export function generateStaticParams() { export function generateStaticParams() {
......
import { ReactNode } from 'react'
// This layout does NOT access the [item] param. Its rendered output is
// identical for /test-independent-head/a and /test-independent-head/b,
// so the segment cache can reuse it across both routes.
export default function Layout({ children }: { children: ReactNode }) {
return (
<div>
<p id="item-layout">Item layout</p>
{children}
</div>
)
}
import { LinkAccordion } from '../../../components/link-accordion'
// The page segment itself is fully static — it doesn't access searchParams
// or cookies. Only the metadata accesses searchParams (making the head
// depend on runtime data) and the [item] param (so it differs per route).
// The page segment content is the same for all param values.
export async function generateStaticParams() {
return [{ item: 'a' }, { item: 'b' }]
}
export async function generateMetadata({
params,
searchParams,
}: {
params: Promise<{ item: string }>
searchParams: Promise<{ q?: string }>
}) {
const { item } = await params
const { q } = await searchParams
return { title: `Independent Head Title: ${item}${q ? ` (q=${q})` : ''}` }
}
export default async function Page({
params,
}: {
params: Promise<{ item: string }>
}) {
const { item } = await params
const sibling = item === 'a' ? 'b' : 'a'
return (
<div>
<p id="page-independent-head">Independent head page</p>
<LinkAccordion href={`/test-independent-head/${sibling}`}>
Go to {sibling}
</LinkAccordion>
</div>
)
}
import { ReactNode, Suspense } from 'react'
import { cookies } from 'next/headers'
// This layout uses runtime prefetching and sits ABOVE the [item] param.
// It's shared between /test-independent-head/a and /test-independent-head/b.
// Once cached from the first prefetch, a subsequent prefetch to a sibling
// page won't need a runtime request for this layout — it's already cached.
export const unstable_instant = {
prefetch: 'runtime',
samples: [
{
cookies: [{ name: 'theme', value: 'default' }],
searchParams: { q: null },
params: { item: 'a' },
},
],
}
async function LayoutContent({ children }: { children: ReactNode }) {
const cookieStore = await cookies()
const theme = cookieStore.get('theme')?.value ?? 'default'
return (
<div>
<p id="layout-independent-head">Shared layout (theme: {theme})</p>
{children}
</div>
)
}
export default function Layout({ children }: { children: ReactNode }) {
return (
<Suspense fallback={<p>Loading layout...</p>}>
<LayoutContent>{children}</LayoutContent>
</Suspense>
)
}
export default function Page() { export default function Page() {
return <p>Outlined test page</p> return <p id="page-outlined">Outlined test page</p>
} }
export default function Page() { export default function Page() {
return <p>Main content</p> return <p id="page-parallel">Main content</p>
} }
export default function Page() { export default function Page() {
return <p>After page</p> return <p id="page-restart">After page</p>
} }
export default function Page() { export default function Page() {
return <p id="page-runtime-parallel">Main content</p> return <p id="page-runtime-parallel">Runtime parallel main content</p>
} }
export default function SmallChainPage() { export default function SmallChainPage() {
return <p>Small chain page</p> return <p id="page-small-chain">Small chain page</p>
} }
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