Unverified Commit 2aea494e authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Extract App Shell from static prefetches (#94095)

Adds support for extracting an App Shell from a more concrete prerender
response. The server sends down a byte offset that represents the subset
of the stream that corresponds to the reusable App Shell.

This does _not_ yet implement shell extraction for per-segment prefetch
responses. Implementing this adds an additional layer of complexity,
because those responses are generated during a separate phase of the
build process. We do intend to implement this, but it's a non-essential
optimization that can come later.

This also does not yet implement shell extraction from a navigation
response (the Cached Navigations feature), though both features are
based on essentially the same mechanism. I'm deferring this to a
subsequent PR because some of the existing implementation needs to be
rethought in light of the new App Shells based model; for example, the
"static stage" boundary might not make sense to track separately from
the App Shell.

The main practical upshot of the PR is that if you have a fully
statically prerendered page with no dynamic holes, that page's App Shell
can now be fetched by the client without incurring any runtime server
execution cost: the server will return the full static page, and the
client will extract the App Shell from that concrete response.

<!-- NEXT_JS_LLM_PR -->
parent b9f067fb
...@@ -11,14 +11,14 @@ import { ...@@ -11,14 +11,14 @@ import {
getStaleAt, getStaleAt,
processRuntimePrefetchStream, processRuntimePrefetchStream,
writeDynamicRenderResponseIntoCache, writeDynamicRenderResponseIntoCache,
writeStaticStageResponseIntoCache, writePrerenderResponseIntoCache,
} from '../segment-cache/cache' } from '../segment-cache/cache'
import { FetchStrategy } from '../segment-cache/types' import { FetchStrategy } from '../segment-cache/types'
import { import {
UnknownDynamicStaleTime, UnknownDynamicStaleTime,
computeDynamicStaleAt, computeDynamicStaleAt,
} from '../segment-cache/bfcache' } from '../segment-cache/bfcache'
import { decodeStaticStage } from './fetch-server-response' import { decodeStageUntilBoundary } from './fetch-server-response'
import { discoverKnownRoute } from '../segment-cache/optimistic-routes' import { discoverKnownRoute } from '../segment-cache/optimistic-routes'
import type { NormalizedSearch } from '../segment-cache/cache-key' import type { NormalizedSearch } from '../segment-cache/cache-key'
...@@ -117,6 +117,10 @@ export function createInitialRouterState({ ...@@ -117,6 +117,10 @@ export function createInitialRouterState({
false // hasDynamicRewrite false // hasDynamicRewrite
) )
// TODO: Implement Shell extraction as part of Cached Navigations.
// Intentionally holding off on doing this until we decide how the Cached
// Navigations behavior should work in combination with App Shells.
// Write the initial seed data into the segment cache so subsequent // Write the initial seed data into the segment cache so subsequent
// navigations to the initial page can serve cached segments instantly. // navigations to the initial page can serve cached segments instantly.
if (initialSeedData !== null && initialStaleTime !== undefined) { if (initialSeedData !== null && initialStaleTime !== undefined) {
...@@ -126,17 +130,22 @@ export function createInitialRouterState({ ...@@ -126,17 +130,22 @@ export function createInitialRouterState({
) { ) {
// Partially static page — truncate the cloned Flight stream at the // Partially static page — truncate the cloned Flight stream at the
// static stage byte boundary, decode, and cache the static subset. // static stage byte boundary, decode, and cache the static subset.
decodeStaticStage<InitialRSCPayload>( // Promise.resolve wraps the Flight-deserialized thenable into a
initialFlightStreamForCache, // native Promise so we can chain `.then` on it safely.
initialStaticStageByteLength, Promise.resolve(initialStaticStageByteLength)
undefined .then(async (byteLength) => {
) const staticStageResponse =
.then(async (staticStageResponse) => { await decodeStageUntilBoundary<InitialRSCPayload>(
initialFlightStreamForCache,
byteLength,
undefined
)
const now = Date.now() const now = Date.now()
const staleAt = await getStaleAt(now, staticStageResponse.s) const staleAt = await getStaleAt(now, staticStageResponse.s)
writeStaticStageResponseIntoCache( writePrerenderResponseIntoCache(
now, now,
FetchStrategy.PPR,
staticStageResponse.f, staticStageResponse.f,
undefined, // no build ID mismatch check for initial HTML undefined, // no build ID mismatch check for initial HTML
staticStageResponse.h, staticStageResponse.h,
...@@ -160,8 +169,9 @@ export function createInitialRouterState({ ...@@ -160,8 +169,9 @@ export function createInitialRouterState({
getStaleAt(now, initialStaleTime) getStaleAt(now, initialStaleTime)
.then((staleAt) => { .then((staleAt) => {
writeStaticStageResponseIntoCache( writePrerenderResponseIntoCache(
now, now,
FetchStrategy.PPR,
initialFlightData, initialFlightData,
undefined, // buildId — not applicable for initial HTML undefined, // buildId — not applicable for initial HTML
initialHeadVaryParams, initialHeadVaryParams,
......
...@@ -357,7 +357,12 @@ export type RSCResponse<T> = { ...@@ -357,7 +357,12 @@ export type RSCResponse<T> = {
type FetchResponseCacheData = { type FetchResponseCacheData = {
isResponsePartial: boolean isResponsePartial: boolean
responseBodyClone?: ReadableStream<Uint8Array> // Separate clones of the response body for stage extraction. The static
// stage and shell stage are extracted from independent reads, so each
// needs its own ReadableStream. Both are derived from a chain of `tee()`
// calls in `processFetch`.
staticBodyClone?: ReadableStream<Uint8Array>
shellBodyClone?: ReadableStream<Uint8Array>
} }
/** /**
...@@ -389,9 +394,16 @@ export async function processFetch(response: Response): Promise<{ ...@@ -389,9 +394,16 @@ export async function processFetch(response: Response): Promise<{
let cacheData: FetchResponseCacheData let cacheData: FetchResponseCacheData
if (process.env.__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS) { if (process.env.__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS) {
const [stream1, stream2] = stream.tee() // Three readers needed: the main Flight decoder, the static-stage
// extractor, and the shell-stage extractor. Tee twice.
const [stream1, rest] = stream.tee()
const [staticBodyClone, shellBodyClone] = rest.tee()
responseStream = stream1 responseStream = stream1
cacheData = { isResponsePartial: isPartial, responseBodyClone: stream2 } cacheData = {
isResponsePartial: isPartial,
staticBodyClone,
shellBodyClone,
}
} else { } else {
responseStream = stream responseStream = stream
cacheData = { isResponsePartial: isPartial } cacheData = { isResponsePartial: isPartial }
...@@ -433,12 +445,12 @@ export async function resolveStaticStageData< ...@@ -433,12 +445,12 @@ export async function resolveStaticStageData<
flightResponse: T, flightResponse: T,
headers: RequestHeaders | undefined headers: RequestHeaders | undefined
): Promise<StaticStageData<T> | null> { ): Promise<StaticStageData<T> | null> {
const { isResponsePartial, responseBodyClone } = cacheData const { isResponsePartial, staticBodyClone } = cacheData
if (responseBodyClone) { if (staticBodyClone) {
if (!isResponsePartial) { if (!isResponsePartial) {
// Fully static — cache the entire decoded response as-is. // Fully static — cache the entire decoded response as-is.
responseBodyClone.cancel() staticBodyClone.cancel()
return { response: flightResponse, isResponsePartial: false } return { response: flightResponse, isResponsePartial: false }
} }
...@@ -446,9 +458,10 @@ export async function resolveStaticStageData< ...@@ -446,9 +458,10 @@ export async function resolveStaticStageData<
if (flightResponse.l !== undefined) { if (flightResponse.l !== undefined) {
// Partially static — truncate the body clone at the byte boundary and // Partially static — truncate the body clone at the byte boundary and
// decode it. // decode it.
const response = await decodeStaticStage<T>( const staticStageByteLength = await flightResponse.l
responseBodyClone, const response = await decodeStageUntilBoundary<T>(
flightResponse.l, staticBodyClone,
staticStageByteLength,
headers headers
) )
...@@ -456,30 +469,69 @@ export async function resolveStaticStageData< ...@@ -456,30 +469,69 @@ export async function resolveStaticStageData<
} }
// No caching — cancel the unused clone. // No caching — cancel the unused clone.
responseBodyClone.cancel() staticBodyClone.cancel()
} }
return null return null
} }
/**
* Resolves the shell stage of a prerender response, performing a separate
* Flight decode of the byte prefix when the shell differs from the main
* response. Returns null when no separate decode is needed:
*
* - `a === undefined`: server didn't emit shell stage info.
* - `a` resolves to `null`: the shell IS the main response — the caller can
* reuse the existing decoded `flightResponse` if it needs a shell payload.
*
* Returns the decoded shell payload when `a` resolves to a number, i.e.
* the shell is a strict prefix of the response and requires a separate
* decode at that byte boundary.
*/
export async function resolveShellStageData<
T extends NavigationFlightResponse | InitialRSCPayload,
>(
cacheData: FetchResponseCacheData,
flightResponse: T,
headers: RequestHeaders | undefined
): Promise<T | null> {
const { shellBodyClone } = cacheData
if (!shellBodyClone) {
return null
}
if (flightResponse.a === undefined) {
shellBodyClone.cancel()
return null
}
const shellByteLength = await flightResponse.a
if (shellByteLength === null) {
// Shell == main response — caller reuses the existing flightResponse.
shellBodyClone.cancel()
return null
}
return decodeStageUntilBoundary<T>(shellBodyClone, shellByteLength, headers)
}
/** /**
* Truncates and buffers a Flight stream clone at the given byte boundary and * Truncates and buffers a Flight stream clone at the given byte boundary and
* decodes the static stage prefix. Used by both the navigation path and the * decodes the prefix as a Flight payload. Used by the static-stage and
* initial HTML hydration path. * shell-stage extraction helpers.
*/ */
export async function decodeStaticStage<T>( export async function decodeStageUntilBoundary<T>(
responseBodyClone: ReadableStream<Uint8Array>, responseBodyClone: ReadableStream<Uint8Array>,
staticStageByteLengthPromise: Promise<number>, byteLength: number,
headers: RequestHeaders | undefined headers: RequestHeaders | undefined
): Promise<T> { ): Promise<T> {
const staticStageByteLength = await staticStageByteLengthPromise
// Buffer the truncated stream into a single chunk before passing it to // Buffer the truncated stream into a single chunk before passing it to
// Flight. This ensures all model data is available synchronously, which is // Flight. This ensures all model data is available synchronously, which is
// required for readVaryParams to synchronously read the thenable status. // required for readVaryParams to synchronously read the thenable status.
const { stream } = await createNonTaskyPrefetchResponseStream( const { stream } = await createNonTaskyPrefetchResponseStream(
responseBodyClone, responseBodyClone,
staticStageByteLength byteLength
) )
return createFromNextReadableStream<T>(stream, headers, { return createFromNextReadableStream<T>(stream, headers, {
......
...@@ -35,7 +35,7 @@ import { ...@@ -35,7 +35,7 @@ import {
markRouteEntryAsDynamicRewrite, markRouteEntryAsDynamicRewrite,
invalidateRouteCacheEntries, invalidateRouteCacheEntries,
getStaleAt, getStaleAt,
writeStaticStageResponseIntoCache, writePrerenderResponseIntoCache,
processRuntimePrefetchStream, processRuntimePrefetchStream,
writeDynamicRenderResponseIntoCache, writeDynamicRenderResponseIntoCache,
EntryStatus, EntryStatus,
...@@ -1737,6 +1737,9 @@ async function fetchMissingDynamicData( ...@@ -1737,6 +1737,9 @@ async function fetchMissingDynamicData(
await waitForNavigationLock() await waitForNavigationLock()
} }
// TODO: Implement Shell extraction as part of Cached Navigations.
// Intentionally holding off on doing this until we decide how the Cached
// Navigations behavior should work in combination with App Shells.
if (routeCacheEntry !== null && result.staticStageData !== null) { if (routeCacheEntry !== null && result.staticStageData !== null) {
const { response: staticStageResponse, isResponsePartial } = const { response: staticStageResponse, isResponsePartial } =
result.staticStageData result.staticStageData
...@@ -1747,8 +1750,9 @@ async function fetchMissingDynamicData( ...@@ -1747,8 +1750,9 @@ async function fetchMissingDynamicData(
result.responseHeaders.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ?? result.responseHeaders.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ??
staticStageResponse.b staticStageResponse.b
writeStaticStageResponseIntoCache( writePrerenderResponseIntoCache(
now, now,
FetchStrategy.PPR,
staticStageResponse.f, staticStageResponse.f,
buildId, buildId,
staticStageResponse.h, staticStageResponse.h,
......
...@@ -27,6 +27,7 @@ import { ...@@ -27,6 +27,7 @@ import {
import { import {
createFetch, createFetch,
createFromNextReadableStream, createFromNextReadableStream,
resolveShellStageData,
type RSCResponse, type RSCResponse,
type RequestHeaders, type RequestHeaders,
} from '../router-reducer/fetch-server-response' } from '../router-reducer/fetch-server-response'
...@@ -2251,16 +2252,109 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2251,16 +2252,109 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
response.cacheData, response.cacheData,
]) ])
const now = Date.now()
const staleAt = await getStaleAt(now, serverData.s, response)
const buildId =
response.headers.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ?? serverData.b
// Check if a reusable App Shell can be extracted from the main response.
let serverDataThatSatisfiesSpawnedEntries: NavigationFlightResponse
// The shell and full response have independent stale times. Track the
// staleAt that corresponds to whatever payload the spawned entries get
// filled with below.
let staleAtForSpawnedEntries = staleAt
if (!process.env.__NEXT_APP_SHELLS || cacheData === null) {
// NOTE: cacheData is always set when Cached Navigations is enabled, and
// therefore when App Shells is enabled. This null check can be removed
// when those flags fully land.
serverDataThatSatisfiesSpawnedEntries = serverData
} else {
const shellStageData = await resolveShellStageData(
cacheData,
serverData,
headers
)
if (shellStageData === null) {
// No App Shell can be extracted. This usually means the entire response
// _is_ the App Shell. The other possibility (for now, until the feature
// is fully stabilized) is that App Shells are not yet enabled. Either
// way, there's nothing extra for us to do: fulfill the pending entries
// using the response from the server.
serverDataThatSatisfiesSpawnedEntries = serverData
} else {
// Successfully extracted an App Shell that is a subset of the main
// response. Depending on the type of prefetch this is, we need to
// decide whether to fulfill the pending entries with the shell or with
// the entire response. In either scenario, we'll be inserting _both_
// versions of the response into the cache; the extra logic is only
// here so that we don't fulfill pending shell entries with something
// that's more concrete than what they expect.
// TODO: The only reason this matters is because during a navigation,
// if a segment is still pending, we render a promise that resolves to
// the eventual value of that segment. But that means we cannot
// eventually resolve that segment to something more concrete than what
// was already requested. Hence the extra logic here. A cleaner way to
// model this, though, is whenever we render a promise that resolves to
// the result of a pending entry, do one additional cache look-up right
// after the promise resolves, to ensure we never get a mismatching
// entry. Leaving this for a follow up.
const shellStaleAt = await getStaleAt(now, shellStageData.s)
if (fetchStrategy === FetchStrategy.RuntimeShell) {
// This is a Shell prefetch, so the pending entries must be fulfilled
// with the shell.
serverDataThatSatisfiesSpawnedEntries = shellStageData
staleAtForSpawnedEntries = shellStaleAt
// Separately, we'll also cache the entire response, by upserting it
// into the cache.
writePrerenderResponseIntoCache(
now,
FetchStrategy.PPR,
serverData.f,
buildId,
serverData.h,
staleAt,
dynamicRequestTree,
renderedSearch,
cacheData.isResponsePartial
)
} else {
// This is _not_ a Shell prefetch, so the pending entries should be
// fulfilled with the entire response.
serverDataThatSatisfiesSpawnedEntries = serverData
// Additionally, we might as well upsert the extracted Shell into the
// cache, too.
// `shellStageData` is only provided in cases where the shell is
// different from the main response. If they are equivalent, this
// branch is skipped. So it follows that any shell data reaches
// this path must be partial -- it does not represent the entire
// UI of the target page.
const isShellStagePartial = true
writePrerenderResponseIntoCache(
now,
FetchStrategy.RuntimeShell,
shellStageData.f,
buildId,
shellStageData.h,
shellStaleAt,
dynamicRequestTree,
renderedSearch,
isShellStagePartial
)
}
}
}
// Read head vary params synchronously. Individual segments carry their // Read head vary params synchronously. Individual segments carry their
// own thenables in CacheNodeSeedData. // own thenables in CacheNodeSeedData.
const headVaryParamsThenable = serverData.h const headVaryParamsThenable = serverDataThatSatisfiesSpawnedEntries.h
const headVaryParams = const headVaryParams =
headVaryParamsThenable !== null headVaryParamsThenable !== null
? readVaryParams(headVaryParamsThenable) ? readVaryParams(headVaryParamsThenable)
: null : null
const now = Date.now()
const staleAt = await getStaleAt(now, serverData.s, response)
// PPRRuntime and RuntimeShell prefetches are partial when the server // PPRRuntime and RuntimeShell prefetches are partial when the server
// marks the response as '~' (Partial). RuntimeShell additionally omits // marks the response as '~' (Partial). RuntimeShell additionally omits
// every dynamic suspense boundary below the App Shell, so its segments // every dynamic suspense boundary below the App Shell, so its segments
...@@ -2271,12 +2365,9 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2271,12 +2365,9 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
(fetchStrategy === FetchStrategy.PPRRuntime && (fetchStrategy === FetchStrategy.PPRRuntime &&
(cacheData?.isResponsePartial ?? false)) (cacheData?.isResponsePartial ?? false))
// Aside from writing the data into the cache, this function also returns const flightDatas = normalizeFlightData(
// the entries that were fulfilled, so we can streamingly update their sizes serverDataThatSatisfiesSpawnedEntries.f
// in the LRU as more data comes in. )
const buildId =
response.headers.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ?? serverData.b
const flightDatas = normalizeFlightData(serverData.f)
if (typeof flightDatas === 'string') { if (typeof flightDatas === 'string') {
rejectSegmentEntriesIfStillPending(spawnedEntries, Date.now() + 10 * 1000) rejectSegmentEntriesIfStillPending(spawnedEntries, Date.now() + 10 * 1000)
return null return null
...@@ -2289,6 +2380,9 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2289,6 +2380,9 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
// Not needed for prefetch responses; pass unknown to use the default. // Not needed for prefetch responses; pass unknown to use the default.
UnknownDynamicStaleTime UnknownDynamicStaleTime
) )
// Aside from writing the data into the cache, this function also returns
// the entries that were fulfilled, so we can streamingly update their sizes
// in the LRU as more data comes in.
fulfilledEntries = writeDynamicRenderResponseIntoCache( fulfilledEntries = writeDynamicRenderResponseIntoCache(
now, now,
fetchStrategy, fetchStrategy,
...@@ -2296,7 +2390,7 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2296,7 +2390,7 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
buildId, buildId,
isResponsePartial, isResponsePartial,
headVaryParams, headVaryParams,
staleAt, staleAtForSpawnedEntries,
navigationSeed, navigationSeed,
spawnedEntries spawnedEntries
) )
...@@ -3004,14 +3098,14 @@ export async function getStaleAt( ...@@ -3004,14 +3098,14 @@ export async function getStaleAt(
} }
/** /**
* Writes the static stage of a navigation response into the segment cache. * Writes a prerender response into the segment cache at the vary path
* When `isResponsePartial` is false, segments are written as non-partial with * determined by `fetchStrategy`. Default segments are skipped (by
* `FetchStrategy.Full` so no dynamic follow-up is needed. Default segments * `writeSeedDataIntoCache`) to avoid caching fallback content that would
* are skipped (by `writeSeedDataIntoCache`) to avoid caching fallback content * block refreshes from overwriting with dynamic data.
* that would block refreshes from overwriting with dynamic data.
*/ */
export function writeStaticStageResponseIntoCache( export function writePrerenderResponseIntoCache(
now: number, now: number,
fetchStrategy: FetchStrategy.PPR | FetchStrategy.RuntimeShell,
flightData: FlightData, flightData: FlightData,
buildId: string | undefined, buildId: string | undefined,
headVaryParamsThenable: VaryParamsThenable | null, headVaryParamsThenable: VaryParamsThenable | null,
...@@ -3020,10 +3114,6 @@ export function writeStaticStageResponseIntoCache( ...@@ -3020,10 +3114,6 @@ export function writeStaticStageResponseIntoCache(
renderedSearch: string, renderedSearch: string,
isResponsePartial: boolean isResponsePartial: boolean
): void { ): void {
const fetchStrategy = isResponsePartial
? FetchStrategy.PPR
: FetchStrategy.Full
const headVaryParams = const headVaryParams =
headVaryParamsThenable !== null headVaryParamsThenable !== null
? readVaryParams(headVaryParamsThenable) ? readVaryParams(headVaryParamsThenable)
......
...@@ -22,7 +22,7 @@ import { ...@@ -22,7 +22,7 @@ import {
deprecated_requestOptimisticRouteCacheEntry, deprecated_requestOptimisticRouteCacheEntry,
convertRootFlightRouterStateToRouteTree, convertRootFlightRouterStateToRouteTree,
getStaleAt, getStaleAt,
writeStaticStageResponseIntoCache, writePrerenderResponseIntoCache,
processRuntimePrefetchStream, processRuntimePrefetchStream,
writeDynamicRenderResponseIntoCache, writeDynamicRenderResponseIntoCache,
type RouteTree, type RouteTree,
...@@ -460,8 +460,13 @@ async function navigateToUnknownRoute( ...@@ -460,8 +460,13 @@ async function navigateToUnknownRoute(
responseHeaders.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ?? responseHeaders.get(NEXT_NAV_DEPLOYMENT_ID_HEADER) ??
staticStageResponse.b staticStageResponse.b
writeStaticStageResponseIntoCache( // TODO: Implement Shell extraction as part of Cached Navigations.
// Intentionally holding off on doing this until we decide how the
// Cached Navigations behavior should work in combination with App
// Shells.
writePrerenderResponseIntoCache(
now, now,
FetchStrategy.PPR,
staticStageResponse.f, staticStageResponse.f,
buildId, buildId,
staticStageResponse.h, staticStageResponse.h,
......
...@@ -790,8 +790,24 @@ function pingRootRouteTree( ...@@ -790,8 +790,24 @@ function pingRootRouteTree(
return PrefetchTaskExitStatus.InProgress return PrefetchTaskExitStatus.InProgress
} }
if (tree.prefetchHints & PrefetchHint.SubtreeHasRuntimePrefetch) { // We may need to do a runtime prefetch for one or more segments.
// The route has segments that require a runtime prefetch. // Before checking, we can do some fast checks to bail out of this
// branch early.
if (
// Do any segments have runtime prefetching configured? This is
// sent by the server as part of the prefetch hints.
tree.prefetchHints & PrefetchHint.SubtreeHasRuntimePrefetch ||
// Are we in the Shell prefetching phase? The Shell phase is allowed
// to perform runtime prefetches even without an explicit opt-in
// because the Shell for a given route is reusable across all given
// params, by definition. So it does not lead to an explosion in
// prefetching costs.
// TODO: In the future, the server could emit a hint to tell us
// *not* to prefetch via a runtime request, via build-time
// heuristics, like if no `cookies()` call was detected. We'll leave
// this optimization for later.
task.phase === PrefetchPhase.Shell
) {
const runtimeStrategy = const runtimeStrategy =
task.phase === PrefetchPhase.Shell task.phase === PrefetchPhase.Shell
? FetchStrategy.RuntimeShell ? FetchStrategy.RuntimeShell
...@@ -1073,7 +1089,22 @@ function pingNewPartOfCacheComponentsTree( ...@@ -1073,7 +1089,22 @@ function pingNewPartOfCacheComponentsTree(
// shared layouts.) Segments in here default to being prefetched statically. // shared layouts.) Segments in here default to being prefetched statically.
// However, if the server instructs us to, we may switch to a runtime // However, if the server instructs us to, we may switch to a runtime
// prefetch instead. Traverse the tree and check at each segment. // prefetch instead. Traverse the tree and check at each segment.
if (tree.prefetchHints & PrefetchHint.HasRuntimePrefetch) { //
// In the Shell phase, every new segment is treated as a runtime-prefetch
// boundary regardless of `HasRuntimePrefetch`, because the Shell is
// reusable across all params by definition (see the matching comment in
// the main scheduler loop).
//
// TODO: If we're reasonably confident that the shell does not depend on
// session data (cookies), we should attempt to prefetch the shell
// statically, instead of via a runtime prefetch. This is an optimization to skip a
// runtime shell request. For fully static pages, it doesn't matter since
// server will respond to even a runtime request with a static response. For
// a partially static page, we can send down a hint from the server.
if (
tree.prefetchHints & PrefetchHint.HasRuntimePrefetch ||
task.phase === PrefetchPhase.Shell
) {
if (task.spawnedRuntimePrefetches === null) { if (task.spawnedRuntimePrefetches === null) {
task.spawnedRuntimePrefetches = new Set([tree.requestKey]) task.spawnedRuntimePrefetches = new Set([tree.requestKey])
} else { } else {
......
...@@ -33,6 +33,26 @@ export default function Page() { ...@@ -33,6 +33,26 @@ export default function Page() {
</Link> </Link>
</li> </li>
</ul> </ul>
<h2>Static posts</h2>
<p>
These posts are fully prerendered at build time. The same shell concept
applies: navigating to a post whose URL was never prefetched should
still render an instant shell while the per-URL content loads.
</p>
<ul>
<li>
<LinkAccordion href="/static-posts/1">Static post 1</LinkAccordion>
</li>
<li>
<LinkAccordion href="/static-posts/2">Static post 2</LinkAccordion>
</li>
<li>
<Link href="/static-posts/124" prefetch={false}>
Unprefetched static post
</Link>
</li>
</ul>
</main> </main>
) )
} }
import { Suspense } from 'react'
type Params = { id: string }
// This page is fully static: no cookies, no `connection()`, no other dynamic
// data. All params are statically known via `generateStaticParams`, so the
// page is prerendered for every URL at build time. With default prefetch
// behavior, the client requests the full prerender; the response carries a
// shell byte offset (`a`) and we extract the shell prefix to cache at the
// Fallback vary path.
export async function generateStaticParams() {
return [{ id: '1' }, { id: '2' }, { id: '124' }, { id: '125' }]
}
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
<Suspense fallback={<p id="static-shell">App shell for static posts</p>}>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
return <p id="static-content">{`Static post ${id}`}</p>
}
...@@ -132,4 +132,57 @@ describe('App Shell prefetching', () => { ...@@ -132,4 +132,57 @@ describe('App Shell prefetching', () => {
.click() .click()
}, [{ includes: 'Post 2' }]) }, [{ includes: 'Post 2' }])
}) })
it('extracts the App Shell from a fully-static prerender response', async () => {
// The /static-posts/[id] route is fully static: all params are known via
// `generateStaticParams` and the page accesses no other dynamic data, so
// each URL is prerendered at build time. When the client prefetches one
// URL, it receives the full prerender; the client extracts the shell
// prefix (using the byte offset in the response) and caches it at the
// Fallback vary path, so that navigations to OTHER URLs in the same
// route still get an instant shell before the per-URL content arrives.
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page)
// Reveal the LinkAccordion for /static-posts/1. Two prefetch responses
// fire: one for the per-segment static prefetch of /static-posts/1
// (which contains the resolved page content + the shell above the
// params boundary), and one for the runtime shell prefetch (which the
// server may return either as a truncated shell or as the full
// prerender that the client extracts a shell prefix from). Both
// responses contain the "App shell for static posts" substring.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/static-posts/1"]')
.click()
}, [
{ includes: 'App shell for static posts' },
{ includes: 'App shell for static posts' },
])
// Click the link to /static-posts/124 — a different param than what
// was prefetched, rendered with prefetch={false}. The cached App
// Shell should render immediately, before the per-URL navigation
// response arrives.
await act(async () => {
await browser.elementByCss('a[href="/static-posts/124"]').click()
// While the navigation response is blocked (we're still in the
// `act` block), the cached App Shell should already be visible.
expect(await browser.elementById('static-shell').text()).toEqual(
'App shell for static posts'
)
})
// After the outer act unblocks the navigation, the per-URL content
// streams in.
expect(await browser.elementById('static-content').text()).toEqual(
'Static post 124'
)
})
}) })
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