Skip to content

Cached Navigations: Cache runtime stage data from navigation requests#90666

Merged
unstubbable merged 2 commits intocanaryfrom
hl/cached-navs-4
Mar 4, 2026
Merged

Cached Navigations: Cache runtime stage data from navigation requests#90666
unstubbable merged 2 commits intocanaryfrom
hl/cached-navs-4

Conversation

@unstubbable
Copy link
Contributor

@unstubbable unstubbable commented Feb 27, 2026

When navigating to a page with unstable_instant: { prefetch: 'runtime' } and no prior prefetch (e.g. prefetch={false} or clicking before prefetch completes), the server now embeds a runtime prefetch stream in the dynamic RSC navigation payload. On the client, this stream is decoded and written into the segment cache so that subsequent navigations to the same page can serve runtime-prefetchable content (cookies, headers, searchParams) instantly, without needing a separate prefetch request.

On the server, generateStagedDynamicFlightRenderResult detects routes with runtime prefetching enabled and attaches a CacheSignal and PrerenderResumeDataCache to the RequestStore. The dynamic render fills these caches as a side effect. Once cacheSignal.cacheReady() resolves, a final runtime prerender (the same 5-stage pipeline used for regular runtime prefetches) runs and its output is piped into a TransformStream whose readable side is included in the RSC payload as the p field on the NavigationFlightResponse. This avoids a separate prospective prerender because the dynamic render has already warmed the caches.

On the client, processRuntimePrefetchStream strips the isPartial byte, decodes the inner Flight stream, and the result is written into the segment cache via writeDynamicRenderResponseIntoCache with FetchStrategy.PPRRuntime. Both the navigateToUnknownRoute and fetchMissingDynamicData code paths handle the new stream.

This is gated on the explicit unstable_instant opt-in because it adds extra server processing (a full runtime prerender per navigation request) and increases payload size. It also requires that the runtime prefetch output has been validated first.

Known limitation: the runtime prefetch cache write currently evicts the static cache entry (which may have a longer stale time) because upsertSegmentEntry treats the fallback match as a replacement target. This means that after the runtime cache expires, the static cache is no longer available as a fallback. A follow-up may address this with a layered cache approach where entries with different fetch strategies and stale times coexist independently.

Extracting runtime data from initial HTML loads (the PPR resume path) is also deferred to a follow-up.

@nextjs-bot
Copy link
Collaborator

nextjs-bot commented Feb 27, 2026

Stats from current PR

🔴 1 regression

Metric Canary PR Change Trend
node_modules Size 475 MB 475 MB 🔴 +267 kB (+0%) ▁▁▁▁▁
📊 All Metrics
📖 Metrics Glossary

Dev Server Metrics:

  • Listen = TCP port starts accepting connections
  • First Request = HTTP server returns successful response
  • Cold = Fresh build (no cache)
  • Warm = With cached build artifacts

Build Metrics:

  • Fresh = Clean build (no .next directory)
  • Cached = With existing .next directory

Change Thresholds:

  • Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
  • Size: Changes < 1KB AND < 1% are insignificant
  • All other changes are flagged to catch regressions

⚡ Dev Server

Metric Canary PR Change Trend
Cold (Listen) 456ms 455ms ▂▁▁▁▁
Cold (Ready in log) 439ms 440ms ▂▁▁▁▁
Cold (First Request) 899ms 895ms ▂▃▃▃▃
Warm (Listen) 455ms 456ms ▂▁▁▁▁
Warm (Ready in log) 439ms 439ms ▂▁▁▁▁
Warm (First Request) 352ms 350ms ▁▂▁▁▁
📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric Canary PR Change Trend
Cold (Listen) 455ms 455ms ▁▁▁▁█
Cold (Ready in log) 437ms 436ms ▃▃▃▃█
Cold (First Request) 1.937s 1.953s ▁▁▁▁█
Warm (Listen) 456ms 456ms ▁▁▁▁█
Warm (Ready in log) 436ms 436ms ▃▃▃▃█
Warm (First Request) 1.940s 1.932s ▂▁▂▁█

