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.
Keep the waiting default
Section titled “Keep the waiting default”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'])));});Activate immediately with skipWaiting()
Section titled “Activate immediately with skipWaiting()”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.
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());});Let the user choose when to reload
Section titled “Let the user choose when to reload”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.
self.addEventListener('message', (event) => { if (event.data && event.data.type === 'SKIP_WAITING') self.skipWaiting();});// pageconst 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.
Check for updates in long-lived tabs
Section titled “Check for updates in long-lived tabs”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);});Match the strategy to the risk
Section titled “Match the strategy to the risk”| 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.
See also
Section titled “See also”- The service worker update flow and skipWaiting
- Service worker lifecycle: install to update
- Offline strategies
- The service worker lifecycle (web.dev)
- ServiceWorkerGlobalScope: skipWaiting() method (developer.mozilla.org)
- ServiceWorkerRegistration: update() method (developer.mozilla.org)
← Back to the Guides overview.