⚙️ Service Workers Setup

What a Service Worker Is

A service worker is a JavaScript file the browser runs in the background, completely separate from any web page. It is a specialized kind of web worker with three defining traits you must keep in mind:

• Separate thread. It runs off the main thread, so its work never blocks your UI. It also keeps running after the user navigates away, and the browser may stop and restart it to save memory.
• No DOM access. It cannot touch document or window. It talks to pages through postMessage, not by reading the DOM. Its global object is self.
• Event-driven & promise-based. It wakes up to handle events — install, activate, fetch, push, sync — and nearly every API it uses returns a Promise.

Remember the rules from the last lesson: a service worker only runs over HTTPS (or localhost), and it can only control pages within its scope.

Registering One

Registration happens in your page code, not in the service worker itself. Always feature-detect first, and register after the page loads so the service worker never competes with the initial render for bandwidth.

// In your main app script (e.g. /js/app.js)
if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker
      .register('/service-worker.js')
      .then((registration) => {
        console.log('SW registered. Scope:', registration.scope);
      })
      .catch((error) => {
        console.error('SW registration failed:', error);
      });
  });
}

Scope: where the file lives matters

A service worker can only intercept requests for pages at or below its own location. A worker at /service-worker.js controls the whole site; one at /app/service-worker.js controls only /app/ and below. This is why the file almost always lives at the site root.

// You can narrow the scope, but never widen it beyond the file's folder:
navigator.serviceWorker.register('/service-worker.js', {
  scope: '/',        // control the entire origin
  type: 'module'     // opt in to ES modules inside the worker (import/export)
});

The Lifecycle

Once registered, a service worker moves through a well-defined lifecycle. Understanding it is the single most important thing in this lesson, because almost every confusing service-worker bug is really a lifecycle misunderstanding.

1. Installing. Fires once, right after registration. This is where you precache the app shell.
2. Installed / Waiting. If an older worker still controls open pages, the new one waits. It will not take over until every tab using the old version is closed — unless you call skipWaiting().
3. Activating. Fires when the worker takes control. This is where you delete outdated caches.
4. Activated & idle. The worker now handles fetch and other events. When there's nothing to do, the browser may terminate it and restart it on the next event — which is why you never store important state in a plain variable.

Install: Precache the Shell

The app shell is the minimal HTML, CSS, and JavaScript that renders your app's user interface — the frame the content later drops into. Caching it during install means every future visit paints instantly, online or off.

Use event.waitUntil() to tell the browser "don't consider me installed until this Promise resolves." Inside it, open a versioned cache and add every shell asset with cache.addAll().

// service-worker.js
const CACHE_VERSION = 'v1';
const CACHE_NAME = `app-shell-${CACHE_VERSION}`;

// The app shell: the bare minimum the UI needs to render.
const APP_SHELL = [
  '/',
  '/index.html',
  '/styles/main.css',
  '/js/app.js',
  '/offline.html',
  '/icons/icon-192.png'
];

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => {
      console.log('Precaching app shell');
      return cache.addAll(APP_SHELL);
    })
  );
});

Why version the cache name?

Baking a version into the cache name (app-shell-v1) means that when you ship new code and bump to v2, the new worker fills a brand-new cache while the old one keeps serving open pages. Nothing breaks mid-update, and cleanup becomes trivial — which is exactly what activate handles next.

Activate: Clean Up Caches

Caches never expire on their own — you have to delete them. The activate event is the safe moment to do it, because by now the new worker is taking control and the old caches are no longer needed. Walk every cache name and delete the ones that aren't the current version.

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames
          // keep the current cache, delete every older app-shell cache
          .filter((name) => name.startsWith('app-shell-') && name !== CACHE_NAME)
          .map((name) => {
            console.log('Deleting old cache:', name);
            return caches.delete(name);
          })
      );
    })
  );
});

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

Fetch: Intercept Requests

The fetch event is where the magic happens. It fires for every network request the page makes within scope — pages, stylesheets, scripts, images, API calls. Call event.respondWith() with a Promise that resolves to a Response, and you have taken full control of that request.

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cachedResponse) => {
      // Serve from cache if we have it, otherwise hit the network.
      return cachedResponse || fetch(event.request);
    })
  );
});

That tiny handler is a complete cache-first strategy. But real fetch handlers usually cache the network response for next time too — and that reveals a subtle rule.

Responses can only be read once

