Design for Version Skew Between Client and Server

Systems & Architecture · deployment, errors, trust

Updated 2026-08-04

Expect old interface code to keep running against a new backend. A blue-green or canary deploy switches the server while the browser keeps the build it already downloaded, and a cached script can serve that build for as long as the cache allows.
Treat the long-lived tab as the normal case, not the rare one. Dashboards, editors, and admin tools stay open for days, which is many deploys.
Recognize the symptoms, because they never look like a deploy problem:

Detect the mismatch and say so. A quiet A new version is available. Reload to continue. is the entire fix, and it has to be non-destructive to unsaved work.
Force the reload only where a stale client is dangerous. Reading a slightly old list is fine, and submitting a payment from a build that no longer matches the API is not.
Save first, reload second. An update prompt that discards a half-written document is worse than the skew it was preventing.
Stamp the build into the interface somewhere findable. Support cannot resolve "it works for me" without knowing which two versions were talking.
Keep the old contract alive for as long as old clients exist. The interface cannot fix a server that stopped accepting yesterday's request shape.

Deploys are continuous and browser tabs are not, so at any moment several versions of your interface are live at once.