Proposal: let apps intervene before the RSC clientVersion skew-recovery reload

[agcty]

We've adopted the 8.3 clientVersion stale-client detection across four RSC Framework Mode apps (custom entries) and it works well. This proposal is about the one place it currently limits us: the recovery reload is unconditional and invisible to the app, and for a collaborative app that combination is actively harmful. Following the contributing guide, here's how we're limited by the current API first; a candidate shape is at the end.

The limitation

On a detected mismatch the runtime does window.location.href = errorReloadPath (guarded by sessionStorage) with no way for the app to know it's happening. Two real consequences we hit:

1. beforeunload guards fire on the framework's own recovery

Collaborative editors guard against losing unsynced changes:

window.addEventListener("beforeunload", (event) => {
  if (hasPendingCollabWrites()) event.preventDefault(); // native "Leave site?" dialog
});

When the skew reload fires mid-session, the browser shows the native Leave site? dialog in the middle of the framework's automatic recovery. If the user cancels it:

• the reload is aborted, but the sessionStorage guard for that version is already armed, so subsequent mismatching fetches short-circuit into never-resolving promises — the app is permanently stale and hung, with no signal to anyone;
• the app cannot distinguish this reload from an ordinary navigation, so it can't suppress its own guard. There is no existing signal (event, flag, callback) that says "this unload is a version-skew recovery, let it through."

2. Session telemetry dies with the page

Error/analytics buffers flush on a best-effort pagehide, but a hard location.href assignment mid-fetch loses whatever context explains why the reload happened. We'd like to record "reloaded due to version skew, from version X" — today the only trace is a console warning.

The workaround we currently maintain

Wrapping the fetch passed to the RSC entry points and re-implementing detection + bounded recovery end-to-end (~400 lines per app: version header, mismatch classification, history-state loop guard, a window flag our collab provider's beforeunload guard checks, telemetry flush). It predates 8.3 — but 8.3's built-in can't replace it solely because there's no seam at the moment of recovery. We'd much rather delete our pipeline and keep the framework's.

Candidate shape (one option — genuinely open to different ones)

type unstable_OnVersionMismatch = (context: {
  reason: "route-discovery" | "navigation" | "server-action";
  currentVersion: string;
  reloadUrl: string;
}) => void | false | Promise<void | false>;

• Awaited immediately before the automatic reload. Apps flush telemetry / set an "expected reload" flag, return nothing, and the framework proceeds — byte-identical behavior when unregistered.
• return false = the app owns recovery: the runtime still refuses to apply the stale payload, but skips its own location.href. In that case the sessionStorage guard should arguably not be armed — otherwise the second mismatch for the same version short-circuits before the hook and later fetches hang silently. Pinning that interaction down is part of the design.
• Not invoked for the deferred eager-discovery case (no reload happens there today).

Open design points we'd like maintainer input on

1. Registration surface. An RSCHydratedRouter prop cannot reach the createCallServer path (it's wired via setServerCallback independently), so a prop-based API can't service server-action mismatches. A registration on the shared surface next to the existing router globals would cover all call sites — including, if desired, the non-RSC fog-of-war path. Alternatively RSC-scope it and drop "server-action".
2. Loop-guard semantics under app ownership (see above).
3. Whether this should wait for the broader clientVersion API to stabilize, and if so, what interim escape hatch you'd suggest for the beforeunload collision — that one bites today.

Related: while evaluating this we found that createCallServer applies action rerender payloads without a version check — filed separately as a straightforward coverage fix, since it adds no API surface: #15342

---

Written on behalf of agcty.

[PrithwishDas101]

I can see why this matters for collaborative apps. A reload that normally fixes a stale client could actually make things worse if the user has unsaved changes or the app needs to flush some telemetry first.

I like the idea of an optional callback, especially if the existing behavior stays exactly the same when no callback is registered.

One thing I'd be careful about is what happens if the callback throws, rejects, or never finishes. It probably shouldn't be possible for a failed callback to leave the app stuck with a stale client forever. Maybe the default reload could still happen after a bounded timeout, unless the app explicitly takes over recovery.

I'd also want the loop-guard behavior to be clearly defined when the app chooses to handle recovery itself. Otherwise, repeated mismatches could end up leaving requests hanging.

That seems like the main edge case to settle before deciding on the exact API shape.