Skip to content

[next]: add partial fallback support#14703

Merged
ztanner merged 2 commits intomainfrom
ztanner/partial-fallback-upgrading
Mar 2, 2026
Merged

[next]: add partial fallback support#14703
ztanner merged 2 commits intomainfrom
ztanner/partial-fallback-upgrading

Conversation

@ztanner
Copy link
Member

@ztanner ztanner commented Jan 22, 2026

This PR adds the partialFallback property onto the Prerender document. This will signal different fallback semantics: namely, the expectation with a partial fallback is that it will immediately kick off a background revalidation to produce a more complete static document.

See vercel/next.js#89063 corresponding Next.js changes.

@changeset-bot
Copy link

changeset-bot bot commented Jan 22, 2026

🦋 Changeset detected

Latest commit: 9f5f47d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages
Name Type
@vercel/build-utils Patch
@vercel/next Patch
@vercel/backends Patch
vercel Patch
@vercel/client Patch
@vercel/elysia Patch
@vercel/express Patch
@vercel/fastify Patch
@vercel/gatsby-plugin-vercel-builder Patch
@vercel/h3 Patch
@vercel/hono Patch
@vercel/koa Patch
@vercel/nestjs Patch
@vercel/node Patch
@vercel/static-build Patch
@vercel/cervel Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions
Copy link
Contributor

github-actions bot commented Jan 22, 2026

📦 CLI Tarball Ready

The Vercel CLI tarball for this PR is now available!

Quick Test

You can test this PR's CLI directly by running:

npx https://vercel-q8jx9on54.vercel.sh/tarballs/vercel.tgz --help

Use in vercel.json

To use this CLI version in your project builds, add to your vercel.json:

{
  "build": {
    "env": {
      "VERCEL_CLI_VERSION": "vercel@https://vercel-q8jx9on54.vercel.sh/tarballs/vercel.tgz"
    }
  }
}

Python Runtime Wheel

A vercel-runtime wheel was also built for this PR.
To use in your Python project builds, also set this environment variable:

VERCEL_RUNTIME_PYTHON="vercel-runtime @ https://vercel-q8jx9on54.vercel.sh/tarballs/vercel_runtime-0.6.0.dev1772474522+9f5f47d-py3-none-any.whl"

Python Workers Wheel

A vercel-workers wheel was also built for this PR.
To use in your Python project builds, also set this environment variable:

VERCEL_WORKERS_PYTHON="vercel-workers @ https://vercel-q8jx9on54.vercel.sh/tarballs/vercel_workers-0.1.0.dev1772474522+9f5f47d-py3-none-any.whl"

@github-actions
Copy link
Contributor

github-actions bot commented Jan 22, 2026

🧪 Unit Test Strategy

Comparing: 34120ab9f5f47d (view diff)

Strategy: Code changed outside of a package - running all unit tests

⚠️ All unit tests will run because global code changes could impact all packages.

Affected packages - 40 (100%)
  1. @vercel-internals/get-package-json
  2. @vercel/backends
  3. @vercel/build-utils
  4. @vercel/cervel
  5. @vercel/cli-auth
  6. @vercel/client
  7. @vercel/config
  8. @vercel/detect-agent
  9. @vercel/edge
  10. @vercel/elysia
  11. @vercel/error-utils
  12. @vercel/express
  13. @vercel/fastify
  14. @vercel/firewall
  15. @vercel/frameworks
  16. @vercel/fs-detectors
  17. @vercel/functions
  18. @vercel/gatsby-plugin-vercel-builder
  19. @vercel/go
  20. @vercel/h3
  21. @vercel/hono
  22. @vercel/hydrogen
  23. @vercel/koa
  24. @vercel/nestjs
  25. @vercel/next
  26. @vercel/node
  27. @vercel/oidc
  28. @vercel/oidc-aws-credentials-provider
  29. @vercel/python
  30. @vercel/python-analysis
  31. @vercel/redwood
  32. @vercel/related-projects
  33. @vercel/remix-builder
  34. @vercel/routing-utils
  35. @vercel/ruby
  36. @vercel/rust
  37. @vercel/static-build
  38. @vercel/static-config
  39. examples
  40. vercel

Results

  • Unit tests: All affected packages will run unit tests
  • E2E tests: Running in parallel via E2E Tests workflow
  • Type checks: All affected packages will run type checks

This comment is automatically generated based on the affected testing strategy

Copy link
Contributor

@vercel vercel bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additional Suggestion:

