Skip to content

partial fallbacks: complete generic shells into more specific shells#91231

Merged
ztanner merged 4 commits intocanaryfrom
ztanner/complete-partial-fallback-shells
Mar 14, 2026
Merged

partial fallbacks: complete generic shells into more specific shells#91231
ztanner merged 4 commits intocanaryfrom
ztanner/complete-partial-fallback-shells

Conversation

@ztanner
Copy link
Copy Markdown
Member

@ztanner ztanner commented Mar 12, 2026 •
edited
Loading

In #91158, I wired up the plumbing to indicate whether a partial fallback shell is upgradeable. The previous heuristic was too coarse. This wires up the handling in next start.

This PR teaches the runtime to complete a fallback shell only as far as prerendering allows. Instead of promoting a generic shell like /[one]/[two] directly to /c/foo, it promotes it to the most specific prerendered shell for that branch, /c/[two], where [one] has generateStaticParams. That means later requests can reuse the more complete shell, while fully dynamic params continue to stream as dynamic content.

With this change:

  • the first request still serves the generic fallback shell immediately
  • the background revalidate writes a more specific shell, not a fully concrete route
  • later requests for the same prerendered branch reuse that shell
  • upgrading stops once only fully dynamic params remain

This keeps the runtime behavior aligned with the build-time remainingPrerenderableParams contract from the downstack PR.

@ztanner ztanner mentioned this pull request Mar 12, 2026
Merged
@ztanner Graphite App
Copy link
Copy Markdown
Member Author

ztanner commented Mar 12, 2026 •
edited
Loading

This stack of pull requests is managed by Graphite. Learn more about stacking.

@ztanner ztanner mentioned this pull request Mar 12, 2026
Closed
@ztanner ztanner force-pushed the 03-10-partial_fallbacks_properly_gate_on_generatestaticparams branch from 76e8322 to 2d4f86a Compare March 12, 2026 00:29
@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch 2 times, most recently from ffe551c to 2c6c867 Compare March 12, 2026 00:34
@ztanner ztanner force-pushed the 03-10-partial_fallbacks_properly_gate_on_generatestaticparams branch from 2d4f86a to 9e3bc3a Compare March 12, 2026 00:34
@nextjs-bot
Copy link
Copy Markdown
Collaborator

nextjs-bot commented Mar 12, 2026 •
edited
Loading

Tests Passed

@nextjs-bot
Copy link
Copy Markdown
Collaborator

nextjs-bot commented Mar 12, 2026 •
edited
Loading

Stats from current PR

🔴 1 regression

Metric Canary PR Change Trend
node_modules Size 482 MB 482 MB 🔴 +107 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) 915ms 913ms ✓ ▁▁▁▁█
Cold (Ready in log) 895ms 893ms ✓ ▁▁▁▁█
Cold (First Request) 1.555s 1.630s ✓ ▁▁▁▁█
Warm (Listen) 913ms 914ms ✓ ▁▁▁▁█
Warm (Ready in log) 890ms 891ms ✓ ▁▁▁▁█
Warm (First Request) 685ms 696ms ✓ ▁▁▁▁█
📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric Canary PR Change Trend
Cold (Listen) 455ms 455ms ✓ ▃▁▁▃▁
Cold (Ready in log) 439ms 438ms ✓ ▁▅▁▅▆
Cold (First Request) 1.952s 1.946s ✓ ▁▄▁▄▄
Warm (Listen) 455ms 456ms ✓ ▁▁▁▁▁
Warm (Ready in log) 438ms 439ms ✓ ▁▅▁▄▅
Warm (First Request) 1.966s 1.953s ✓ ▁▄▁▄▅

⚡ Production Builds

Metric Canary PR Change Trend
Fresh Build 6.208s 6.159s ✓ ▁▁▁▁█
Cached Build 6.278s 6.349s ✓ ▁▁▁▁█
📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric Canary PR Change Trend
Fresh Build 14.319s 14.297s ✓ ▃▁▂▂▂
Cached Build 14.389s 14.441s ✓ ▃▁▃▁▂
node_modules Size 482 MB 482 MB 🔴 +107 kB (+0%) █████
📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **408 kB** → **408 kB** ✅ -6 B

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

