Service Workers & PWA

Offline web apps, background sync, push notifications, and the Progressive Web App model.

What it is, in plain English: A Service Worker is a script that runs in the background, separate from your web page, acting as a programmable network proxy. It can intercept every network request your page makes and respond from cache — making your app work offline. Service Workers are the foundation of Progressive Web Apps (PWA): installable web apps that work offline, send push notifications, and feel like native apps.

Where this bites you

With the cache-first fetch handler above, once a file is in the cache, the cache wins: forever. Deploy a new app.js and every returning visitor keeps getting the old one, because the service worker answers before the network is ever asked. Nothing errors, and it usually looks fine on the developer's machine, where DevTools is often set to bypass the service worker.

// sw.js -- deployed with release 1
const CACHE = "my-app-v1";
// ... install caches "/app.js"; fetch answers from the cache first ...

// release 2 changes app.js -- but sw.js is left untouched
// app.js v1:  console.log("app v1");
// app.js v2:  console.log("app v2");

// returning visitor, reload after release 2:
// app v1
// reload again:
// app v1          <- the new app.js is never fetched

Making web apps work offline

A Service Worker is a script that sits between your web page and the network. It can catch network requests and serve cached responses — so your app works even when there's no internet connection. It also enables push notifications and background sync.

Browser support note: Service Workers require HTTPS (or localhost for development). They don't work on http:// pages in production.

Step 1 — Register the Service Worker

// In your main JavaScript file (app.js or index.js):
if ("serviceWorker" in navigator) {
  window.addEventListener("load", async () => {
    try {
      const reg = await navigator.serviceWorker.register("/sw.js");
      console.log("Service Worker registered:", reg.scope);
    } catch (error) {
      console.error("Registration failed:", error);
    }
  });
}

Step 2 — The Service Worker file (sw.js)

// sw.js — lives at the root of your site

const CACHE = "my-app-v1";
const ASSETS = ["/", "/index.html", "/style.css", "/app.js"];

// install event — cache core files when SW is first installed:
self.addEventListener("install", (event) => {
  event.waitUntil(
    caches.open(CACHE).then(cache => cache.addAll(ASSETS))
  );
  self.skipWaiting();  // activate immediately (don't wait for old SW)
});

// activate event — clean up old caches:
self.addEventListener("activate", (event) => {
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(
        keys.filter(key => key !== CACHE)
            .map(key  => caches.delete(key))
      )
    )
  );
  self.clients.claim();  // take control of open tabs immediately
});

// fetch event — intercept every network request:
self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches.match(event.request).then(cached => {
      if (cached) return cached;  // serve from cache
      return fetch(event.request); // fall back to network
    })
  );
});

The activate handler above already deletes old caches, but it only runs when a new sw.js is installed, and the browser only installs one when the file's bytes change. So change the cache name with every release; build tools such as Workbox do this for you with a content hash. Expect one extra load: the visit that discovers the new worker is still served by the old one, and the next visit gets the new files.

// sw.js -- release 2
const CACHE = "my-app-v2";   // new name every release: sw.js changes, so it reinstalls

// visit 1 after release 2:  app v1   (served by the old worker while the new one installs)
//                           caches: my-app-v1, my-app-v2
// visit 2:                  app v2   (the new worker is active; activate deleted my-app-v1)
//                           caches: my-app-v2

Step 3 — Web App Manifest (for installability)