⚡ Production Builds

Metric Canary PR Change Trend
Fresh Build 4.112s 4.079s ▃▁▁▁▁
Cached Build 4.089s 4.102s ▃▁▁▁▁
📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric Canary PR Change Trend
Fresh Build 13.851s 13.853s ▁▁▁▁█
Cached Build 13.942s 13.988s ▁▁▁▁█
node_modules Size 475 MB 475 MB 🔴 +267 kB (+0%) ▁▁▁▁▁
📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **401 kB** → **401 kB** ⚠️ +231 B

80 files with content-based hashes (individual files not comparable between builds)

Server

Middleware
Canary PR Change
middleware-b..fest.js gzip 767 B 766 B
Total 767 B 766 B ✅ -1 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 450 B 452 B
Total 450 B 452 B ⚠️ +2 B

📦 Webpack

Client

Main Bundles
Canary PR Change
5528-HASH.js gzip 5.54 kB N/A -
6280-HASH.js gzip 59.1 kB N/A -
6335.HASH.js gzip 169 B N/A -
912-HASH.js gzip 4.59 kB N/A -
e8aec2e4-HASH.js gzip 62.6 kB N/A -
framework-HASH.js gzip 59.7 kB 59.7 kB
main-app-HASH.js gzip 255 B 253 B
main-HASH.js gzip 39.1 kB 39.1 kB
webpack-HASH.js gzip 1.68 kB 1.68 kB
262-HASH.js gzip N/A 4.59 kB -
2889.HASH.js gzip N/A 169 B -
5602-HASH.js gzip N/A 5.55 kB -
6948ada0-HASH.js gzip N/A 62.6 kB -
9544-HASH.js gzip N/A 60.2 kB -
Total 233 kB 234 kB ⚠️ +1.04 kB
Polyfills
Canary PR Change
polyfills-HASH.js gzip 39.4 kB 39.4 kB
Total 39.4 kB 39.4 kB
Pages
Canary PR Change
_app-HASH.js gzip 194 B 194 B
_error-HASH.js gzip 183 B 180 B 🟢 3 B (-2%)
css-HASH.js gzip 331 B 330 B
dynamic-HASH.js gzip 1.81 kB 1.81 kB
edge-ssr-HASH.js gzip 256 B 256 B
head-HASH.js gzip 351 B 352 B
hooks-HASH.js gzip 384 B 383 B
image-HASH.js gzip 580 B 581 B
index-HASH.js gzip 260 B 260 B
link-HASH.js gzip 2.51 kB 2.51 kB
routerDirect..HASH.js gzip 320 B 319 B
script-HASH.js gzip 386 B 386 B
withRouter-HASH.js gzip 315 B 315 B
1afbb74e6ecf..834.css gzip 106 B 106 B
Total 7.98 kB 7.98 kB ✅ -1 B

Server

Edge SSR
Canary PR Change
edge-ssr.js gzip 125 kB 125 kB
page.js gzip 254 kB 255 kB
Total 379 kB 380 kB ⚠️ +1.09 kB
Middleware
Canary PR Change
middleware-b..fest.js gzip 618 B 615 B
middleware-r..fest.js gzip 156 B 155 B
middleware.js gzip 43.6 kB 43.6 kB
edge-runtime..pack.js gzip 842 B 842 B
Total 45.2 kB 45.3 kB ⚠️ +42 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 715 B 718 B
Total 715 B 718 B ⚠️ +3 B
Build Cache
Canary PR Change
0.pack gzip 4.04 MB 4.05 MB 🔴 +9.57 kB (+0%)
index.pack gzip 103 kB 103 kB
index.pack.old gzip 103 kB 102 kB
Total 4.25 MB 4.26 MB ⚠️ +9.06 kB

🔄 Shared (bundler-independent)