Server

Middleware
Canary PR Change
middleware-b..fest.js gzip 765 B 759 B ✓
Total 765 B 759 B ✅ -6 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 450 B 451 B ✓
Total 450 B 451 B ⚠️ +1 B

📦 Webpack

Client

Main Bundles
Canary PR Change
5528-HASH.js gzip 5.54 kB N/A -
6280-HASH.js gzip 59.9 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.7 kB N/A -
framework-HASH.js gzip 59.7 kB 59.7 kB ✓
main-app-HASH.js gzip 256 B 252 B 🟢 4 B (-2%)
main-HASH.js gzip 39.2 kB 39.2 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.7 kB -
9544-HASH.js gzip N/A 60.6 kB -
Total 234 kB 234 kB ⚠️ +721 B
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 267 kB 267 kB ✓
Total 392 kB 392 kB ⚠️ +657 B
Middleware
Canary PR Change
middleware-b..fest.js gzip 615 B 616 B ✓
middleware-r..fest.js gzip 156 B 155 B ✓
middleware.js gzip 43.5 kB 43.7 kB ✓
edge-runtime..pack.js gzip 842 B 842 B ✓
Total 45.1 kB 45.3 kB ⚠️ +218 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 716 B 718 B ✓
Total 716 B 718 B ⚠️ +2 B
Build Cache
Canary PR Change
0.pack gzip 4.21 MB 4.24 MB 🔴 +24.2 kB (+1%)
index.pack gzip 108 kB 108 kB ✓
index.pack.old gzip 108 kB 107 kB ✓
Total 4.43 MB 4.45 MB ⚠️ +24.3 kB

🔄 Shared (bundler-independent)

Runtimes
Canary PR Change
app-page-exp...dev.js gzip 332 kB 332 kB ✓
app-page-exp..prod.js gzip 180 kB 180 kB ✓
app-page-tur...dev.js gzip 331 kB 331 kB ✓
app-page-tur..prod.js gzip 180 kB 180 kB ✓
app-page-tur...dev.js gzip 328 kB 328 kB ✓
app-page-tur..prod.js gzip 178 kB 178 kB ✓
app-page.run...dev.js gzip 328 kB 328 kB ✓
app-page.run..prod.js gzip 178 kB 178 kB ✓
app-route-ex...dev.js gzip 75.9 kB 75.9 kB ✓
app-route-ex..prod.js gzip 51.7 kB 51.7 kB ✓
app-route-tu...dev.js gzip 76 kB 76 kB ✓
app-route-tu..prod.js gzip 51.7 kB 51.7 kB ✓
app-route-tu...dev.js gzip 75.6 kB 75.6 kB ✓
app-route-tu..prod.js gzip 51.5 kB 51.5 kB ✓
app-route.ru...dev.js gzip 75.5 kB 75.5 kB ✓
app-route.ru..prod.js gzip 51.4 kB 51.4 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.3 kB 43.3 kB ✓
pages-api-tu..prod.js gzip 33 kB 33 kB ✓
pages-api.ru...dev.js gzip 43.3 kB 43.3 kB ✓
pages-api.ru..prod.js gzip 33 kB 33 kB ✓
pages-turbo....dev.js gzip 52.7 kB 52.7 kB ✓
pages-turbo...prod.js gzip 38.6 kB 38.6 kB ✓
pages.runtim...dev.js gzip 52.7 kB 52.7 kB ✓
pages.runtim..prod.js gzip 38.6 kB 38.6 kB ✓
server.runti..prod.js gzip 62.4 kB 62.4 kB ✓
Total 2.94 MB 2.94 MB ⚠️ +51 B
📝 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

Diff too large to display

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

Diff too large to display

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/95734b8e508730371adf34216ab60747afa58785/next