// manifest.json — makes your app installable ("Add to home screen"):
{
  "name": "My App",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",   // hides the browser UI
  "background_color": "#ffffff",
  "theme_color": "#2563eb",
  "icons": [
    { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ]
}

// Link in index.html:
// <link rel="manifest" href="/manifest.json">

Try It Yourself

// Service Worker lifecycle — demonstrated in console (SW runs separately)
// In a real app, you register the SW from your main JS file

// REGISTRATION (in main.js / index.js):
async function registerSW() {
  if (!("serviceWorker" in navigator)) {
    console.log("Service Workers not supported");
    return;
  }

try {
    const registration = await navigator.serviceWorker.register("/sw.js", {
      scope: "/",  // which URLs the SW controls
    });

console.log("SW registered:", registration.scope);

registration.addEventListener("updatefound", () => {
      const newWorker = registration.installing;
      console.log("New SW installing...");

newWorker.addEventListener("statechange", () => {
        if (newWorker.state === "installed" && navigator.serviceWorker.controller) {
          console.log("Update available! Refresh to activate.");
          showUpdateBanner();
        }
      });
    });

} catch (error) {
    console.error("SW registration failed:", error);
  }
}

registerSW();

// Check SW status:
if (navigator.serviceWorker.controller) {
  console.log("Page is controlled by a SW");
  console.log("SW URL:", navigator.serviceWorker.controller.scriptURL);
}

// Listen for messages from the SW:
navigator.serviceWorker.addEventListener("message", (event) => {
  console.log("SW says:", event.data);
});

// THE SERVICE WORKER FILE (sw.js) would contain:
const SW_CODE = `
const CACHE_NAME = "v1";
const PRECACHE = ["/", "/index.html", "/style.css", "/app.js"];

// Install: cache essential files
self.addEventListener("install", (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then(cache => cache.addAll(PRECACHE))
  );
});

// Activate: clean up old caches
self.addEventListener("activate", (event) => {
  event.waitUntil(
    caches.keys().then(keys =>
      Promise.all(keys.filter(k => k !== CACHE_NAME).map(k => caches.delete(k)))
    )
  );
});

// Fetch: serve from cache, fall back to network
self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches.match(event.request).then(cached =>
      cached ?? fetch(event.request)
    )
  );
});
`;

console.log("Service Worker code preview (would live in sw.js):");
console.log(SW_CODE.slice(0, 200) + "...");

Caching strategies and push notifications

Caching strategies

// Cache-first: serve cached content, update in background
// Best for: static assets (JS, CSS, images)
async function cacheFirst(request) {
  const cached = await caches.match(request);
  if (cached) {
    // Background update (stale-while-revalidate pattern):
    fetch(request).then(resp => {
      caches.open(CACHE).then(c => c.put(request, resp));
    });
    return cached;
  }
  const response = await fetch(request);
  const cache = await caches.open(CACHE);
  cache.put(request, response.clone());
  return response;
}

// Network-first: try network, fall back to cache
// Best for: API responses, dynamic content
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 caches.match(request);  // offline fallback
  }
}

Push Notifications

// 1. Request permission:
const permission = await Notification.requestPermission();
if (permission !== "granted") return;

// 2. Subscribe to push (in main thread):
const reg = await navigator.serviceWorker.ready;
const sub = await reg.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: urlBase64ToUint8Array(PUBLIC_VAPID_KEY),
});
// Send 'sub' to your server — it uses it to send pushes

// 3. Handle push in Service Worker (sw.js):
self.addEventListener("push", (event) => {
  const data = event.data.json();
  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body,
      icon: "/icon-192.png",
      data: { url: data.url },
    })
  );
});

// 4. Handle notification click (sw.js):
self.addEventListener("notificationclick", (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url));
});

Workbox and SW spec internals

Workbox — the production-ready SW toolkit

// Writing SW caching strategies from scratch is error-prone.
// Workbox (by Google) provides battle-tested implementations:
import { precacheAndRoute } from "workbox-precaching";
import { registerRoute }    from "workbox-routing";
import { CacheFirst, NetworkFirst, StaleWhileRevalidate } from "workbox-strategies";
import { ExpirationPlugin } from "workbox-expiration";

// Precache assets (generated by build tool — Vite, webpack):
precacheAndRoute(self.__WB_MANIFEST);

// Cache API responses (network-first, 24h expiry):
registerRoute(
  ({ url }) => url.pathname.startsWith("/api/"),
  new NetworkFirst({
    cacheName: "api-cache",
    plugins: [new ExpirationPlugin({ maxAgeSeconds: 24 * 60 * 60 })],
  })
);

// Cache images (cache-first, 30 days):
registerRoute(
  ({ request }) => request.destination === "image",
  new CacheFirst({
    cacheName: "images",
    plugins: [new ExpirationPlugin({ maxEntries: 60, maxAgeSeconds: 30 * 24 * 60 * 60 })],
  })
);

Service Worker spec — W3C Service Workers

Service Workers are a subset of Web Workers with a distinct lifecycle (install → activate → fetch). They operate at the registration scope level — a registered SW controls all pages under its scope. The skipWaiting() / clients.claim() pair is critical for immediate activation: without skipWaiting, a new SW waits for all controlled tabs to close before activating (ensuring consistency). The Cache Storage API (defined in the same W3C Service Workers spec) provides the underlying persistent URL-to-Response mapping.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.