Unverified Commit e383590a authored by Hendrik Liebau's avatar Hendrik Liebau Committed by GitHub

Add a global opt-in for the runtime stage of Cached Navigations (#95064)

`cachedNavigations` is an under-the-hood optimization that caches
subsets of a route, seeded from actual navigations, so subsequent
navigations to the same or similar page are served instantly. It is on
by default with Cache Components. The static stage is automatic, while
the more expensive runtime stage (which spawns an additional prerender
and embeds its output in the response) is opted into per segment via
`export const prefetch = 'allow-runtime'`.

Gating the runtime stage on the `prefetch` config is awkward, because
Cached Navigations is about caching real navigations rather than
speculative prefetching, so the people who benefit most are exactly
those who turn prefetching down. To dogfood the runtime stage's CPU and
payload overhead across a whole app, this change widens the
`experimental.cachedNavigations` config from `boolean` to `boolean |
'allow-runtime'`. `true` keeps its current meaning, and
`'allow-runtime'` additionally treats every route as runtime-cached
regardless of its per-segment `prefetch` config.

The new value only affects the two production spawn gates in
`app-render.tsx` (the client-navigation Flight render and the initial
HTML render), where the runtime prerender is now spawned when either a
segment opted in or the global flag is set. Prefetch hints, instant
validation, and component-tree staging are intentionally left keyed off
the per-segment config. The widened value is preserved through the
render options (the build templates pass it through instead of coercing
it to a boolean), while the client-facing env var stays a plain boolean
since the runtime prerender is entirely server-driven.

The `cached-navigations` e2e fixture is split into a `default/` fixture
(the existing suite, re-pointed) and a new `global-runtime/` fixture
that sets `cachedNavigations: 'allow-runtime'`, with a test asserting
that a route with no `prefetch` export still has its request-derived
content runtime-cached on a second navigation.
parent 88ef2160
...@@ -904,9 +904,8 @@ export async function handler( ...@@ -904,9 +904,8 @@ export async function handler(
prefetchInlining: nextConfig.experimental.prefetchInlining ?? false, prefetchInlining: nextConfig.experimental.prefetchInlining ?? false,
authInterrupts: Boolean(nextConfig.experimental.authInterrupts), authInterrupts: Boolean(nextConfig.experimental.authInterrupts),
useCacheTimeout: nextConfig.experimental.useCacheTimeout, useCacheTimeout: nextConfig.experimental.useCacheTimeout,
cachedNavigations: Boolean( cachedNavigations:
nextConfig.experimental.cachedNavigations nextConfig.experimental.cachedNavigations ?? false,
),
appShells: nextConfig.experimental.appShells, appShells: nextConfig.experimental.appShells,
clientTraceMetadata: clientTraceMetadata:
nextConfig.experimental.clientTraceMetadata || ([] as any), nextConfig.experimental.clientTraceMetadata || ([] as any),
......
...@@ -174,7 +174,7 @@ async function requestHandler( ...@@ -174,7 +174,7 @@ async function requestHandler(
prefetchInlining: nextConfig.experimental.prefetchInlining ?? false, prefetchInlining: nextConfig.experimental.prefetchInlining ?? false,
authInterrupts: Boolean(nextConfig.experimental.authInterrupts), authInterrupts: Boolean(nextConfig.experimental.authInterrupts),
useCacheTimeout: nextConfig.experimental.useCacheTimeout, useCacheTimeout: nextConfig.experimental.useCacheTimeout,
cachedNavigations: Boolean(nextConfig.experimental.cachedNavigations), cachedNavigations: nextConfig.experimental.cachedNavigations ?? false,
appShells: nextConfig.experimental.appShells, appShells: nextConfig.experimental.appShells,
clientTraceMetadata: clientTraceMetadata:
nextConfig.experimental.clientTraceMetadata || ([] as any), nextConfig.experimental.clientTraceMetadata || ([] as any),
......
...@@ -978,18 +978,19 @@ async function generateStagedDynamicFlightRenderResultNode( ...@@ -978,18 +978,19 @@ async function generateStagedDynamicFlightRenderResultNode(
: null : null
const staticStageByteLengthDeferred = createPromiseWithResolvers<number>() const staticStageByteLengthDeferred = createPromiseWithResolvers<number>()
// Check if this route has opted into runtime prefetching via
// instant. If so, we piggyback on the dynamic render to fill caches
// and then spawn a final runtime prerender whose result stream is embedded in
// the RSC payload. This is gated on the explicit opt-in because it adds extra
// server processing, increases the response payload size, and the runtime
// prefetch output should have been validated first.
const hasRuntimePrefetch =
await anySegmentHasRuntimePrefetchEnabled(loaderTree)
let runtimePrefetchStream: ReadableStream<Uint8Array> | undefined let runtimePrefetchStream: ReadableStream<Uint8Array> | undefined
if (hasRuntimePrefetch) { // Check if this route should runtime-cache its navigation: either a segment
// opted in via `prefetch = 'allow-runtime'`, or the global
// `cachedNavigations: 'allow-runtime'` flag forces it for every route. If so,
// we piggyback on the dynamic render to fill caches and then spawn a final
// runtime prerender whose result stream is embedded in the RSC payload. This
// is gated because it adds extra server processing and increases the response
// payload size.
if (
experimental.cachedNavigations === 'allow-runtime' ||
(await anySegmentHasRuntimePrefetchEnabled(loaderTree))
) {
// Create a mutable cache that gets filled during the dynamic render. // Create a mutable cache that gets filled during the dynamic render.
const prerenderResumeDataCache = createPrerenderResumeDataCache() const prerenderResumeDataCache = createPrerenderResumeDataCache()
requestStore.resumeDataCache = prerenderResumeDataCache requestStore.resumeDataCache = prerenderResumeDataCache
...@@ -3523,16 +3524,18 @@ async function renderToStream( ...@@ -3523,16 +3524,18 @@ async function renderToStream(
const staticStageByteLengthDeferred = const staticStageByteLengthDeferred =
createPromiseWithResolvers<number>() createPromiseWithResolvers<number>()
// If the route has runtime prefetching enabled, spawn a runtime
// prerender after the resume render fills caches. The result is
// embedded in the initial RSC payload so the client can cache
// runtime-prefetchable content during hydration.
const hasRuntimePrefetch =
await anySegmentHasRuntimePrefetchEnabled(tree)
let runtimePrefetchStream: ReadableStream<Uint8Array> | undefined let runtimePrefetchStream: ReadableStream<Uint8Array> | undefined
if (hasRuntimePrefetch) { // If the route should runtime-cache its navigation, spawn a runtime
// prerender after the resume render fills caches. The result is
// embedded in the initial RSC payload so the client can cache
// runtime-prefetchable content during hydration. This is enabled either
// per segment via `prefetch = 'allow-runtime'`, or globally via the
// `cachedNavigations: 'allow-runtime'` flag.
if (
cachedNavigations === 'allow-runtime' ||
(await anySegmentHasRuntimePrefetchEnabled(tree))
) {
const prerenderResumeDataCache = createPrerenderResumeDataCache() const prerenderResumeDataCache = createPrerenderResumeDataCache()
requestStore.resumeDataCache = prerenderResumeDataCache requestStore.resumeDataCache = prerenderResumeDataCache
......
...@@ -165,7 +165,7 @@ export interface RenderOptsPartial { ...@@ -165,7 +165,7 @@ export interface RenderOptsPartial {
prefetchInlining: PrefetchInliningConfig prefetchInlining: PrefetchInliningConfig
authInterrupts: boolean authInterrupts: boolean
useCacheTimeout: number useCacheTimeout: number
cachedNavigations: boolean cachedNavigations: boolean | 'allow-runtime'
appShells: ExperimentalConfig['appShells'] appShells: ExperimentalConfig['appShells']
/** /**
......
...@@ -219,7 +219,9 @@ export const experimentalSchema = { ...@@ -219,7 +219,9 @@ export const experimentalSchema = {
craCompat: z.boolean().optional(), craCompat: z.boolean().optional(),
caseSensitiveRoutes: z.boolean().optional(), caseSensitiveRoutes: z.boolean().optional(),
clientParamParsingOrigins: z.array(z.string()).optional(), clientParamParsingOrigins: z.array(z.string()).optional(),
cachedNavigations: z.boolean().optional(), cachedNavigations: z
.union([z.boolean(), z.literal('allow-runtime')])
.optional(),
dynamicOnHover: z.boolean().optional(), dynamicOnHover: z.boolean().optional(),
useOffline: z.boolean().optional(), useOffline: z.boolean().optional(),
optimisticRouting: z.boolean().optional(), optimisticRouting: z.boolean().optional(),
......
...@@ -472,7 +472,15 @@ export interface ExperimentalConfig { ...@@ -472,7 +472,15 @@ export interface ExperimentalConfig {
* rewrites will get the rewrite headers. * rewrites will get the rewrite headers.
*/ */
clientParamParsingOrigins?: string[] clientParamParsingOrigins?: string[]
cachedNavigations?: boolean /**
* Caches subsets of a route, seeded from actual navigations, so subsequent
* navigations to the same or similar pages can be served instantly. Requires
* Cache Components. `true` caches the static stage only (the runtime stage is
* opted into per segment via `export const prefetch = 'allow-runtime'`).
* `'allow-runtime'` additionally treats every segment as runtime-cached,
* regardless of its per-segment `prefetch` config.
*/
cachedNavigations?: boolean | 'allow-runtime'
dynamicOnHover?: boolean dynamicOnHover?: boolean
useOffline?: boolean useOffline?: boolean
optimisticRouting?: boolean optimisticRouting?: boolean
......
...@@ -2210,7 +2210,10 @@ function enforceExperimentalFeatures( ...@@ -2210,7 +2210,10 @@ function enforceExperimentalFeatures(
config.cacheComponents = true config.cacheComponents = true
} }
// TODO: Remove this once cachedNavigations is the default. // TODO: Remove this once cachedNavigations is the default. Note:
// cachedNavigations may be the string 'allow-runtime'. These guards treat it
// as truthy, so an explicit 'allow-runtime' is respected here and in the
// cacheComponents-tied default below rather than being downgraded to `true`.
if ( if (
process.env.__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS === 'true' && process.env.__NEXT_EXPERIMENTAL_CACHED_NAVIGATIONS === 'true' &&
// We do respect an explicit value in the user config. // We do respect an explicit value in the user config.
......
import path from 'path'
import { nextTestSetup } from 'e2e-utils'
import type * as Playwright from 'playwright'
import { createRouterAct } from 'router-act'
// The `global-runtime` fixture sets `experimental.cachedNavigations:
// 'allow-runtime'`, which makes every route runtime-cache its navigations
// regardless of whether a segment opted in via `prefetch = 'allow-runtime'`.
describe('cached navigations - global allow-runtime', () => {
const { next, isNextDev } = nextTestSetup({
files: path.join(__dirname, 'global-runtime'),
})
if (isNextDev) {
it('is skipped', () => {})
return
}
it('runtime-caches a route that has no per-segment prefetch config', async () => {
let page: Playwright.Page
const browser = await next.browser('/', {
async beforePageLoad(p: Playwright.Page) {
page = p
await page.clock.install()
},
})
const act = createRouterAct(page)
// First navigation to /runtime-prefetchable — a route that reads request
// data (searchParams, cookies, headers) but does NOT export
// `prefetch = 'allow-runtime'`. The link uses prefetch={false}, so this is
// a plain navigation with no prefetch.
await act(
async () => {
await browser.elementByCss('a[href="/runtime-prefetchable"]').click()
},
{ includes: 'Dynamic content' }
)
// Everything is visible after the full dynamic response.
expect(await browser.elementById('cached-content').text()).toContain(
'Cached content'
)
expect(
await browser.elementById('search-params-boundary').text()
).toContain('Search params:')
expect(await browser.elementById('cookies-boundary').text()).toContain(
'Cookie:'
)
expect(await browser.elementById('headers-boundary').text()).toContain(
'Header:'
)
expect(await browser.elementById('connection-boundary').text()).toContain(
'Dynamic content'
)
// Navigate back to home
await browser.back()
expect(await browser.elementByCss('h1').text()).toBe('Home')
// Second navigation — under the global flag, the request-derived content
// (searchParams, cookies, headers) was runtime-cached from the first
// navigation's embedded runtime prefetch stream and shows instantly, even
// with the dynamic request blocked. Without the global flag this route
// would only get static caching, since it never opts in via
// `prefetch = 'allow-runtime'`. Only the truly dynamic connection() content
// needs a server request.
await act(async () => {
await act(
async () => {
await browser.elementByCss('a[href="/runtime-prefetchable"]').click()
},
{
includes: 'Dynamic content',
block: true,
}
)
// Static cached content is visible.
expect(await browser.elementById('cached-content').text()).toContain(
'Cached content'
)
// Request-derived content is runtime-cached from the first navigation,
// despite no per-segment opt-in.
expect(
await browser.elementById('search-params-boundary').text()
).toContain('Search params:')
expect(await browser.elementById('cookies-boundary').text()).toContain(
'Cookie:'
)
expect(await browser.elementById('headers-boundary').text()).toContain(
'Header:'
)
// Only connection() shows a Suspense fallback — it's truly dynamic.
expect(await browser.elementById('connection-boundary').text()).toBe(
'Loading connection...'
)
})
// After unblocking, the dynamic content resolves too.
expect(await browser.elementById('connection-boundary').text()).toContain(
'Dynamic content'
)
})
})
import path from 'path'
import { nextTestSetup } from 'e2e-utils' import { nextTestSetup } from 'e2e-utils'
import { retry } from 'next-test-utils' import { retry } from 'next-test-utils'
import type * as Playwright from 'playwright' import type * as Playwright from 'playwright'
...@@ -5,7 +6,7 @@ import { createRouterAct } from 'router-act' ...@@ -5,7 +6,7 @@ import { createRouterAct } from 'router-act'
describe('cached navigations', () => { describe('cached navigations', () => {
const { next, isNextDev } = nextTestSetup({ const { next, isNextDev } = nextTestSetup({
files: __dirname, files: path.join(__dirname, 'default'),
}) })
if (isNextDev) { if (isNextDev) {
......
import Link from 'next/link'
import { ReactNode } from 'react'
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html>
<body>
<nav>
<Link href="/" prefetch={false}>
Home
</Link>
</nav>
{children}
</body>
</html>
)
}
import Link from 'next/link'
export default function Home() {
return (
<main>
<h1>Home</h1>
<h2>
Links with <code>prefetch=false</code>
</h2>
<ul>
<li>
<Link href="/runtime-prefetchable" prefetch={false}>
Go to runtime-prefetchable page
</Link>
</li>
</ul>
</main>
)
}
import { cookies, headers } from 'next/headers'
import { connection } from 'next/server'
import { Suspense } from 'react'
// Note: intentionally no `export const prefetch = 'allow-runtime'` and no
// `instant` config. This route gets runtime-cached purely because of the global
// `cachedNavigations: 'allow-runtime'` config in next.config.ts.
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
return (
<main>
<CachedContent />
<div id="search-params-boundary">
<Suspense fallback={<p>Loading search params...</p>}>
<SearchParamsContent searchParams={searchParams} />
</Suspense>
</div>
<div id="cookies-boundary">
<Suspense fallback={<p>Loading cookies...</p>}>
<CookiesContent />
</Suspense>
</div>
<div id="headers-boundary">
<Suspense fallback={<p>Loading headers...</p>}>
<HeadersContent />
</Suspense>
</div>
<div id="connection-boundary">
<Suspense fallback={<p>Loading connection...</p>}>
<ConnectionContent />
</Suspense>
</div>
</main>
)
}
async function CachedContent() {
'use cache'
return <p id="cached-content">Cached content</p>
}
async function SearchParamsContent({
searchParams,
}: {
searchParams: Promise<{ q?: string }>
}) {
const { q } = await searchParams
return <p>Search params: {q ?? 'none'}</p>
}
async function CookiesContent() {
const cookieStore = await cookies()
const value = cookieStore.get('testCookie')?.value ?? 'none'
return <p>Cookie: {value}</p>
}
async function HeadersContent() {
const headerStore = await headers()
const value = headerStore.get('x-test-header') ?? 'none'
return <p>Header: {value}</p>
}
async function ConnectionContent() {
await connection()
return <p>Dynamic content</p>
}
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
productionBrowserSourceMaps: true,
experimental: {
// Globally treat every route as runtime-cached, regardless of any
// per-segment `prefetch` config.
cachedNavigations: 'allow-runtime',
prefetchInlining: false,
exposeTestingApiInProductionBuild: true,
optimisticRouting: true,
useOffline: true,
varyParams: true,
},
}
export default nextConfig
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