Unverified Commit 1eaa37ec authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Prefetch App Shells on the client (#93999)

Gated behind `experimental.appShells`. Clicking a link to a route the
user has never specifically prefetched now renders the route's App Shell
instantly; the per-link concrete request continues in the background and
streams in the param-specific content.

### Motivation

Today, prefetching a parameterized route like `/chat/[id]` requires a
concrete `id`. The framework caches a separate prefetch entry per link,
so the cost of prefetching scales with the number of visible links — not
with the number of routes. On a page with high link cardinality (a feed,
a search-results page, a chat list) it is impractical to prefetch every
concrete URL up front. If a per-link prefetch for `/chat/123` is still
in flight when the user clicks the link, the navigation blocks until
that prefetch completes; there's no cached generic shell to fall back
to. The cost of a prefetch miss is a full blocking navigation.

The property we want: once a user has visited a Next.js app, every
subsequent navigation should transition to _something_ instantly — at
minimum an App Shell — regardless of whether per-link prefetches for the
concrete destination have completed. This matters most under adverse
conditions (slow networks, offline, high-cardinality routes), but the
guarantee is unconditional.

App Shells make that property hold. A shell is a per-_route_ resource,
not a per-link one — the number of shells in flight at any time scales
with filesystem routes, which is bounded and small. Aggressive App Shell
prefetching is affordable in a way that aggressive per-link runtime
prefetching is not.

### Mechanism

A new `Shell` phase sits in the prefetch scheduler between the existing
`RouteTree` and `Speculative` (formerly `Segments`) phases. Shell-phase
tasks issue an App Shell request and write the response under a
param-independent vary path. Concurrent shell tasks for sibling links to
the same route dedupe at this keypath, so the cache holds at most one
shell entry per route.

The headline property: if N links on a page resolve to the same route
under different params, they share _one_ App Shell request collectively.
Once it lands, every one of those navigations can render an instant
shell, regardless of whether the param-specific concrete prefetch has
completed.

The Speculative phase is mostly unchanged — it still issues the per-link
concrete prefetches that fill in param-specific content over time.
Routes that are fully static (no runtime data anywhere in their tree)
skip the Shell phase entirely, since their existing static prefetches
are already shell-like in shape.

### Navigation-time cache lookup

A small change in how the cache is read at navigation time is what makes
the instant-shell guarantee actually hold. The cache normally returns
the _most-specific_ matching entry — the right semantics for prefetch
dedup, but the wrong semantics for navigation. If a fulfilled shell
entry coexists with an in-flight Pending entry for a more-specific
keypath that the navigation also matches, the most-specific entry is the
empty Pending one, and the navigation would block on it instead of
rendering the shell.

Navigation now does a two-pass lookup: first prefer Fulfilled entries
anywhere along the vary path (so a less-specific shell beats a
more-specific Pending), then fall back to the regular behavior if
nothing fulfilled is found. Prefetch reads keep the original semantics,
since they need to see in-flight entries to dedupe.

### Scope

The shape of the prefetch request and the response interpretation differ
between static (`PPR`) and runtime (`PPRRuntime`) prefetches. Only the
runtime path is covered here. The static path uses a different strategy
— rewinding a single response into a shell prefix and a concrete suffix,
rather than issuing a separate shell-only request — and will be added in
a future PR alongside the server-side byte-offset machinery it depends
on.
<!-- NEXT_JS_LLM_PR -->
parent 242ae681
...@@ -101,7 +101,7 @@ export type RequestHeaders = { ...@@ -101,7 +101,7 @@ export type RequestHeaders = {
[RSC_HEADER]?: '1' [RSC_HEADER]?: '1'
[NEXT_ROUTER_STATE_TREE_HEADER]?: string [NEXT_ROUTER_STATE_TREE_HEADER]?: string
[NEXT_URL]?: string [NEXT_URL]?: string
[NEXT_ROUTER_PREFETCH_HEADER]?: '1' | '2' [NEXT_ROUTER_PREFETCH_HEADER]?: '1' | '2' | '3'
[NEXT_ROUTER_SEGMENT_PREFETCH_HEADER]?: string [NEXT_ROUTER_SEGMENT_PREFETCH_HEADER]?: string
'x-deployment-id'?: string 'x-deployment-id'?: string
[NEXT_HMR_REFRESH_HEADER]?: '1' [NEXT_HMR_REFRESH_HEADER]?: '1'
......
...@@ -30,7 +30,7 @@ import { ...@@ -30,7 +30,7 @@ import {
type RefreshState, type RefreshState,
type FulfilledRouteCacheEntry, type FulfilledRouteCacheEntry,
convertReusedFlightRouterStateToRouteTree, convertReusedFlightRouterStateToRouteTree,
readSegmentCacheEntry, readSegmentCacheEntryForNavigation,
waitForSegmentCacheEntry, waitForSegmentCacheEntry,
markRouteEntryAsDynamicRewrite, markRouteEntryAsDynamicRewrite,
invalidateRouteCacheEntries, invalidateRouteCacheEntries,
...@@ -1072,7 +1072,7 @@ function createCacheNodeForSegment( ...@@ -1072,7 +1072,7 @@ function createCacheNodeForSegment(
let cachedRsc: React.ReactNode | null = null let cachedRsc: React.ReactNode | null = null
let isCachedRscPartial: boolean = true let isCachedRscPartial: boolean = true
const segmentEntry = readSegmentCacheEntry(now, tree.varyPath) const segmentEntry = readSegmentCacheEntryForNavigation(now, tree.varyPath)
if (segmentEntry !== null) { if (segmentEntry !== null) {
switch (segmentEntry.status) { switch (segmentEntry.status) {
case EntryStatus.Fulfilled: { case EntryStatus.Fulfilled: {
...@@ -1175,7 +1175,10 @@ function createCacheNodeForSegment( ...@@ -1175,7 +1175,10 @@ function createCacheNodeForSegment(
let cachedHead: HeadData | null = null let cachedHead: HeadData | null = null
let isCachedHeadPartial: boolean = true let isCachedHeadPartial: boolean = true
if (metadataVaryPath !== null) { if (metadataVaryPath !== null) {
const metadataEntry = readSegmentCacheEntry(now, metadataVaryPath) const metadataEntry = readSegmentCacheEntryForNavigation(
now,
metadataVaryPath
)
if (metadataEntry !== null) { if (metadataEntry !== null) {
switch (metadataEntry.status) { switch (metadataEntry.status) {
case EntryStatus.Fulfilled: { case EntryStatus.Fulfilled: {
......
...@@ -23,6 +23,7 @@ export function computeDynamicStaleAt( ...@@ -23,6 +23,7 @@ export function computeDynamicStaleAt(
import { import {
setInCacheMap, setInCacheMap,
getFromCacheMap, getFromCacheMap,
EntryStatus,
type UnknownMapEntry, type UnknownMapEntry,
type CacheMap, type CacheMap,
createCacheMap, createCacheMap,
...@@ -49,6 +50,10 @@ export type BFCacheEntry = { ...@@ -49,6 +50,10 @@ export type BFCacheEntry = {
navigatedAt: number navigatedAt: number
staleAt: number staleAt: number
version: number version: number
// A BFCacheEntry always represents a completed navigation, so the status is
// always Fulfilled. The field exists so that BFCacheEntry conforms to the
// MapValue protocol.
status: EntryStatus.Fulfilled
} }
const bfcacheMap: CacheMap<BFCacheEntry> = createCacheMap() const bfcacheMap: CacheMap<BFCacheEntry> = createCacheMap()
...@@ -102,6 +107,7 @@ export function writeToBFCache( ...@@ -102,6 +107,7 @@ export function writeToBFCache(
// is exported by a page. // is exported by a page.
staleAt: dynamicStaleAt, staleAt: dynamicStaleAt,
version: currentBfCacheVersion, version: currentBfCacheVersion,
status: EntryStatus.Fulfilled,
} }
const isRevalidation = false const isRevalidation = false
setInCacheMap(bfcacheMap, varyPath, entry, isRevalidation) setInCacheMap(bfcacheMap, varyPath, entry, isRevalidation)
...@@ -148,7 +154,8 @@ export function updateBFCacheEntryStaleAt( ...@@ -148,7 +154,8 @@ export function updateBFCacheEntryStaleAt(
currentBfCacheVersion, currentBfCacheVersion,
bfcacheMap, bfcacheMap,
varyPath, varyPath,
isRevalidation isRevalidation,
false
) )
if (entry !== null) { if (entry !== null) {
entry.staleAt = newStaleAt entry.staleAt = newStaleAt
...@@ -170,7 +177,8 @@ export function readFromBFCache( ...@@ -170,7 +177,8 @@ export function readFromBFCache(
currentBfCacheVersion, currentBfCacheVersion,
bfcacheMap, bfcacheMap,
varyPath, varyPath,
isRevalidation isRevalidation,
false
) )
} }
...@@ -187,6 +195,7 @@ export function readFromBFCacheDuringRegularNavigation( ...@@ -187,6 +195,7 @@ export function readFromBFCacheDuringRegularNavigation(
currentBfCacheVersion, currentBfCacheVersion,
bfcacheMap, bfcacheMap,
varyPath, varyPath,
isRevalidation isRevalidation,
false
) )
} }
...@@ -65,15 +65,31 @@ import { lruPut, updateLruSize, deleteFromLru } from './lru' ...@@ -65,15 +65,31 @@ import { lruPut, updateLruSize, deleteFromLru } from './lru'
* should prefer to put it in cache.ts. * should prefer to put it in cache.ts.
*/ */
// The protocol that values must implement. In practice, the only two types that /**
// we ever actually deal with in this module are RouteCacheEntry and * Tracks the status of a cache entry as it progresses from no data (Empty),
// SegmentCacheEntry; this is just to keep track of the coupling so we don't * waiting for server data (Pending), and finished (either Fulfilled or
// leak concerns between the modules unnecessarily. * Rejected depending on the response from the server.
*
* This is defined here, rather than in cache.ts, because cache-map.ts needs to
* inspect the status when performing a `onlyMatchFulfilled` lookup.
*/
export const enum EntryStatus {
Empty = 0,
Pending = 1,
Fulfilled = 2,
Rejected = 3,
}
// The protocol that values must implement. In practice, the only types that
// we ever actually deal with in this module are RouteCacheEntry,
// SegmentCacheEntry, and BFCacheEntry; this is just to keep track of the
// coupling so we don't leak concerns between the modules unnecessarily.
export interface MapValue { export interface MapValue {
ref: UnknownMapEntry | null ref: UnknownMapEntry | null
size: number size: number
staleAt: number staleAt: number
version: number version: number
status: EntryStatus
} }
/** /**
...@@ -215,7 +231,14 @@ export function getFromCacheMap<V extends MapValue>( ...@@ -215,7 +231,14 @@ export function getFromCacheMap<V extends MapValue>(
currentCacheVersion: number, currentCacheVersion: number,
rootEntry: CacheMap<V>, rootEntry: CacheMap<V>,
keys: VaryPath, keys: VaryPath,
isRevalidation: boolean isRevalidation: boolean,
// When true, terminal entries whose status is not Fulfilled are skipped, so
// the lookup falls through to a less-specific Fallback entry. Use this
// during a navigation to prefer a Fulfilled shell entry over a more-specific
// Pending entry that may still be in-flight. Callers that want to also
// accept non-Fulfilled entries should perform a second lookup with this set
// to false.
onlyMatchFulfilled: boolean
): V | null { ): V | null {
const entry = getEntryWithFallbackImpl( const entry = getEntryWithFallbackImpl(
now, now,
...@@ -223,7 +246,8 @@ export function getFromCacheMap<V extends MapValue>( ...@@ -223,7 +246,8 @@ export function getFromCacheMap<V extends MapValue>(
rootEntry, rootEntry,
keys, keys,
isRevalidation, isRevalidation,
0 0,
onlyMatchFulfilled
) )
if (entry === null || entry.value === null) { if (entry === null || entry.value === null) {
return null return null
...@@ -244,7 +268,8 @@ export function isValueExpired( ...@@ -244,7 +268,8 @@ export function isValueExpired(
function lazilyEvictIfNeeded<V extends MapValue>( function lazilyEvictIfNeeded<V extends MapValue>(
now: number, now: number,
currentCacheVersion: number, currentCacheVersion: number,
entry: MapEntry<V> entry: MapEntry<V>,
onlyMatchFulfilled: boolean
) { ) {
// We have a matching entry, but before we can return it, we need to check if // We have a matching entry, but before we can return it, we need to check if
// it's still fresh. Otherwise it should be treated the same as a cache miss. // it's still fresh. Otherwise it should be treated the same as a cache miss.
...@@ -262,6 +287,12 @@ function lazilyEvictIfNeeded<V extends MapValue>( ...@@ -262,6 +287,12 @@ function lazilyEvictIfNeeded<V extends MapValue>(
return null return null
} }
if (onlyMatchFulfilled && value.status !== EntryStatus.Fulfilled) {
// The entry is fresh but is not Fulfilled. Treat as a non-match so the
// recursion can continue and try a Fallback entry.
return null
}
// The matched entry has not expired. Return it. // The matched entry has not expired. Return it.
return entry return entry
} }
...@@ -272,7 +303,8 @@ function getEntryWithFallbackImpl<V extends MapValue>( ...@@ -272,7 +303,8 @@ function getEntryWithFallbackImpl<V extends MapValue>(
entry: MapEntry<V>, entry: MapEntry<V>,
keys: VaryPath | null, keys: VaryPath | null,
isRevalidation: boolean, isRevalidation: boolean,
previousKey: unknown | null previousKey: unknown | null,
onlyMatchFulfilled: boolean
): MapEntry<V> | null { ): MapEntry<V> | null {
// This is similar to getExactEntry, but if an exact match is not found for // This is similar to getExactEntry, but if an exact match is not found for
// a key, it will return the fallback entry instead. This is recursive at // a key, it will return the fallback entry instead. This is recursive at
...@@ -280,6 +312,10 @@ function getEntryWithFallbackImpl<V extends MapValue>( ...@@ -280,6 +312,10 @@ function getEntryWithFallbackImpl<V extends MapValue>(
// valid match for [a, b, c, d]. // valid match for [a, b, c, d].
// //
// It will return the most specific match available. // It will return the most specific match available.
//
// When `onlyMatchFulfilled` is true, terminal entries that aren't Fulfilled
// are treated as non-matches, so the recursion will continue searching for
// a Fallback match. See getFromCacheMap for the rationale.
let key let key
let remainingKeys: VaryPath | null let remainingKeys: VaryPath | null
if (keys !== null) { if (keys !== null) {
...@@ -292,14 +328,12 @@ function getEntryWithFallbackImpl<V extends MapValue>( ...@@ -292,14 +328,12 @@ function getEntryWithFallbackImpl<V extends MapValue>(
remainingKeys = null remainingKeys = null
} else { } else {
// There are no more keys. This is the terminal entry. // There are no more keys. This is the terminal entry.
return lazilyEvictIfNeeded(
// TODO: When performing a lookup during a navigation, as opposed to a now,
// prefetch, we may want to skip entries that are Pending if there's also currentCacheVersion,
// a Fulfilled fallback entry. Tricky to say, though, since if it's entry,
// already pending, it's likely to stream in soon. Maybe we could do this onlyMatchFulfilled
// just on slow connections and offline mode. )
return lazilyEvictIfNeeded(now, currentCacheVersion, entry)
} }
const map = entry.map const map = entry.map
if (map !== null) { if (map !== null) {
...@@ -312,7 +346,8 @@ function getEntryWithFallbackImpl<V extends MapValue>( ...@@ -312,7 +346,8 @@ function getEntryWithFallbackImpl<V extends MapValue>(
existingEntry, existingEntry,
remainingKeys, remainingKeys,
isRevalidation, isRevalidation,
key key,
onlyMatchFulfilled
) )
if (result !== null) { if (result !== null) {
return result return result
...@@ -328,7 +363,8 @@ function getEntryWithFallbackImpl<V extends MapValue>( ...@@ -328,7 +363,8 @@ function getEntryWithFallbackImpl<V extends MapValue>(
fallbackEntry, fallbackEntry,
remainingKeys, remainingKeys,
isRevalidation, isRevalidation,
key key,
onlyMatchFulfilled
) )
} }
} }
......
...@@ -78,9 +78,11 @@ import { ...@@ -78,9 +78,11 @@ import {
setSizeInCacheMap, setSizeInCacheMap,
deleteFromCacheMap, deleteFromCacheMap,
isValueExpired, isValueExpired,
EntryStatus,
type CacheMap, type CacheMap,
type UnknownMapEntry, type UnknownMapEntry,
} from './cache-map' } from './cache-map'
export { EntryStatus } from './cache-map'
import { import {
appendSegmentRequestKeyPart, appendSegmentRequestKeyPart,
convertSegmentPathToStaticExportFilename, convertSegmentPathToStaticExportFilename,
...@@ -183,18 +185,6 @@ type RouteCacheEntryShared = { ...@@ -183,18 +185,6 @@ type RouteCacheEntryShared = {
version: number version: number
} }
/**
* Tracks the status of a cache entry as it progresses from no data (Empty),
* waiting for server data (Pending), and finished (either Fulfilled or
* Rejected depending on the response from the server.
*/
export const enum EntryStatus {
Empty = 0,
Pending = 1,
Fulfilled = 2,
Rejected = 3,
}
export type PendingRouteCacheEntry = RouteCacheEntryShared & { export type PendingRouteCacheEntry = RouteCacheEntryShared & {
status: EntryStatus.Empty | EntryStatus.Pending status: EntryStatus.Empty | EntryStatus.Pending
blockedTasks: Set<PrefetchTask> | null blockedTasks: Set<PrefetchTask> | null
...@@ -458,7 +448,8 @@ export function readRouteCacheEntry( ...@@ -458,7 +448,8 @@ export function readRouteCacheEntry(
getCurrentRouteCacheVersion(), getCurrentRouteCacheVersion(),
routeCacheMap, routeCacheMap,
varyPath, varyPath,
isRevalidation isRevalidation,
false
) )
if (existingEntry !== null) { if (existingEntry !== null) {
return existingEntry return existingEntry
...@@ -483,7 +474,48 @@ export function readSegmentCacheEntry( ...@@ -483,7 +474,48 @@ export function readSegmentCacheEntry(
getCurrentSegmentCacheVersion(), getCurrentSegmentCacheVersion(),
segmentCacheMap, segmentCacheMap,
varyPath, varyPath,
isRevalidation isRevalidation,
false
)
}
/**
* Like `readSegmentCacheEntry`, but prefers a Fulfilled entry over a
* more-specific Pending or Rejected entry. Use this during a navigation, where
* a less-specific shell entry (e.g. params -> Fallback) should be rendered
* immediately rather than blocking on a more-specific Pending entry that may
* still be in-flight.
*
* Performs up to two lookups:
* 1. An `onlyMatchFulfilled` lookup that walks past Pending/Rejected entries
* at more-specific keypaths to find a Fulfilled fallback (e.g. a cached
* shell).
* 2. If no Fulfilled entry is found, a regular lookup that returns the most
* specific match regardless of status.
*/
export function readSegmentCacheEntryForNavigation(
now: number,
varyPath: SegmentVaryPath
): SegmentCacheEntry | null {
const isRevalidation = false
const fulfilled = getFromCacheMap(
now,
getCurrentSegmentCacheVersion(),
segmentCacheMap,
varyPath,
isRevalidation,
true
)
if (fulfilled !== null) {
return fulfilled
}
return getFromCacheMap(
now,
getCurrentSegmentCacheVersion(),
segmentCacheMap,
varyPath,
isRevalidation,
false
) )
} }
...@@ -497,7 +529,8 @@ function readRevalidatingSegmentCacheEntry( ...@@ -497,7 +529,8 @@ function readRevalidatingSegmentCacheEntry(
getCurrentSegmentCacheVersion(), getCurrentSegmentCacheVersion(),
segmentCacheMap, segmentCacheMap,
varyPath, varyPath,
isRevalidation isRevalidation,
false
) )
} }
...@@ -2092,6 +2125,7 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2092,6 +2125,7 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
fetchStrategy: fetchStrategy:
| FetchStrategy.LoadingBoundary | FetchStrategy.LoadingBoundary
| FetchStrategy.PPRRuntime | FetchStrategy.PPRRuntime
| FetchStrategy.RuntimeShell
| FetchStrategy.Full, | FetchStrategy.Full,
dynamicRequestTree: FlightRouterState, dynamicRequestTree: FlightRouterState,
spawnedEntries: Map<SegmentRequestKey, PendingSegmentCacheEntry> spawnedEntries: Map<SegmentRequestKey, PendingSegmentCacheEntry>
...@@ -2131,6 +2165,10 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2131,6 +2165,10 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
headers[NEXT_ROUTER_PREFETCH_HEADER] = '2' headers[NEXT_ROUTER_PREFETCH_HEADER] = '2'
break break
} }
case FetchStrategy.RuntimeShell: {
headers[NEXT_ROUTER_PREFETCH_HEADER] = '3'
break
}
case FetchStrategy.LoadingBoundary: { case FetchStrategy.LoadingBoundary: {
headers[NEXT_ROUTER_PREFETCH_HEADER] = '1' headers[NEXT_ROUTER_PREFETCH_HEADER] = '1'
break break
...@@ -2221,11 +2259,15 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest( ...@@ -2221,11 +2259,15 @@ export async function fetchSegmentPrefetchesUsingDynamicRequest(
const now = Date.now() const now = Date.now()
const staleAt = await getStaleAt(now, serverData.s, response) const staleAt = await getStaleAt(now, serverData.s, response)
// PPRRuntime prefetches are partial when the server marks the response // PPRRuntime and RuntimeShell prefetches are partial when the server
// as '~' (Partial). Full/LoadingBoundary prefetches are always complete. // marks the response as '~' (Partial). RuntimeShell additionally omits
// every dynamic suspense boundary below the App Shell, so its segments
// are always partial regardless of what the server marker says.
// Full/LoadingBoundary prefetches are always complete.
const isResponsePartial = const isResponsePartial =
fetchStrategy === FetchStrategy.PPRRuntime && fetchStrategy === FetchStrategy.RuntimeShell ||
(cacheData?.isResponsePartial ?? false) (fetchStrategy === FetchStrategy.PPRRuntime &&
(cacheData?.isResponsePartial ?? false))
// Aside from writing the data into the cache, this function also returns // Aside from writing the data into the cache, this function also returns
// the entries that were fulfilled, so we can streamingly update their sizes // the entries that were fulfilled, so we can streamingly update their sizes
...@@ -2411,6 +2453,7 @@ export function writeDynamicRenderResponseIntoCache( ...@@ -2411,6 +2453,7 @@ export function writeDynamicRenderResponseIntoCache(
| FetchStrategy.LoadingBoundary | FetchStrategy.LoadingBoundary
| FetchStrategy.PPR | FetchStrategy.PPR
| FetchStrategy.PPRRuntime | FetchStrategy.PPRRuntime
| FetchStrategy.RuntimeShell
| FetchStrategy.Full, | FetchStrategy.Full,
flightDatas: NormalizedFlightData[], flightDatas: NormalizedFlightData[],
buildId: string | undefined, buildId: string | undefined,
...@@ -2523,6 +2566,7 @@ function writeSeedDataIntoCache( ...@@ -2523,6 +2566,7 @@ function writeSeedDataIntoCache(
| FetchStrategy.LoadingBoundary | FetchStrategy.LoadingBoundary
| FetchStrategy.PPR | FetchStrategy.PPR
| FetchStrategy.PPRRuntime | FetchStrategy.PPRRuntime
| FetchStrategy.RuntimeShell
| FetchStrategy.Full, | FetchStrategy.Full,
tree: RouteTree, tree: RouteTree,
staleAt: number, staleAt: number,
...@@ -2577,12 +2621,15 @@ function writeSeedDataIntoCache( ...@@ -2577,12 +2621,15 @@ function writeSeedDataIntoCache(
} }
} }
const EMPTY_VARY_PARAMS: Set<string> = new Set()
function fulfillEntrySpawnedByRuntimePrefetch( function fulfillEntrySpawnedByRuntimePrefetch(
now: number, now: number,
fetchStrategy: fetchStrategy:
| FetchStrategy.LoadingBoundary | FetchStrategy.LoadingBoundary
| FetchStrategy.PPR | FetchStrategy.PPR
| FetchStrategy.PPRRuntime | FetchStrategy.PPRRuntime
| FetchStrategy.RuntimeShell
| FetchStrategy.Full, | FetchStrategy.Full,
rsc: React.ReactNode, rsc: React.ReactNode,
isPartial: boolean, isPartial: boolean,
...@@ -2605,11 +2652,28 @@ function fulfillEntrySpawnedByRuntimePrefetch( ...@@ -2605,11 +2652,28 @@ function fulfillEntrySpawnedByRuntimePrefetch(
// untrustworthy set could replace concrete params with Fallback and let // untrustworthy set could replace concrete params with Fallback and let
// unrelated URLs read each other's content from the cache. // unrelated URLs read each other's content from the cache.
// //
// Override to an empty set for RuntimeShell prefetches. The shell is
// param-free by definition — that's the whole point of the strategy — so
// every param node in the vary path should be Fallback regardless of what
// the server reports.
// NOTE: It would be better not to override this value on the client. We
// should be able to trust the server. However, there's one known case where
// the server can over-report search params: the tracking proxy in
// `createVaryingSearchParams` registers `?` on any string property access,
// and `Promise.resolve(proxy)` reads `.then` during thenability detection,
// so just wrapping the proxy in a promise is enough to leak `?` into the
// accumulator. We also don't want to special case "then" access because it's
// perfectly valid to have a search param named "then". The plan to address
// this is to track each search param individually, rather than the entire
// query string as a whole.
//
// When non-null, this is the param set to re-key by; when null, the entry // When non-null, this is the param set to re-key by; when null, the entry
// stays keyed by the request's concrete vary path. // stays keyed by the request's concrete vary path.
const fulfilledVaryParams = const fulfilledVaryParams =
process.env.__NEXT_VARY_PARAMS && fetchStrategy !== FetchStrategy.Full process.env.__NEXT_VARY_PARAMS && fetchStrategy !== FetchStrategy.Full
? segmentVaryParams ? fetchStrategy === FetchStrategy.RuntimeShell
? EMPTY_VARY_PARAMS
: segmentVaryParams
: null : null
// We should only write into cache entries that are owned by us. Or create // We should only write into cache entries that are owned by us. Or create
......
...@@ -36,9 +36,10 @@ export const enum FetchStrategy { ...@@ -36,9 +36,10 @@ export const enum FetchStrategy {
// and determine if one segment is "more specific" than another // and determine if one segment is "more specific" than another
// (i.e. if it's likely that it contains more data) // (i.e. if it's likely that it contains more data)
LoadingBoundary = 0, LoadingBoundary = 0,
PPR = 1, RuntimeShell = 1,
PPRRuntime = 2, PPR = 2,
Full = 3, PPRRuntime = 3,
Full = 4,
} }
/** /**
......
...@@ -269,6 +269,13 @@ export function getSegmentVaryPathForRequest( ...@@ -269,6 +269,13 @@ export function getSegmentVaryPathForRequest(
// params that can be treated as Fallback. (Or perhaps the inverse.) // params that can be treated as Fallback. (Or perhaps the inverse.)
const originalVaryPath = tree.varyPath const originalVaryPath = tree.varyPath
if (fetchStrategy === FetchStrategy.RuntimeShell) {
// The Shell phase issues a runtime render with params omitted. The
// resulting entry is reusable across all concrete param values, so we
// key it at the shell vary path (every param substituted with Fallback).
return getShellSegmentVaryPath(originalVaryPath)
}
// Only page segments (and the special "metadata" segment, which is treated // Only page segments (and the special "metadata" segment, which is treated
// like a page segment for the purposes of caching) may contain search // like a page segment for the purposes of caching) may contain search
// params. There's no reason to include them in the vary path otherwise. // params. There's no reason to include them in the vary path otherwise.
...@@ -362,3 +369,28 @@ export function getFulfilledSegmentVaryPath( ...@@ -362,3 +369,28 @@ export function getFulfilledSegmentVaryPath(
} }
return clone as SegmentVaryPath return clone as SegmentVaryPath
} }
function getShellSegmentVaryPath(original: VaryPath): SegmentVaryPath {
// Re-keys a segment's vary path to identify the "App Shell" entry for this
// segment position — a reusable, param-free loading state that can be served
// for any concrete navigation to this segment. Every param node (path
// params, search params) is replaced with Fallback; only structural nodes
// (request keys, etc.) keep their concrete value.
//
// NOTE: For now, we treat root params the same as non-root params and
// forbid them from the shell. Root params change less frequently than
// other params, though, so caching the shell across root param values is
// a potential future optimization. One way to model that would be to
// evict the entire client cache whenever a root param change is detected.
// Then we would no longer need to include them in the cache key, which
// would be consistent with how we treat session-based data like cookies.
const clone: VaryPath = {
id: original.id,
value: original.id === null ? original.value : Fallback,
parent:
original.parent === null
? null
: getShellSegmentVaryPath(original.parent),
}
return clone as SegmentVaryPath
}
import { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html>
<body>{children}</body>
</html>
)
}
import Link from 'next/link'
import { LinkAccordion } from '../components/link-accordion'
export default function Page() {
return (
<main>
<h1>Home</h1>
<h2>Dynamic posts</h2>
<p>
These posts read request-time data (cookies). Their App Shell is the
part of the page that doesn&apos;t depend on the URL params, so it can
be cached once and reused for any post.
</p>
<ul>
<li>
<LinkAccordion href="/posts/1">Post 1</LinkAccordion>
</li>
<li>
<LinkAccordion href="/posts/2">Post 2</LinkAccordion>
</li>
<li>
<LinkAccordion href="/posts/3">Post 3</LinkAccordion>
</li>
<li>
<Link href="/posts/124" prefetch={false}>
Unprefetched post
</Link>
</li>
<li>
<Link href="/posts/125?foo=bar" prefetch={false}>
Unprefetched post with search params
</Link>
</li>
</ul>
</main>
)
}
import { Suspense } from 'react'
import { cookies } from 'next/headers'
import { connection } from 'next/server'
type Params = { id: string }
export const unstable_prefetch = 'force-runtime'
export default function Page({ params }: { params: Promise<Params> }) {
return (
<main>
{/* Cookies are part of the request context, so they're available
when the App Shell is prerendered. The result is included in
the cached shell. */}
<Suspense fallback={<p id="cookie-loading">Loading cookie...</p>}>
<CookieDependent />
</Suspense>
{/* The fallback is the App Shell — the part of the page that
doesn't depend on params. */}
<Suspense fallback={<p id="shell">App shell for posts</p>}>
<ParamsDependent params={params} />
</Suspense>
</main>
)
}
async function CookieDependent() {
const cookieStore = await cookies()
const value = cookieStore.get('testCookie')?.value ?? 'none'
return <p id="cookie-value">{`Cookie: ${value}`}</p>
}
async function ParamsDependent({ params }: { params: Promise<Params> }) {
const { id } = await params
// The fallback shows while the dynamic content is loading, after the
// params have resolved.
return (
<>
<p id="param-value">{`Post ${id}`}</p>
<Suspense
fallback={<p id="dynamic-loading">Loading dynamic content...</p>}
>
<Dynamic id={id} />
</Suspense>
</>
)
}
async function Dynamic({ id }: { id: string }) {
await connection()
return <p id="dynamic-content">{`Post body for ${id}`}</p>
}
'use client'
import Link, { type LinkProps } from 'next/link'
import { useState } from 'react'
export function LinkAccordion({
href,
children,
prefetch,
}: {
href: string
children: React.ReactNode
prefetch?: LinkProps['prefetch']
}) {
const [isVisible, setIsVisible] = useState(false)
return (
<>
<input
type="checkbox"
checked={isVisible}
onChange={() => setIsVisible(!isVisible)}
data-link-accordion={href}
/>
{isVisible ? (
<Link href={href} prefetch={prefetch}>
{children}
</Link>
) : (
<>{children} (link is hidden)</>
)}
</>
)
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
experimental: {
prefetchInlining: true,
optimisticRouting: true,
cachedNavigations: true,
appShells: true,
varyParams: true,
},
}
export default nextConfig
import { nextTestSetup } from 'e2e-utils'
import type * as Playwright from 'playwright'
import { createRouterAct } from 'router-act'
describe('App Shell prefetching', () => {
const { next, isNextDev } = nextTestSetup({
files: __dirname,
})
if (isNextDev) {
it('is skipped', () => {})
return
}
it('reuses the app shell across different param values so navigation to an unprefetched route is instant', async () => {
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page)
// Reveal the LinkAccordion for /posts/1. This caches the App Shell
// for the route — the param-independent content of the page that's
// reusable for any /posts/[id].
//
// The "App shell for posts" substring appears in two responses: one
// for the App Shell itself and one for the per-link prefetch of
// /posts/1 (which, for a dynamic page, also includes the shell
// content above its inner Suspense fallback).
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/posts/1"]')
.click()
}, [
{ includes: 'App shell for posts' },
{ includes: 'App shell for posts' },
])
await act(async () => {
// Click the link to /posts/124. This link is rendered with
// prefetch={false}, so it was never prefetched. The cached App
// Shell should render immediately, before any navigation response
// arrives.
await browser.elementByCss('a[href="/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('shell').text()).toEqual(
'App shell for posts'
)
// Sesssion data (cookies) is not dependent on URL-data, so they are
// allowed to be accessed in the shell.
expect(await browser.elementById('cookie-value').text()).toEqual(
'Cookie: none'
)
})
// After the outer act unblocks the navigation, params resolve and the
// dynamic content streams in.
expect(await browser.elementById('param-value').text()).toEqual('Post 124')
expect(await browser.elementById('dynamic-content').text()).toEqual(
'Post body for 124'
)
})
it('reuses the app shell across different search param values', async () => {
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page)
// Reveal the LinkAccordion for /posts/1. This caches the App Shell.
// Because the App Shell does not depend on params or search params,
// it should be reusable across all combinations of either.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/posts/1"]')
.click()
}, [
{ includes: 'App shell for posts' },
{ includes: 'App shell for posts' },
])
// Navigate to /posts/125?foo=bar — a different param AND a different
// search-params value than what was prefetched. The cached App Shell
// should be reused since it doesn't vary on either.
await act(async () => {
await browser.elementByCss('a[href="/posts/125?foo=bar"]').click()
// While the navigation response is blocked, the cached App Shell
// should already be visible.
expect(await browser.elementById('shell').text()).toEqual(
'App shell for posts'
)
})
})
it('issues a concrete prefetch for a second link with a different param, even though the shell is already cached', async () => {
let page: Playwright.Page
const browser = await next.browser('/', {
beforePageLoad(p: Playwright.Page) {
page = p
},
})
const act = createRouterAct(page)
// Reveal the LinkAccordion for /posts/1. The "App shell for posts"
// substring appears in two responses: one for the App Shell itself
// and one for the per-link prefetch of /posts/1 (which, for a
// dynamic page, also includes the shell content above its inner
// Suspense fallback).
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/posts/1"]')
.click()
}, [
{ includes: 'App shell for posts' },
{ includes: 'App shell for posts' },
])
// Reveal the LinkAccordion for /posts/2. The App Shell is already
// cached and reused, but a per-link prefetch should still fire for
// /posts/2 so that its param-specific content lands in the cache.
// We assert on that param-specific content to confirm.
await act(async () => {
await browser
.elementByCss('input[data-link-accordion="/posts/2"]')
.click()
}, [{ includes: 'Post 2' }])
})
})
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