A Response body is a stream you can consume a single time. If you want to both return it to the page and store it in the cache, you must clone() it first.

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => {
      if (cached) return cached;

      return fetch(event.request).then((networkResponse) => {
        // Clone BEFORE the body is read, so we have two usable copies.
        const copy = networkResponse.clone();
        caches.open(CACHE_NAME).then((cache) => cache.put(event.request, copy));
        return networkResponse;
      });
    })
  );
});

Caching Strategies

A caching strategy is simply your policy for a given request: when do you trust the cache, and when do you trust the network? Different assets deserve different answers. Here are the three you'll reach for most.

Cache-first

Check the cache; only touch the network if it's a miss. Fastest possible response, ideal for static assets that rarely change — CSS, JS bundles, fonts, logos. The risk: users can get a stale asset until the cache is updated, so version your files or cache names.

function cacheFirst(request) {
  return caches.match(request).then((cached) => {
    if (cached) return cached;
    return fetch(request).then((response) => {
      const copy = response.clone();
      caches.open(CACHE_NAME).then((cache) => cache.put(request, copy));
      return response;
    });
  });
}

Network-first

Try the network; fall back to the cache if it fails. Best for content that should be as fresh as possible but is still worth showing stale when offline — HTML documents, news feeds, dashboards.

function networkFirst(request) {
  return fetch(request)
    .then((response) => {
      const copy = response.clone();
      caches.open(CACHE_NAME).then((cache) => cache.put(request, copy));
      return response;
    })
    .catch(() => caches.match(request)); // offline: serve last known copy
}

Stale-while-revalidate

Answer immediately from the cache, and simultaneously fetch a fresh copy in the background to update the cache for next time. The best of both worlds — instant response plus eventual freshness — for things where a slightly old version is fine right now: avatars, article bodies, non-critical feeds.

function staleWhileRevalidate(request) {
  return caches.open(CACHE_NAME).then((cache) => {
    return cache.match(request).then((cached) => {
      const networkFetch = fetch(request).then((response) => {
        cache.put(request, response.clone()); // refresh for next time
        return response;
      });
      // Return the cached copy now if we have one; otherwise wait for network.
      return cached || networkFetch;
    });
  });
}

Routing requests to strategies

In a real service worker you inspect each request and pick a strategy:

self.addEventListener('fetch', (event) => {
  const { request } = event;
  const url = new URL(request.url);

  // HTML navigations: network-first, fall back to offline page.
  if (request.mode === 'navigate') {
    event.respondWith(networkFirst(request).catch(() => caches.match('/offline.html')));
    return;
  }
  // Static assets: cache-first.
  if (['style', 'script', 'font'].includes(request.destination)) {
    event.respondWith(cacheFirst(request));
    return;
  }
  // Images and feeds: stale-while-revalidate.
  event.respondWith(staleWhileRevalidate(request));
});

Best Practices & Pitfalls

✅ Do

• Feature-detect with if ('serviceWorker' in navigator) before registering
• Give caches versioned names and delete old ones in activate
• Wrap install/activate work in event.waitUntil() so the browser waits for it
• Clone a response before caching and returning it
• Match the strategy to the asset: cache-first for static, network-first for fresh, stale-while-revalidate for the in-between
• Provide an /offline.html fallback for failed navigations

❌ Don't

• Don't store important state in module-level variables — the worker can be terminated and restarted at any time
• Don't try to widen scope beyond the worker's own directory
• Don't put user-specific or authenticated API responses in a shared cache-first cache
• Don't cache POST requests — the Cache API only stores GET responses
• Don't forget that cache.addAll() fails entirely if one URL 404s

Practice & Quiz

const CACHE = 'shell-v1';
const SHELL = ['/', '/index.html', '/styles/main.css', '/offline.html'];

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

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

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cached) => {
      return cached || fetch(event.request).catch(() => {
        if (event.request.mode === 'navigate') return caches.match('/offline.html');
      });
    })
  );
});

Summary

📚 Additional Resources

• MDN — Service Worker API
• MDN — Using Service Workers
• web.dev — Learn PWA: Service workers
• Chrome Developers — Workbox

🚀 What's Next?

Your service worker can now cache assets and survive a lost connection. But a truly resilient app does more than serve stale HTML — it stores data offline, queues user actions, and syncs them back when the network returns. The next lesson dives into that: Offline Functionality, covering offline fallback pages, IndexedDB for structured data, and the Background Sync API.