Repository navigation
Conversation
A tab that outlives a deployment imports chunks that no longer exist. The loader answers it with the new build's props, the component import 404s, and the navigation dies on an error boundary or on the detached error page. Each build now gets one id, folded into both bundles. A Pages GET carries it, every Pages response names the build that answered, and a request from another build gets the reload response the protocol upgrade path already uses. The tab loads the destination as a document, keeping its query and fragment. Adapter plugins accept `deployRecovery: false` to keep their own error boundaries in charge.
A cached JSON payload now carries the build that rendered it, and a request from another build skips the entry so the app can answer with its reload response.
Collaborator
Author
|
👁️🗨️ Review this pull request with grouped, summarized diffs at: raw result💭 analyzed by {
"headSha": "2dd6b067cde65cb86b7d14dd2f9dae0a196b86a6",
"result": {
"overallSummary": "A tab left open across a deploy imports chunks that no longer exist, so its next Pages navigation dies on the error boundary. This PR gives each build an id folded into both bundles, has the client send it and compare it against the response, and recovers a stale navigation with a single document load of the destination (query and fragment intact), with `deployRecovery: false` as the opt-out.",
"groups": [
{
"key": "build-identity-core",
"label": "Build identity and recovery",
"summary": "The heart of the change: derive one source-hash id per build, define it into both bundles, carry it on the wire, and let the server answer a GET from another build with the existing reload response while the client turns that into a document load of the destination.\n\nWorth extra care: the id must be identical in the client and server bundles, and the reload must fire at most once per destination.",
"category": "core",
"filePaths": [
"packages/edge/src/pages-protocol.ts",
"packages/edge/src/index.ts",
"packages/void/env.d.ts",
"packages/void/src/pages/build-id.ts",
"packages/void/src/pages/build-id-source.ts",
"packages/void/src/pages/plugin.ts",
"packages/void/src/pages/protocol.ts",
"packages/void/src/pages/navigation-engine.ts"
],
"critical": true,
"fileNotes": [
{
"path": "packages/void/src/pages/build-id-source.ts",
"text": "The cache is keyed on size + mtime rather than content, so the id is trusted whenever that fingerprint matches. The test documents the consequence: an edit that keeps the size and restores the mtime reuses the old id."
},
{
"path": "packages/void/src/pages/plugin.ts",
"text": "`buildId ??=` is computed once per plugin instance so both environment config resolutions agree; `userConfig.define` is spread *after* the computed define, which is what lets an app pin the id."
},
{
"path": "packages/void/src/pages/navigation-engine.ts",
"text": "Three separate guards here: the prefetch path drops a stale payload without reloading, only `method === 'GET'` may reload, and `claimDeployReload` allows one reload per (build, url) per 10s in `sessionStorage`. Removing any one of them reintroduces a bug the tests cover."
},
{
"path": "packages/void/src/pages/protocol.ts",
"text": "The build check is deliberately not in `Vary`: only the no-store reload response differs by build, and the payload body does not. A reviewer might expect a `Vary` here."
}
]
},
{
"key": "isr-build-scope",
"label": "ISR cache per build",
"summary": "Closes the hole the core change would otherwise leave: an ISR JSON cache hit skips the app entirely, so the reload response never happens. Cached payloads now keep the build that rendered them and are bypassed for a client from another build.",
"category": "data",
"filePaths": [
"packages/isr/src/runtime.ts"
],
"fileNotes": [
{
"path": "packages/isr/src/runtime.ts",
"text": "The build id is captured from the response header at populate time and replayed on the HIT; a client that sends no id still gets the cache (`isStaleBuild` returns false when nothing was seen)."
}
]
},
{
"key": "adapter-options",
"label": "Adapter option pass-through",
"summary": "Each framework plugin gains `deployRecovery` and now forwards its whole options object to the pages plugin instead of listing options one by one, so future pages-owned options need no per-adapter glue.",
"category": "build",
"filePaths": [
"packages/react/src/plugin.ts",
"packages/react/src/plugin-pages.ts",
"packages/solid/src/plugin.ts",
"packages/solid/src/plugin-pages.ts",
"packages/svelte/src/plugin.ts",
"packages/svelte/src/plugin-pages.ts",
"packages/vue/src/plugin.ts",
"packages/vue/src/plugin-pages.ts"
],
"fileNotes": [
{
"path": "packages/react/src/plugin.ts",
"text": "The spread now forwards every adapter option (including `react`, plus the new `deployRecovery`) into `pagesPlugin`; check that no option the pages plugin does not own starts colliding."
}
]
},
{
"key": "docs",
"label": "Recovery docs",
"summary": "Documents the deploy behaviour under Pages routing and lists `deployRecovery` in each framework's option reference.",
"category": "docs",
"filePaths": [
"docs/guide/pages-routing/overview.md",
"docs/reference/api/pages.md"
]
},
{
"key": "tests",
"label": "Tests",
"summary": "Covers build-id derivation and caching, the dev/opt-out no-op cases, the server reload response vs. matching build vs. stale mutation, the client reload/prefetch/dedupe paths, and the ISR bypass.",
"category": "tests",
"filePaths": [
"packages/void/test/unit/pages-build-id.test.ts",
"packages/void/test/unit/pages-client.test.ts",
"packages/void/test/unit/pages-protocol.test.ts",
"packages/void/test/unit/isr-cache.test.ts",
"packages/void/test/unit/pages-plugin-adapters.test.ts"
]
}
],
"schemaVersion": 1,
"source": "llm",
"generatedAt": "2026-11-22T03:26:23.220Z",
"model": "openai-compatible/opencode-go/deepseek-v4.1-flash",
"locale": "en"
}
} |
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #849
Description
A tab that outlives a deployment imports chunks that no longer exist. The loader answers it with the new build's props, the component import 404s, and the navigation dies on an error boundary or on the detached "Something went wrong" page.
The tab now notices that the server runs a different build and recovers with one document load of the destination it asked for. The query string and fragment survive, the current page stays visible until the load starts, and the failed import never happens.
deployRecovery: falseturns it off.Each build gets one id, folded into the client and the server bundle. Every Pages request carries it in
X-VoidPages-Build, and every response names the build that answered. A GET from another build gets the response the protocol upgrade path already uses: no page data,no-store, and the current build in the header.Three things never reload the tab:
Options
void deploywould need one sourceVary: X-VoidPages-BuildOne reload per destination per 10s, kept in
sessionStorage, guards against a cache that keeps serving the old document. Without storage the guard is inert and the reload still happens.The id covers the whole source tree, so a server-only deploy also reloads open tabs, once. Hashing the client output would be exact, but those names exist only after the client build, and the Node target builds the server first. The breadth costs one extra document load on such a deploy. Hashing itself is cheap: about 1ms for a normal app, and the second pass over an 8000-file tree reuses the cached id in about 30ms.
Server-side comparison means the request carries a build and the response depends on it, without
Vary. Page data isno-store, so the responses that differ are already uncached. If the request shape should stay fixed, the client can compare the response header instead, at the costs above.Still open
Prerendered apps keep page props in
/_void/pages/*.json, which has no build id, so a stale tab on a prerendered page still lands on its error boundary.Rolling deployments compare ids exactly, without a retry. While two builds are live, a fresh tab can reload once more than it needed to. A retry would have to tell a rollout apart from a stale document, which the tab cannot see.
Test
Build identity: one id per build across environments, derived from the source, withheld in dev and when recovery is off.
Server: a GET from another build gets the reload response with the current id and no page data. A matching build gets the payload. A mutation from a stale client keeps its response.
Client: the visit reloads the destination with its query and fragment, a second visit renders instead, a prefetch drops a stale payload, a stale mutation response is applied, and a response with no build id is left alone.
ISR: an entry from another build is bypassed, a matching one is served with its id, and a client that sends no id still hits the cache.
Both captures use
playground/react-pagesand the same request:GET /withX-VoidPages: true,X-VoidPages-Version: 2andX-VoidPages-Build: 000000000000.Base
92a01567b:537 bytes of page props for a tab that cannot import them. This is the bug.
This branch:
An empty body, no
x-voidpages, and the live build, which is the reload the client performs. The same request carrying that id returns the 537-byte payload, header included, unchanged.Both bundles of that build inline
e599410d42d0. The per-build UUID this started with produced18ad6551…in one and5c7377c7…in the other.