Runtimes
Canary PR Change
app-page-exp...dev.js gzip 321 kB 322 kB
app-page-exp..prod.js gzip 170 kB 171 kB
app-page-tur...dev.js gzip 321 kB 321 kB
app-page-tur..prod.js gzip 170 kB 170 kB
app-page-tur...dev.js gzip 317 kB 318 kB
app-page-tur..prod.js gzip 168 kB 169 kB
app-page.run...dev.js gzip 318 kB 318 kB
app-page.run..prod.js gzip 168 kB 169 kB
app-route-ex...dev.js gzip 70.5 kB 70.5 kB
app-route-ex..prod.js gzip 48.8 kB 48.8 kB
app-route-tu...dev.js gzip 70.6 kB 70.6 kB
app-route-tu..prod.js gzip 48.9 kB 48.9 kB
app-route-tu...dev.js gzip 70.1 kB 70.1 kB
app-route-tu..prod.js gzip 48.6 kB 48.6 kB
app-route.ru...dev.js gzip 70.1 kB 70.1 kB
app-route.ru..prod.js gzip 48.6 kB 48.6 kB
dist_client_...dev.js gzip 324 B 324 B
dist_client_...dev.js gzip 326 B 326 B
dist_client_...dev.js gzip 318 B 318 B
dist_client_...dev.js gzip 317 B 317 B
pages-api-tu...dev.js gzip 43.2 kB 43.2 kB
pages-api-tu..prod.js gzip 32.9 kB 32.9 kB
pages-api.ru...dev.js gzip 43.2 kB 43.2 kB
pages-api.ru..prod.js gzip 32.9 kB 32.9 kB
pages-turbo....dev.js gzip 52.6 kB 52.6 kB
pages-turbo...prod.js gzip 38.5 kB 38.5 kB
pages.runtim...dev.js gzip 52.6 kB 52.6 kB
pages.runtim..prod.js gzip 38.5 kB 38.5 kB
server.runti..prod.js gzip 61.9 kB 61.9 kB
Total 2.83 MB 2.83 MB ⚠️ +3.56 kB
📝 Changed Files (8 files)

Files with changes:

  • app-page-exp..ntime.dev.js
  • app-page-exp..time.prod.js
  • app-page-tur..ntime.dev.js
  • app-page-tur..time.prod.js
  • app-page-tur..ntime.dev.js
  • app-page-tur..time.prod.js
  • app-page.runtime.dev.js
  • app-page.runtime.prod.js
View diffs
app-page-exp..ntime.dev.js
failed to diff
app-page-exp..time.prod.js
failed to diff
app-page-tur..ntime.dev.js
failed to diff
app-page-tur..time.prod.js

Diff too large to display

app-page-tur..ntime.dev.js
failed to diff
app-page-tur..time.prod.js
failed to diff
app-page.runtime.dev.js
failed to diff
app-page.runtime.prod.js

Diff too large to display

📎 Tarball URL
https://vercel-packages.vercel.app/next/commits/f6b0988aa84e6db1d4651ac0982381e22183a2be/next

@nextjs-bot
Copy link
Collaborator

nextjs-bot commented Mar 2, 2026

Tests Passed

@unstubbable unstubbable force-pushed the hl/cached-navs-4 branch 2 times, most recently from 64fe9e0 to 79f2ba5 Compare March 2, 2026 18:38
@unstubbable unstubbable force-pushed the hl/cached-navs-4 branch 2 times, most recently from 8190feb to 9431026 Compare March 2, 2026 21:23
@unstubbable unstubbable marked this pull request as ready for review March 3, 2026 21:49
@unstubbable unstubbable changed the base branch from hl/cached-navs-3 to graphite-base/90666 March 4, 2026 16:44
When navigating to a page with `unstable_instant: { prefetch: 'runtime'
}` and no prior prefetch (e.g. `prefetch={false}` or clicking before
prefetch completes), the server now embeds a runtime prefetch stream in
the dynamic RSC navigation payload. On the client, this stream is
decoded and written into the segment cache so that subsequent
navigations to the same page can serve runtime-prefetchable content
(cookies, headers, searchParams) instantly, without needing a separate
prefetch request.

On the server, `generateStagedDynamicFlightRenderResult` detects routes
with runtime prefetching enabled and attaches a `CacheSignal` and
`PrerenderResumeDataCache` to the `RequestStore`. The dynamic render
fills these caches as a side effect. Once `cacheSignal.cacheReady()`
resolves, a final runtime prerender (the same 5-stage pipeline used for
regular runtime prefetches) runs and its output is piped into a
`TransformStream` whose readable side is included in the RSC payload as
the `p` field on the `NavigationFlightResponse`. This avoids a separate
prospective prerender because the dynamic render has already warmed the
caches.

On the client, `processRuntimePrefetchStream` strips the completeness
marker, decodes the inner Flight stream, and the result is written into
the segment cache via `writeDynamicRenderResponseIntoCache` with
`FetchStrategy.PPRRuntime`. Both the `navigateToUnknownRoute` and
`fetchMissingDynamicData` code paths handle the new stream.

This is gated on the explicit `unstable_instant` opt-in because it adds
extra server processing (a full runtime prerender per navigation
request) and increases payload size. It also requires that the runtime
prefetch output has been validated first.

Known limitation: the runtime prefetch cache write currently evicts the
static cache entry (which may have a longer stale time) because
`upsertSegmentEntry` treats the fallback match as a replacement target.
This means that after the runtime cache expires, the static cache is no
longer available as a fallback. A follow-up will address this with a
layered cache approach where entries with different fetch strategies and
stale times coexist independently.

Extracting runtime data from initial HTML loads (the PPR resume path) is
also deferred to a follow-up.
@unstubbable unstubbable force-pushed the graphite-base/90666 branch from 77ae56e to 5a18a71 Compare March 4, 2026 16:44
@graphite-app graphite-app bot changed the base branch from graphite-base/90666 to canary March 4, 2026 16:45
@unstubbable unstubbable merged commit 4b56af9 into canary Mar 4, 2026
413 of 417 checks passed
@unstubbable unstubbable deleted the hl/cached-navs-4 branch March 4, 2026 18:09
sokra pushed a commit that referenced this pull request Mar 6, 2026
…#90666)

When navigating to a page with `unstable_instant: { prefetch: 'runtime'
}` and no prior prefetch (e.g. `prefetch={false}` or clicking before
prefetch completes), the server now embeds a runtime prefetch stream in
the dynamic RSC navigation payload. On the client, this stream is
decoded and written into the segment cache so that subsequent
navigations to the same page can serve runtime-prefetchable content
(cookies, headers, searchParams) instantly, without needing a separate
prefetch request.

On the server, `generateStagedDynamicFlightRenderResult` detects routes
with runtime prefetching enabled and attaches a `CacheSignal` and
`PrerenderResumeDataCache` to the `RequestStore`. The dynamic render
fills these caches as a side effect. Once `cacheSignal.cacheReady()`
resolves, a final runtime prerender (the same 5-stage pipeline used for
regular runtime prefetches) runs and its output is piped into a
`TransformStream` whose readable side is included in the RSC payload as
the `p` field on the `NavigationFlightResponse`. This avoids a separate
prospective prerender because the dynamic render has already warmed the
caches.

On the client, `processRuntimePrefetchStream` strips the isPartial byte,
decodes the inner Flight stream, and the result is written into the
segment cache via `writeDynamicRenderResponseIntoCache` with
`FetchStrategy.PPRRuntime`. Both the `navigateToUnknownRoute` and
`fetchMissingDynamicData` code paths handle the new stream.

This is gated on the explicit `unstable_instant` opt-in because it adds
extra server processing (a full runtime prerender per navigation
request) and increases payload size. It also requires that the runtime
prefetch output has been validated first.

Known limitation: the runtime prefetch cache write currently evicts the
static cache entry (which may have a longer stale time) because
`upsertSegmentEntry` treats the fallback match as a replacement target.
This means that after the runtime cache expires, the static cache is no
longer available as a fallback. A follow-up may address this with a
layered cache approach where entries with different fetch strategies and
stale times coexist independently.

Extracting runtime data from initial HTML loads (the PPR resume path) is
also deferred to a follow-up.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants