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.

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
    })
  );
});

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 — HTML Standard §10.2

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 (WHATWG Cache §§) 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.