Service Workers

The problem

The HTTP cache (Experiment 06) is a set of rules you hand to the browser. A service worker is the opposite: a small program you write that sits between your pages and the network and decides, request by request, what to do. Answer from a cache. Go to the network. Do both. Show an offline page.

That makes it the most powerful caching tool on the web and one of the easiest to get wrong. It doesn’t make your site faster by itself. It lets you define what “faster” and “works offline” mean, and then it holds you to that choice, including after you deploy something new.

Things to try

1. “No service worker”. Offline is broken and the bad connection takes tens of seconds. This is your baseline.
2. “Cache-first everything”. Offline works and the bad connection is instant. After the deploy it’s stuck on the old version.
3. “Network-first everything”. Always fresh when you’re online, but look at the bad-connection visit. Drag the timeout to 0 and watch it get worse.
4. Mixed versions. Set documents to network-first and assets to cache-first with fingerprinting off. The new HTML talks to the old JavaScript.
5. “Sensible mix”. Tick fingerprinting off and on to see what it buys.
6. “Stale-while-revalidate”. Instant everywhere, always one visit behind, and the bytes add up.

What a service worker is

• A JavaScript file you register from a page. It runs off the main thread, has no access to the DOM, and wakes up to handle events such as install, activate and fetch.
• It works only over HTTPS (and on localhost for development), and only controls pages inside its scope, by default the folder it is served from.
• The page that first registers it isn’t controlled by it. The worker takes over from the next navigation, unless it calls clients.claim(). That’s why the second visit in the widget still uses the network when nothing was precached.
• Its fetch handler sees every request the controlled page makes, and can answer from anywhere.

// in the page
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
}

The strategies

Network only

Don’t touch it. Right for requests that must never be cached, such as payments or anything personalised and security-sensitive.

Cache first

Instant and works offline. Right for files that never change at their URL, such as fingerprinted assets. Wrong for anything that changes in place: it will never ask again.

Network first

Fresh when you’re online, with the cache as a safety net. Right for documents and data. The cost is waiting on the network before you fall back, so add a timeout.

Stale-while-revalidate

Answer from the cache immediately and refresh it in the background. Right when slightly old is fine. The visitor is always one version behind, and every visit downloads again.

Use a different strategy for different content. Documents and API data want freshness. Fingerprinted assets are immutable, so serve them from the cache. That combination is the “sensible mix” preset.

Precache and runtime cache

Precaching downloads the app shell at install, so the second visit already works offline. Runtime caching stores things as they’re requested. Precache what the whole site needs, and runtime-cache the rest.

One more cost to know about: a worker that isn’t running has to start before it can answer a navigation, which can add delay. Navigation preload lets the browser start the network request while the worker boots.

A sketch of the whole thing (real projects usually use a library such as Workbox rather than hand-rolling it):

const VERSION = 'v5';
const SHELL = ['/', '/styles.3f9a1c.css', '/app.8c2e77.js', '/offline.html'];

self.addEventListener('install', (event) => {
  event.waitUntil(caches.open(VERSION).then((c) => c.addAll(SHELL)));
});

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

self.addEventListener('fetch', (event) => {
  const req = event.request;
  if (req.method !== 'GET') return;
  if (req.mode === 'navigate') {
    // network first for documents, with an offline fallback
    event.respondWith(fetch(req).catch(() => caches.match('/offline.html')));
    return;
  }
  // cache first for fingerprinted assets
  event.respondWith(caches.match(req).then((hit) => hit ?? fetch(req)));
});

The update lifecycle

1. The browser re-fetches sw.js on navigations (and at least daily). If it differs by even one byte, it installs it as a new worker.
2. The new worker runs install, usually precaching new files. The old worker keeps serving.
3. The new worker waits. It becomes active only when no page is controlled by the old worker, which means every tab closed. A reload isn’t enough, because the reloaded page is itself controlled by the old worker.
4. On activate the new worker deletes caches the old version left behind.

skipWaiting() and clients.claim() shorten this, at a cost: you can end up with an old page running under a new worker, and a new worker may have deleted files the old page still needs. They’re safe only when each release is backwards compatible with the one before.

Two rules of thumb: version your caches so activation can clean up, and serve sw.js with no-cache. Modern browsers already skip the HTTP cache when they check the main worker file, but scripts it imports can still be cached, so don’t rely on the default.

Common misconceptions

Other things that bite

• Only cache what you mean to. Cache successful (200) responses, not errors, and be careful with personalised pages and anything behind a login.
• Caches grow. Browsers cap storage and may evict it under pressure. Don’t assume something you cached is still there.
• Third-party responses can be “opaque”: you can store them but not inspect them, including whether they succeeded.
• It adds a layer to debug. A bug that “fixes itself in a private window” is often a worker.

See it on a real page

1. In DevTools open Application, then Service workers. You’ll see its status (activated, waiting), and the checkboxes Update on reload, Bypass for network and Offline. “Update on reload” is for development: it hides the waiting problem that your users will have.
2. Open Cache storage to see exactly what the worker has stored, and delete it to reset.
3. In Network, the Size column shows (ServiceWorker) for responses the worker answered.
4. Test the offline and bad-connection cases for real, using the throttling and Offline controls, because that’s the situation you built this for.

Model assumptions