Rolling out a service worker safely: scope, versioned caches, the waiting worker and a kill switch

Goal

Add offline caching to a site without the classic failure: a stale worker keeps serving old HTML and assets after a deploy, or a broken worker cannot be replaced because it serves its own script from cache.

Prerequisites

HTTPS (MDN: service workers run only on secure origins, with localhost allowed), a build that emits content-hashed asset file names, and the lifecycle as the MDN guide describes it: a new worker installs in the background, waits until no page still uses the old one, then activates; skipWaiting() and clients.claim() shortcut the wait.

Steps

1. Register from one place with an explicit scope (/ for the whole origin; the script must be served at or above that path unless the server sends Service-Worker-Allowed), and serve the worker script with Cache-Control: no-cache. Pass updateViaCache: "none" so the script and its imports bypass the HTTP cache when the browser checks for updates.
2. Name caches with a string that changes every build (static-<git-sha>); in activate, delete every cache whose name is not current, as in the guide's cache clean-up example, and only then clients.claim().
3. Pick a strategy per resource class: cache-first for hashed immutable assets; network-first with cache fallback for HTML navigations and API data; never cache-first for un-hashed HTML.
4. Precache only the app shell in install, and keep the list short: cache.addAll() rejects with a TypeError if any response is outside the 200 range, which fails the whole installation.
5. Decide how updates land. The default (activate when the last old tab closes) is safest for consistency. If you call skipWaiting(), show a "new version available, reload" prompt rather than letting a new worker serve new assets to old pages silently.
6. Build the kill switch before the first release: a worker version whose activate deletes all caches and calls self.registration.unregister(), and a documented way to deploy it in minutes.
7. Rehearse the update path on staging: deploy, reload twice, confirm the new version is active and old caches are gone; then deploy the kill switch and confirm the worker disappears.

Expected result

Every deploy replaces the caches within one update cycle, users never load a mix of old HTML and new assets, and a bad worker can be retired without waiting for cache expiry or user action.

Limits and test basis

Behaviour follows the cited MDN pages; browser update-check timing and storage eviction rules are not claimed. Offline writes (queued requests, background sync) are a separate design. Caching third-party origins adds opaque responses that cannot be inspected for errors.

A timeout on network-first navigations

Network-first falls back to the cache only when the request fails, and on a connection that is present but stalled the request does not fail until the browser's own timeout, so the user waits on a blank page while a cached copy exists. Bound the wait: start the network request, and if it has not answered within a short, documented time, respond with the cached HTML and let the fresh copy land on the next navigation (Workbox's NetworkFirst strategy exposes this as networkTimeoutSeconds). Pair it with navigation preload (registration.navigationPreload.enable()) so the network request starts in parallel with the worker's startup rather than after it. Hashed asset names keep the served HTML consistent with its own assets either way.