Service worker lifecycle and cache strategies

You deploy a new service worker, reload the page, and still get the old behaviour. No error — the new worker installed fine. It is just waiting for you to close every tab.

Registration and scope

navigator.serviceWorker.register('sw.js') starts the lifecycle. The scope defaults to the directory of sw.js — a worker at /app/sw.js controls all pages under /app/. You can narrow it: register('sw.js', { scope: '/app/checkout/' }).

A service worker has no DOM and no persistent global state — the browser kills and restarts it freely to save memory. All durable state lives in the Cache API or IndexedDB. It runs on its own thread, independent of any page — it can receive push notifications and run background sync even when no tab is open.

The lifecycle

register → install → [waiting] → activate → idle ↔ running

install — fires when the browser parses the new worker for the first time. This is where you pre-cache the app shell:

self.addEventListener('install', event => {
  event.waitUntil(
    caches.open('v1').then(cache => cache.addAll(['/app.js', '/index.html']))
  );
});

event.waitUntil(promise) tells the browser: do not advance the lifecycle until this promise settles. Forget it and the browser may kill the worker mid-cache-population.

waiting — a newly installed worker does not take control of already-open pages by default. It waits until every tab using the old worker closes. This prevents a page from running old HTML with new cached assets.

activate — fires after waiting. This is where you delete old caches:

self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(keys.filter(k => k !== 'v1').map(k => caches.delete(k)))
    )
  );
});

fetch — intercepts every network request in scope. event.respondWith(response) determines what the page receives.

skipWaiting + clients.claim()

To activate immediately without waiting for tabs to close:

// install handler
self.skipWaiting();

// activate handler
self.addEventListener('activate', event => {
  event.waitUntil(clients.claim());
});

skipWaiting() — new worker activates immediately, even with open pages. clients.claim() — new worker takes control of all open pages in its scope.

Use this deliberately. Without content-hashed asset filenames, skipWaiting is how you ship the version-mismatch failure mode.

Cache strategies

Inside the fetch handler you pick a strategy per request type:

Cache-first — check cache, fall back to network. Right for immutable, content-hashed static assets (app.4f3a1c.js):

event.respondWith(caches.match(event.request).then(r => r || fetch(event.request)));

Network-first — try network, fall back to cache on failure. Right for API responses that should be fresh but must degrade gracefully offline.

Stale-while-revalidate — serve the cached copy immediately, fetch a fresh copy in the background to update the cache for next time. Right for content that can be slightly stale (avatars, feeds).

Network-only and cache-only are the degenerate ends.

Libraries like Workbox give these strategies declaratively with route matching, but the strategies themselves are ten lines of fetch-handler code.