Skip to content
orbitpush

Version skew

Why a page still open on the previous build can break after a deploy, and which old files orbitpush keeps so it does not.

A deploy replaces the site, but not the pages people already have open. A tab loaded before the deploy, or an installed PWA, keeps running the JavaScript of the previous build. That mismatch between the code running in the browser and the files on the server is version skew.

What breaks

Most build tools split an app into chunks with hashed names and load a chunk when the visitor first needs it. When a visitor on the previous build opens a route that has its own chunk, the old code asks for it under its old name, such as /assets/Settings-B3x9k.js. The new build calls it /assets/Settings-D8f2a.js. If the old file is gone, the request returns 404 and the page breaks with an error such as Failed to fetch dynamically imported module, until the visitor reloads.

The same happens to a stylesheet, a WebAssembly module, route data or a font that the old code loads after the page is open.

What orbitpush keeps

orbitpush keeps the files an open page of the previous build can still request: .js, .mjs, .css, .wasm, .json, fonts (.woff2, .woff, .ttf, .otf) and source maps (.map). The old code finds its chunks, and the visitor moves to the new version on the next reload.

A later deploy deletes these files once they have been out of the build for 7 days. Only a deploy deletes files: nothing runs on a timer.

What goes right away

Every other file that leaves the build is deleted on the deploy that drops it. An open page does not need the previous build’s HTML, so a removed page stops being served right away, and so does a PDF or an image you removed, also one published by mistake.

If the output directory has no index.html, which usually means the wrong or an empty directory, deploy warns and deletes no stale file before its 7 days, so a mistake does not take the site down.

The stale record

The date each kept file left the build is stored in /.orbitpush/stale.json in the storage zone. The pull zone serves it publicly like every other file there, and it lists only paths the site already served. If you delete it, the next deploy treats every kept file as stale from then on.

.orbitpush/ in the storage zone belongs to orbitpush. deploy skips files under .orbitpush/ in the output directory, with a warning.