Version skew goes undetected on .data navigations to already-discovered routes in non-RSC framework mode

[uncoolclub]

Summary

In framework mode without RSC, a tab that's been open across a deploy can navigate to a route it already knows, fetch .data from the new server, and hand that payload to the old client modules. Nothing compares the two builds.

We'd like to add an opt-in check for this, and to write down what the expected behavior is either way. There's a draft PR at #15518.

What we saw

We run SSR on a single rolling deployment — old servers get replaced, not kept around. During a routine deploy, three people hit the root error boundary 17 times over six minutes. None of them had reloaded; they were clicking links.

1. User opens the app on build A and gets A's entry, route chunks, and manifest.
2. We deploy. Servers are now B. The open tab doesn't find out.
3. User goes /a/1 → /a/2 → /. All client navigations, so the tab keeps running A and only fetches .data.
4. Those .data requests are answered by B.

That release renamed a field in a loader payload (oldField → newField). Our API kept both keys through the transition, but the server-side zod schema on B stripped the one it no longer declared, so oldField wasn't in the response. A's component read oldField.name and threw.

Reloading fixed it, and no new session hit it.

Why the existing check doesn't fire

Route discovery does compare build versions. It just only does that when it fetches the manifest, and it skips the fetch for paths the tab already knows:

// packages/react-router/lib/dom/ssr/fog-of-war.ts
if (discoveredPaths.has(path)) return;

All three of our hops were to already-discovered routes — /a/:id was the same route both times, and / came with the initial payload. So patchRoutesOnNavigation returned early, no manifest request went out, and nothing got compared.

The .data request carries no version of its own either. singleFetchUrl() builds <pathname>.data with no version param, and we couldn't find a version reference in packages/react-router/lib/server-runtime/single-fetch.ts — the server reads X-Remix-Reload-Document on redirects but never compares builds.

RSC already does this

Since #15318 in 8.3.0, the RSC path compares the server's build version on every data fetch, not just during discovery. getFetchAndDecodeViaRSC reads it off the payload and hands mismatches to handleClientVersionMismatch. Route discovery doesn't come into it.

	manifest request	every data request
RSC (8.3.0+)	compares	compares
non-RSC single fetch	compares	nothing sent or compared

Related: #14849 frames this gap as RSC-only. With #15318 shipped that looks reversed now, which is why this is a separate thread rather than a reply there.

What we'd build

The PR stamps the server's build version onto single-fetch responses behind future.unstable_detectVersionSkew and compares it client-side, reusing handleClientVersionMismatch and its sessionStorage loop guard. Redirects are returned before the comparison so an action redirect still reaches its target.

We'd also want a section in docs/start/framework/deploying.md. That page is a list of deployment templates right now, and whichever way this goes, what happens to open tabs across a deploy seems worth stating.

Opt-in because the document navigation throws away in-flight form state, and if you keep previous builds addressable you never hit this.

What we'd like to know

Mostly whether the asymmetry is on purpose. If non-RSC mode is meant to tolerate skew on open sessions, the docs section alone is the right outcome and we'll drop the rest.

The other thing: is there a supported API for this that we missed? Before the PR we were patching window.fetch in entry.client to send our build version and checking it in a root loader, which works but leans on window.__reactRouterManifest.version and the .data URL convention, neither of which look public. We'd rather use something you already have.

Environment

• React Router 8.3.1, framework mode, SSR, no RSC
• Single rolling deployment; previous builds aren't kept addressable
• Reproducing it needs a tab loaded before a deploy and a client navigation to an already-discovered route after. Happy to put together a two-server harness if that helps.

[uncoolclub]

I went ahead and implemented this: #15518 (draft).

It does what the proposal described. The server stamps its build version onto single fetch responses behind future.unstable_detectVersionSkew, and the client compares it on arrival, reusing handleClientVersionMismatch and its loop guard. Ordering follows the RSC path, so redirects are followed through before any comparison.

The integration test covers the case that started this: a tab navigating to an already-discovered route, getting .data from a different build, and reloading instead of rendering it. It fails without the implementation.

The questions in this thread still stand, and the PR body adds a couple more that only came up while building it (header name, header vs payload, and whether this belongs in future at all). If the asymmetry turns out to be intentional, I am happy to drop the implementation and keep only the documentation part.

[uncoolclub]

Comparison link, as requested in #15518:

main...uncoolclub:react-router:version-skew-single-fetch