@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch 2 times, most recently from 811c48f to ab5e416 Compare March 12, 2026 01:50
@ztanner ztanner force-pushed the 03-10-partial_fallbacks_properly_gate_on_generatestaticparams branch from 9e3bc3a to 1d62a5f Compare March 12, 2026 01:50
@ztanner ztanner changed the title Partial Fallbacks: complete into the most specific prerenderable shell partial fallbacks: complete generic shells into the most specific prerendered shell Mar 12, 2026
@ztanner ztanner changed the title partial fallbacks: complete generic shells into the most specific prerendered shell partial fallbacks: complete generic shells into more specific shells Mar 12, 2026
@ztanner ztanner force-pushed the 03-10-partial_fallbacks_properly_gate_on_generatestaticparams branch from 1d62a5f to 3260155 Compare March 12, 2026 14:52
@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch 3 times, most recently from 66f3bd1 to dded37d Compare March 12, 2026 17:04
@ztanner ztanner marked this pull request as ready for review March 12, 2026 17:57
@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch from dded37d to 6fa5319 Compare March 12, 2026 18:27
@ztanner ztanner force-pushed the 03-10-partial_fallbacks_properly_gate_on_generatestaticparams branch from 3260155 to a63d9ae Compare March 12, 2026 18:27
@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch from 6fa5319 to 9d5c5ae Compare March 12, 2026 18:31
@ztanner ztanner force-pushed the 03-10-partial_fallbacks_properly_gate_on_generatestaticparams branch from a63d9ae to 967f390 Compare March 12, 2026 20:58
@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch from 9d5c5ae to 80f34b9 Compare March 12, 2026 20:58
@ztanner ztanner requested review from gnoff and ijjk March 12, 2026 22:03
lubieowoce
lubieowoce reviewed Mar 12, 2026
View reviewed changes
@ztanner Graphite App
Copy link
Copy Markdown
Member Author

ztanner commented Mar 14, 2026 •
edited
Loading

Merge activity

  • Mar 14, 12:34 AM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Mar 14, 12:37 AM UTC: Graphite rebased this pull request as part of a merge.
  • Mar 14, 1:06 AM UTC: Graphite couldn't merge this PR because it was not satisfying all requirements (Failed CI: 'thank you, next', 'test prod (5/10) / build').

@ztanner ztanner changed the base branch from 03-10-partial_fallbacks_properly_gate_on_generatestaticparams to graphite-base/91231 March 14, 2026 00:35
@ztanner ztanner changed the base branch from graphite-base/91231 to canary March 14, 2026 00:35
@ztanner ztanner force-pushed the ztanner/complete-partial-fallback-shells branch from 95734b8 to 3f870bc Compare March 14, 2026 00:37
@ztanner ztanner merged commit ae3f9f5 into canary Mar 14, 2026
281 of 284 checks passed
@ztanner ztanner deleted the ztanner/complete-partial-fallback-shells branch March 14, 2026 01:21
unstubbable added a commit that referenced this pull request Mar 20, 2026
@unstubbable
Fix server actions in standalone mode with cacheComponents
2dd7712 
The `staticPathKey` condition added in #91231 inadvertently applies to
server action requests on dynamic SSG routes when `cacheComponents` is
enabled.

Server action fetch requests from the client do not send the `RSC`
header (`rsc: 1`). They only send `Accept: text/x-component` and the
`Next-Action` header. This means `isRSCRequest` and
`isDynamicRSCRequest` are both `false` for action requests. The new
`staticPathKey` condition (`isSSG && pageIsDynamic &&
prerenderInfo?.fallbackRouteParams`) evaluates to `true` for dynamic PPR
routes, setting `staticPathKey` even though `ssgCacheKey` is `null` for
actions.

With `staticPathKey` set, the request enters the fallback rendering
block, which serves the cached fallback HTML shell with the action
result appended to it, instead of responding with just the RSC action
result.

The fix excludes server action requests from the `staticPathKey`
computation by adding `!isPossibleServerAction` to the condition,
restoring the pre-#91231 behavior where `staticPathKey` was always
`null` for server actions in production.

fixes #91662
closes #91677
closes #91669
@unstubbable unstubbable mentioned this pull request Mar 20, 2026
Merged
unstubbable added a commit that referenced this pull request Mar 20, 2026
@unstubbable
Fix server actions in standalone mode with cacheComponents
62c15cb 
The `staticPathKey` condition added in #91231 inadvertently applies to
server action requests on dynamic SSG routes when `cacheComponents` is
enabled.

Server action fetch requests from the client do not send the `RSC`
header (`rsc: 1`). They only send `Accept: text/x-component` and the
`Next-Action` header. This means `isRSCRequest` and
`isDynamicRSCRequest` are both `false` for action requests. The new
`staticPathKey` condition (`isSSG && pageIsDynamic &&
prerenderInfo?.fallbackRouteParams`) evaluates to `true` for dynamic PPR
routes, setting `staticPathKey` even though `ssgCacheKey` is `null` for
actions.

With `staticPathKey` set, the request enters the fallback rendering
block, which serves the cached fallback HTML shell with the action
result appended to it, instead of responding with just the RSC action
result.

The fix excludes server action requests from the `staticPathKey`
computation by adding `!isPossibleServerAction` to the condition,
restoring the pre-#91231 behavior where `staticPathKey` was always
`null` for server actions in production.

fixes #91662
closes #91677
closes #91669
unstubbable added a commit that referenced this pull request Mar 20, 2026
@unstubbable
Fix server actions in standalone mode with cacheComponents (#91711)
8cbc037 
The `staticPathKey` condition added in #91231 inadvertently applies to
server action requests on dynamic SSG routes when `cacheComponents` is
enabled.

Server action fetch requests from the client do not send the `RSC`
header (`rsc: 1`). They only send `Accept: text/x-component` and the
`Next-Action` header. This means `isRSCRequest` and
`isDynamicRSCRequest` are both `false` for action requests. The new
`staticPathKey` condition (`isSSG && pageIsDynamic &&
prerenderInfo?.fallbackRouteParams`) evaluates to `true` for dynamic PPR
routes, setting `staticPathKey` even though `ssgCacheKey` is `null` for
actions.

With `staticPathKey` set, the request enters the fallback rendering
block, which serves the cached fallback HTML shell with the action
result appended to it, instead of responding with just the RSC action
result.

The fix excludes server action requests from the `staticPathKey`
computation by adding `!isPossibleServerAction` to the condition,
restoring the pre-#91231 behavior where `staticPathKey` was always
`null` for server actions in production.

fixes #91662
closes #91677
closes #91669
ijjk pushed a commit that referenced this pull request Mar 20, 2026
@unstubbable @ijjk
Fix server actions in standalone mode with cacheComponents (#91711)
88fc430 
The `staticPathKey` condition added in #91231 inadvertently applies to
server action requests on dynamic SSG routes when `cacheComponents` is
enabled.

Server action fetch requests from the client do not send the `RSC`
header (`rsc: 1`). They only send `Accept: text/x-component` and the
`Next-Action` header. This means `isRSCRequest` and
`isDynamicRSCRequest` are both `false` for action requests. The new
`staticPathKey` condition (`isSSG && pageIsDynamic &&
prerenderInfo?.fallbackRouteParams`) evaluates to `true` for dynamic PPR
routes, setting `staticPathKey` even though `ssgCacheKey` is `null` for
actions.

With `staticPathKey` set, the request enters the fallback rendering
block, which serves the cached fallback HTML shell with the action
result appended to it, instead of responding with just the RSC action
result.

The fix excludes server action requests from the `staticPathKey`
computation by adding `!isPossibleServerAction` to the condition,
restoring the pre-#91231 behavior where `staticPathKey` was always
`null` for server actions in production.

fixes #91662
closes #91677
closes #91669
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 28, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@lubieowoce lubieowoce lubieowoce left review comments

@ijjk ijjk ijjk approved these changes

@gnoff gnoff Awaiting requested review from gnoff

Assignees

No one assigned

Labels

created-by: Next.js team PRs by the Next.js team. locked tests type: next

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@ztanner @nextjs-bot @lubieowoce @ijjk