⚙️ Service Workers Implementation

What Is a Service Worker?

A service worker is a JavaScript file that runs on its own thread, separate from your pages, and sits between the app and the network as a programmable proxy. Every request a controlled page makes can pass through the worker's fetch handler, which decides whether to answer from a cache, hit the network, or synthesize a response.

💡 A useful analogy: Think of a service worker as a mail-room clerk between your office (the page) and the outside world (the network). The clerk can hand you a copy from the filing cabinet (cache) instantly, go out to fetch fresh mail when needed, and hold onto your outgoing letters until the road reopens. You never talk to the outside directly — the clerk mediates.

The Lifecycle

A service worker moves through a well-defined lifecycle. Understanding it prevents the two classic bugs: stale caches that never update, and a new worker that "won't take control."

Registration (from a page)

Registration happens in your page code, not the worker itself. Feature-detect, then register after load so it doesn't compete with critical resources:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', async () => {
    try {
      const reg = await navigator.serviceWorker.register('/sw.js');
      console.log('SW registered, scope:', reg.scope);
    } catch (err) {
      console.error('SW registration failed:', err);
    }
  });
}

Install — precache the shell

The install event fires once per worker version. Use it to open a cache and store the app shell. event.waitUntil() keeps the worker in installing until the promise settles, so a half-filled cache is never considered ready.

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

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE).then((cache) => cache.addAll(SHELL))
  );
  self.skipWaiting(); // activate this version immediately (see "Updating" below)
});

Activate — clean up old caches

Once a new worker activates, delete caches from previous versions so users don't accumulate stale copies. clients.claim() lets the new worker control already-open pages without a reload.

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

Fetch — intercept requests

The fetch event fires for every request from a controlled page. Call event.respondWith() with a Response (or a promise for one). The strategy you choose here is the heart of the worker — the next section covers the options.

The Cache API & the App Shell

The Cache API (caches) is a promise-based store that maps Request objects to Response objects. It's separate from the HTTP cache and fully under your control.

const cache = await caches.open('shell-v1');

await cache.addAll(['/', '/styles/main.css']); // fetch + store in one call
await cache.put(request, response.clone());     // store a response you already have
const hit = await cache.match(request);          // undefined on a miss
await cache.delete(request);                      // remove one entry
await caches.delete('shell-v0');                  // drop an entire cache

const response = await fetch(request);
cache.put(request, response.clone()); // store the copy
return response;                       // return the original

The Five Caching Strategies

There is no single "correct" strategy — you pick one per kind of resource based on how fresh it must be versus how fast it should load.

Cache first

async function cacheFirst(request) {
  const cached = await caches.match(request);
  if (cached) return cached;
  const response = await fetch(request);
  const cache = await caches.open(CACHE);
  cache.put(request, response.clone());
  return response;
}

Network first

async function networkFirst(request) {
  try {
    const response = await fetch(request);
    const cache = await caches.open(CACHE);
    cache.put(request, response.clone());
    return response;
  } catch {
    return (await caches.match(request)) ?? caches.match('/offline.html');
  }
}

Stale-while-revalidate

async function staleWhileRevalidate(request) {
  const cache = await caches.open(CACHE);
  const cached = await cache.match(request);
  const network = fetch(request).then((response) => {
    cache.put(request, response.clone()); // refresh for next time
    return response;
  });
  return cached ?? network; // instant if cached, otherwise wait for network
}

Routing Requests to Strategies

A real worker inspects each request and dispatches it to the right strategy. Here's a realistic e-commerce example inside one fetch handler:

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

  // Never cache non-GET or cross-origin API writes.
  if (request.method !== 'GET') return; // let the browser handle it

  // Static assets → cache first
  if (['/styles/', '/scripts/', '/images/', '/fonts/'].some((p) => url.pathname.startsWith(p))) {
    event.respondWith(cacheFirst(request));
    return;
  }

  // Product data that changes → network first
  if (url.pathname.startsWith('/api/products')) {
    event.respondWith(networkFirst(request));
    return;
  }

  // Checkout & cart → always fresh
  if (url.pathname.startsWith('/checkout') || url.pathname.startsWith('/cart')) {
    event.respondWith(fetch(request));
    return;
  }

  // Everything else → stale-while-revalidate
  event.respondWith(staleWhileRevalidate(request));
});

