How it works
The Service Workers spec runs register, update and unregister as jobs queued per scope, so calls never interleave. A registration holds up to three workers in installing, waiting and active.
The Update algorithm fetches the script with a Service-Worker: script header. Unless updateViaCache is 'all', the request uses cache mode no-cache; a registration is stale when its last update check was more than 86,400 seconds ago, and a stale one also gets no-cache. The fetched body is compared byte for byte with the stored one. If it's unchanged, scripts the worker loaded with importScripts() are fetched and compared too; they may come from the HTTP cache unless updateViaCache is 'none'. No difference, no new worker.
Install runs the new worker, fires install, and waits for every waitUntil() promise. On success the worker moves to waiting, and Try Activate runs. It activates the waiting worker when there's no active worker, or when the active one has no pending events and either no client uses the registration or the waiting one set its skip waiting flag. Try Activate runs again when the last client unloads and when skipWaiting() is called.
Activate moves the worker to active, makes it the controller of every client the old one controlled (firing controllerchange there), then fires activate. A client's controller is otherwise chosen once, when it's created: the navigation that loads a page picks the registration's active worker.
waitUntil() and respondWith() need an active event. In both browsers:
addEventListener('install', async (event) => {
await null; // a microtask: still inside dispatch
event.waitUntil(Promise.resolve()); // allowed
await new Promise((r) => setTimeout(r, 0)); // a task later: dispatch has ended
event.waitUntil(Promise.resolve()); // throws InvalidStateError
});
Microtasks run before the event finishes dispatching, so an await on an already-settled promise still counts as synchronous here; await fetch(...) doesn't. The same held for respondWith(). Call them first and do the async work inside the promise you pass.
Edge cases
Driven with Puppeteer against http://localhost, fresh profile per run; Chrome 156 and Firefox 159 agreed on every row.
Real-world scenario
A versioned precache that cleans up only once the new version has taken over:
const CACHE = 'static-v2';
const ASSETS = ['/', '/app.js', '/app.css'];
addEventListener('install', (event) => {
event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(ASSETS)));
});
addEventListener('activate', (event) => {
event.waitUntil(
caches.keys().then((keys) =>
Promise.all(keys.filter((key) => key !== CACHE).map((key) => caches.delete(key))),
),
);
});
While v2 waits, both static-v1 and static-v2 exist, so v1 pages keep working. After activation only static-v2 remained, in both browsers. Deleting in install instead would break v1 pages that are still open.
Trade-offs
- Wait (the default) is always safe: one tab never runs two versions. The cost is that a user who keeps a tab open for days stays on the old version.
skipWaiting() on every install gets fixes out immediately, but open pages run against a worker they weren't built for. It's fine when the worker only does network-first caching and never deletes what old pages need.
- Prompt, then skip combines both: the page decides when to switch and reloads right after.
clients.claim() helps when the worker should control the first visit, for example to cache its requests. Without it, the first page's requests bypass the worker.