A service worker (SW) is a browser-managed JS worker that sits between your page and the network. It can intercept fetch requests and decide whether to serve from cache, the network, or generate a response.

What it enables

• Offline mode — serve cached HTML/assets when the network is down.
• Custom caching strategies beyond HTTP cache (e.g., stale-while-revalidate, cache-first for static, network-first for API).
• Background sync — queue mutations made offline; replay when network returns.
• Push notifications — receive server-sent pushes even when the tab is closed.
• Periodic background sync (limited support) — wake up periodically to refresh.
• Pre-cache the next likely navigation's assets.

Lifecycle

1. Register (from the page):

``js navigator.serviceWorker.register('/sw.js'); ``

1. Install event fires once per SW version. Use it to pre-cache static assets.
2. Activate event fires once the new SW takes control. Use it to clean up old caches.
3. Fetch events fire for every network request in scope.

A new SW deployment doesn't immediately replace the old one — by default the old SW keeps serving open tabs. self.skipWaiting() + clients.claim() force an immediate takeover (risky if old + new SW have different cache schemas).

Anatomy

// sw.js
const CACHE = 'v3-static';
const STATIC = ['/', '/styles.css', '/app.js', '/offline.html'];

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

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

self.addEventListener('fetch', e => {
  if (e.request.mode === 'navigate') {
    // Network-first for HTML
    e.respondWith(
      fetch(e.request).catch(() => caches.match('/offline.html'))
    );
    return;
  }
  // Cache-first for static assets
  e.respondWith(
    caches.match(e.request).then(hit => hit || fetch(e.request))
  );
});

Caching strategies

Constraints

• HTTPS required (except localhost).
• No DOM access — workers run in a separate global; communicate with pages via postMessage.
• Scope = the path of the SW file. /sw.js controls the whole origin; /app/sw.js only /app/*.
• One SW per scope at a time.
• Lifespan is browser-controlled — the SW gets killed when idle, woken on events.
• Storage quotas — Cache API uses origin storage; can be evicted under pressure.

Common pitfalls

• Cache invalidation: forgetting to bump the cache name on deploy → users stuck on old assets.
• SW serving an old HTML shell that loads new chunked JS that no longer exists → app breaks.
• Auth headers in cached requests — make sure SW caches don't leak across users.
• CORS in SW fetch — opaque responses can be cached but JS can't inspect them.
• Debugging — chrome://serviceworker-internals, DevTools → Application → Service Workers, Update on reload.

Libraries

Don't write SW from scratch. Use Workbox (Google) — battle-tested helpers for caching strategies, route matching, precache manifests, build-tool integrations. Next.js, Nuxt, Vite all have PWA plugins built on Workbox.

When you don't need a service worker

• App is online-only and has no offline use case.
• HTTP caching is sufficient (most sites).
• The SW complexity isn't worth the added deploy/debug overhead.

A service worker is power and footgun. Reach for it when offline, push, or aggressive custom caching are genuine product needs — not because PWAs are trendy.