Background Sync & Push

Background sync — don't lose the user's action

When a write fails because the user is offline, queue it in IndexedDB and register a sync tag. The browser fires a sync event once connectivity returns — even if the page has since closed.

// In the page: try to send; on failure, register a sync.
async function sendMessage(message) {
  try {
    await fetch('/api/messages', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(message)
    });
  } catch {
    await saveToOutbox(message);            // store in IndexedDB
    const reg = await navigator.serviceWorker.ready;
    await reg.sync.register('outbox-sync'); // retry later
  }
}

// In the service worker: drain the outbox when online.
self.addEventListener('sync', (event) => {
  if (event.tag !== 'outbox-sync') return;
  event.waitUntil((async () => {
    for (const msg of await readOutbox()) {
      const res = await fetch('/api/messages', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(msg)
      });
      if (res.ok) await removeFromOutbox(msg.id);
    }
  })());
});

Push notifications

Push lets your server wake the worker to show a notification while the app is closed. The user must grant permission, and you subscribe with a VAPID public key:

// In the page: subscribe after permission is granted.
async function subscribeToPush() {
  const permission = await Notification.requestPermission();
  if (permission !== 'granted') return;

  const reg = await navigator.serviceWorker.ready;
  const subscription = await reg.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY)
  });
  await fetch('/api/subscriptions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(subscription)
  });
}

// In the service worker: show the notification, handle clicks.
self.addEventListener('push', (event) => {
  const data = event.data?.json() ?? {};
  event.waitUntil(
    self.registration.showNotification(data.title ?? 'Update', {
      body: data.body,
      icon: '/icons/icon-192.png',
      data: { url: data.url }
    })
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url ?? '/'));
});

Updating & Debugging

How updates work

When you deploy a byte-different sw.js, the browser installs the new version but keeps it waiting until every tab controlled by the old worker closes — so two versions never run at once. Calling self.skipWaiting() in install plus clients.claim() in activate promotes the new worker immediately. Because caches are keyed by name, bumping the version string is what triggers a real refresh:

const VERSION = 'v3';
const CACHE = `shell-${VERSION}`; // new name → activate cleans up shell-v2

Debugging in DevTools

• Application → Service Workers: tick Update on reload during development so you always run the latest file.
• Bypass for network: temporarily ignore the worker to compare against the live network.
• Application → Cache Storage: inspect exactly what's cached and clear it.
• Network → Offline: simulate no connection to test your fallbacks.

Hands-on Exercise

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

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

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

self.addEventListener('fetch', (event) => {
  const { request } = event;
  if (request.method !== 'GET') return;
  const url = new URL(request.url);

  if (url.pathname.startsWith('/api/')) {
    event.respondWith(
      fetch(request)
        .then((res) => {
          const copy = res.clone();
          caches.open(CACHE).then((c) => c.put(request, copy));
          return res;
        })
        .catch(() => caches.match(request))
    );
    return;
  }

  event.respondWith(
    caches.match(request).then((cached) =>
      cached ??
      fetch(request).catch(() =>
        request.mode === 'navigate' ? caches.match('/offline.html') : undefined
      )
    )
  );
});

Summary & Quiz

📚 Further Reading

• MDN — Service Worker API
• web.dev — Learn PWA: Service workers
• Workbox documentation
• web.dev — The Offline Cookbook

🚀 What's Next?

You can now cache and serve requests. The final piece is design: treating offline as the default rather than an error. Next we cover offline-first strategies — client storage, sync queues, and conflict resolution.