The doBuild function returned objects without the files field in several code paths, causing the check at index.ts:66 to fail with "Unable to trace files for build" even when builds succeeded

Fix on Vercel

@ztanner ztanner force-pushed the ztanner/partial-fallback-upgrading branch from 02bff34 to 0f4569e Compare March 2, 2026 15:55
@ztanner ztanner marked this pull request as ready for review March 2, 2026 15:56
@ztanner ztanner requested review from a team, huozhi, ijjk and timneutkens as code owners March 2, 2026 15:56
@ztanner ztanner merged commit 9721f49 into main Mar 2, 2026
200 checks passed
@ztanner ztanner deleted the ztanner/partial-fallback-upgrading branch March 2, 2026 18:33
jeffsee55 pushed a commit that referenced this pull request Mar 2, 2026
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @vercel/backends@0.0.40

### Patch Changes

- Updated dependencies
\[[`9721f4948a72d273f792c54f5393aa50ac279209`](9721f49)]:
    -   @vercel/build-utils@13.6.2

## @vercel/build-utils@13.6.2

### Patch Changes

- add partialFallback flag to prerender output
([#14703](#14703))

## @vercel/cervel@0.0.27

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/backends@0.0.40

## vercel@50.25.6

### Patch Changes

- Updated dependencies
\[[`9721f4948a72d273f792c54f5393aa50ac279209`](9721f49)]:
    -   @vercel/build-utils@13.6.2
    -   @vercel/next@4.15.37
    -   @vercel/backends@0.0.40
    -   @vercel/elysia@0.1.43
    -   @vercel/express@0.1.52
    -   @vercel/fastify@0.1.46
    -   @vercel/go@3.4.3
    -   @vercel/h3@0.1.52
    -   @vercel/hono@0.2.46
    -   @vercel/hydrogen@1.3.5
    -   @vercel/koa@0.1.26
    -   @vercel/nestjs@0.2.47
    -   @vercel/node@5.6.10
    -   @vercel/python@6.19.0
    -   @vercel/redwood@2.4.9
    -   @vercel/remix-builder@5.6.0
    -   @vercel/ruby@2.3.2
    -   @vercel/rust@1.0.5
    -   @vercel/static-build@2.8.44

## @vercel/client@17.2.51

### Patch Changes

- Updated dependencies
\[[`9721f4948a72d273f792c54f5393aa50ac279209`](9721f49)]:
    -   @vercel/build-utils@13.6.2

## @vercel/elysia@0.1.43

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10

## @vercel/express@0.1.52

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10
    -   @vercel/cervel@0.0.27

## @vercel/fastify@0.1.46

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10

## @vercel/fs-detectors@5.8.15

### Patch Changes

- Fix App Router dynamic API routes returning 404 in production. When a
project has both Next.js (App Router) and a root `api/` folder,
zero-config added a catch-all `^/api(/.*)?# @vercel/fs-detectors → 404
in the filesystem phase, which runs before the rewrite phase where
Next.js routes live. So requests like
`/api/flow/hello/next`or`/api/blog/posts/5`matched the catch-all and
never reached the Next.js route. When Next.js is the frontend we no
longer add that rewrite so those routes are handled by Next.js.
(Locally, only`next dev`worked;`vc dev\` had the same 404.)
([#15297](#15297))

## @vercel/gatsby-plugin-vercel-builder@2.0.142

### Patch Changes

- Updated dependencies
\[[`9721f4948a72d273f792c54f5393aa50ac279209`](9721f49)]:
    -   @vercel/build-utils@13.6.2

## @vercel/h3@0.1.52

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10

## @vercel/hono@0.2.46

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10

## @vercel/koa@0.1.26

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10

## @vercel/nestjs@0.2.47

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/node@5.6.10

## @vercel/next@4.15.37

### Patch Changes

- add partialFallback flag to prerender output
([#14703](#14703))

## @vercel/node@5.6.10

### Patch Changes

- Updated dependencies
\[[`9721f4948a72d273f792c54f5393aa50ac279209`](9721f49)]:
    -   @vercel/build-utils@13.6.2

## @vercel/static-build@2.8.44

### Patch Changes

-   Updated dependencies \[]:
    -   @vercel/gatsby-plugin-vercel-builder@2.0.142


<!-- VADE_RISK_START -->
> [!NOTE]
> Low Risk Change
>
> This PR is an automated Changesets release that only bumps version
numbers in package.json files and updates CHANGELOG.md files across
multiple packages, with no code logic changes.
> 
> - Version bumps in package.json files (patch versions)
> - CHANGELOG.md updates documenting dependency updates
> - Deleted changeset markdown files consumed by release process
>
> <sup>Risk assessment for [commit
00d9965](https://github.com/vercel/vercel/commit/00d9965d12c097c2375af4e717f17594ca2ed06c).</sup>
<!-- VADE_RISK_END -->

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
ztanner added a commit that referenced this pull request Mar 4, 2026
Based on #14703

This updates only `allowQuery` for fallback HTML when the route is a
true `partialFallback` (PPR fallback with postponed state) and cache
components is enabled. For all other fallback cases, behavior stays the
same as today (allowQuery is cleared to [] for shared fallback caching).

This change is needed because partial-fallback shells can be
param-specific, so collapsing them to one shared fallback cache key can
serve the wrong shell across params and block correct upgrade behavior.
Gating this behind `partialFallback` lets us roll out the new behavior
safely and independently, without changing legacy fallback semantics for
non-partial paths.

<!-- VADE_RISK_START -->
> [!NOTE]
> Low Risk Change
>
> This PR modifies caching behavior for partial fallback shells by
conditionally varying the allowQuery parameter, which is a Next.js
build/rendering optimization change rather than a security or data
schema change.
> 
> - Adds conditional logic for `htmlAllowQuery` based on
`partialFallback` and `isAppClientParamParsingEnabled`
> - Moves `partialFallback` variable declaration earlier in function
> - Updates comments explaining fallback caching behavior
>
> <sup>Risk assessment for [commit
0fc83c1](https://github.com/vercel/vercel/commit/0fc83c1231498eecad58db950cd0bfcb166004e4).</sup>
<!-- VADE_RISK_END -->
ricardo-agz pushed a commit that referenced this pull request Mar 4, 2026
Based on #14703

This updates only `allowQuery` for fallback HTML when the route is a
true `partialFallback` (PPR fallback with postponed state) and cache
components is enabled. For all other fallback cases, behavior stays the
same as today (allowQuery is cleared to [] for shared fallback caching).

This change is needed because partial-fallback shells can be
param-specific, so collapsing them to one shared fallback cache key can
serve the wrong shell across params and block correct upgrade behavior.
Gating this behind `partialFallback` lets us roll out the new behavior
safely and independently, without changing legacy fallback semantics for
non-partial paths.

<!-- VADE_RISK_START -->
> [!NOTE]
> Low Risk Change
>
> This PR modifies caching behavior for partial fallback shells by
conditionally varying the allowQuery parameter, which is a Next.js
build/rendering optimization change rather than a security or data
schema change.
> 
> - Adds conditional logic for `htmlAllowQuery` based on
`partialFallback` and `isAppClientParamParsingEnabled`
> - Moves `partialFallback` variable declaration earlier in function
> - Updates comments explaining fallback caching behavior
>
> <sup>Risk assessment for [commit
0fc83c1](https://github.com/vercel/vercel/commit/0fc83c1231498eecad58db950cd0bfcb166004e4).</sup>
<!-- VADE_RISK_END -->
ztanner added a commit to vercel/next.js that referenced this pull request Mar 6, 2026
In #69282, we landed support for
Partial Fallback Prerendering. The intention behind this feature was to
be able to upgrade from a partial fallback (essentially the UI produced
when `await params` is dynamic, ie the param was not part of
`generateStaticParams` at build time) to a route shell (when the param
values are filled in, and thus we can prerender more of the page).

It was reverted in #79258 because
we didn't add first-class support to this in the build output API and
the necessary infrastructure changes to perform similar behavior that
this PR does to trigger a background revalidation with params filled in.

This re-lands the feature in Next.js now that upstream support landed
(vercel/vercel#14703,
vercel/vercel#15338, and Vercel infra changes
which are rolling out)
sokra pushed a commit to vercel/next.js that referenced this pull request Mar 6, 2026
In #69282, we landed support for
Partial Fallback Prerendering. The intention behind this feature was to
be able to upgrade from a partial fallback (essentially the UI produced
when `await params` is dynamic, ie the param was not part of
`generateStaticParams` at build time) to a route shell (when the param
values are filled in, and thus we can prerender more of the page).

It was reverted in #79258 because
we didn't add first-class support to this in the build output API and
the necessary infrastructure changes to perform similar behavior that
this PR does to trigger a background revalidation with params filled in.

This re-lands the feature in Next.js now that upstream support landed
(vercel/vercel#14703,
vercel/vercel#15338, and Vercel infra changes
which are rolling out)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants