Skip to content

Update strategies

Published

A service worker update can wait for open pages to close, take over immediately, or activate when the user accepts an “update available” notice and reloads. Choose when the new version should reach users and implement that choice in the page and worker code. The service worker update flow and skipWaiting explains skipWaiting(), clients.claim(), and the waiting state.

You need a registered worker whose script changes between deploys. The browser treats the worker as updated when the fetched script is byte-different from the one it holds, and it checks on navigation to an in-scope page, on push and sync events (unless a check ran within the previous 24 hours), and on register() when the script URL changed. Most browsers ignore HTTP caching headers for that check.

Without skipWaiting(), a newly installed worker waits until the old worker controls zero clients. This keeps a page on the worker version it loaded under, using the cache that matches its code. The cost is that a reload is not enough; during a refresh the old and new page overlap, so the old worker is still controlling a client, and the update applies only after the user closes or navigates away from every tab. Pick this when users close tabs within a day and a stale version for that long is acceptable.

// sw.js: nothing to add. The install handler only precaches.
self.addEventListener('install', (event) => {
event.waitUntil(caches.open('shell-v4').then((cache) => cache.addAll(['/', '/app.js'])));
});

self.skipWaiting() in install makes the new worker activate as soon as installation finishes, even while the old worker’s pages are open. Pair it with clients.claim() in activate when the first install should control pages that loaded without a worker. The new worker now answers fetches for HTML produced by an older version. A cache or schema change that is not backwards compatible will break those open pages. Use it for non-breaking fixes that should land at once.

sw.js
self.addEventListener('install', (event) => {
self.skipWaiting(); // the promise it returns can be ignored
event.waitUntil(caches.open('shell-v4').then((cache) => cache.addAll(['/', '/app.js'])));
});
self.addEventListener('activate', (event) => {
event.waitUntil(self.clients.claim());
});

The middle path installs the new worker, lets it wait, tells the user, and calls skipWaiting() only when they accept, followed by one controlled reload. It avoids both the silent inconsistency of unconditional skipWaiting() and the “update does not apply” cost of the default. The worker listens for a message; the page watches the registration for a waiting worker and reloads once on controllerchange.

sw.js
self.addEventListener('message', (event) => {
if (event.data && event.data.type === 'SKIP_WAITING') self.skipWaiting();
});
// page
const registration = await navigator.serviceWorker.register('/sw.js');
function offerUpdate(worker) {
const banner = document.querySelector('#update-banner');
banner.hidden = false;
banner.querySelector('button').onclick = () => worker.postMessage({ type: 'SKIP_WAITING' });
}
if (registration.waiting) offerUpdate(registration.waiting);
registration.addEventListener('updatefound', () => {
const installing = registration.installing;
installing.addEventListener('statechange', () => {
if (installing.state === 'installed' && navigator.serviceWorker.controller) offerUpdate(installing);
});
});
let refreshing = false;
navigator.serviceWorker.addEventListener('controllerchange', () => {
if (refreshing) return;
refreshing = true;
location.reload();
});

The navigator.serviceWorker.controller check skips the banner on the very first install, when there is no old worker to replace.

A tab left open for days does not navigate, so it does not trigger the browser’s check. registration.update() fetches the script and installs it if it differs, bypassing the HTTP cache when the previous fetch is older than 24 hours. An hourly call keeps a kiosk or dashboard within an hour of the latest deploy at the cost of one small request per hour.

navigator.serviceWorker.register('/sw.js').then((registration) => {
setInterval(() => registration.update(), 60 * 60 * 1000);
});
Situation Strategy What it costs
Users close or navigate away from tabs daily Waiting default Update lands only after the last tab closes
Tabs stay open for hours or days Default plus hourly registration.update() One extra request per hour per tab
Release changes cache layout or IndexedDB schema Default or user-prompted reload A banner to design and a reload the user must accept
Non-breaking fix that should apply at once skipWaiting() in install New worker answers pages built by the old version

Deploy a byte-changed sw.js, open the app in two tabs, and watch the chosen behaviour in the Service workers pane: the default shows waiting to activate until both tabs close; skipWaiting() shows the new worker activated and is running on the next reload; the prompted flow shows the banner, then the reload.

← Back to the Guides overview.