Service workers & offline apps

A tiny server in the browser

A service worker is a JavaScript file the browser can run between pages in its scope and the network. It can intercept requests, answer from cache, fall back to a saved offline page, receive push events, and retry queued work later.

You have seen fetch, promises, IndexedDB, and the Cache API. A service worker combines those ideas into a request router that can keep an app useful when the network is unreliable.

Real apps register a worker from page code. The worker then moves through installing, installed/waiting, activating, and activated. A new version usually waits until pages using the old version close.

1register("/sw.js")2install event: precache files3activate event: cleanup old caches4// Later: /sw.js changes on the server5new worker installs6new worker waits while old tabs are open7skipWaiting(); // optional immediate handoff8clients.claim(); // optional control for open pages

Service workers require HTTPS, except on localhost for development. The default scope is the script’s directory: /app/sw.js controls /app/ by default. Browsers check for updates on navigation to a controlled page and periodically, at least about every 24 hours.

1if ("serviceWorker" in navigator && isSecureContext) {2  const registration = await navigator.serviceWorker.register("/sw.js", {3    scope: "/app/",4  });5 6  registration.addEventListener("updatefound", () => {7    const next = registration.installing;8    next?.addEventListener("statechange", () => {9      if (next.state === "installed" && navigator.serviceWorker.controller) {10        showUpdateReadyMessage();11      }12    });13  });14}

Once active and controlling a page, the worker receives fetch events for requests in scope. The key rule is precise: event.respondWith() must be called synchronously inside the handler. The promise you pass can do asynchronous cache and network work afterward.

1self.addEventListener("fetch", (event) => {Run2  const request = event.request;3 4  if (request.mode === "navigate") {5    event.respondWith(networkFirst(request, "/offline.html"));6    return;7  }8 9  if (request.destination === "style" || request.destination === "script") {10    event.respondWith(cacheFirst(request));11    return;12  }13 14  event.respondWith(staleWhileRevalidate(request));15});

1self.addEventListener("fetch", (event) => {2  const request = event.request;3 4  if (request.mode === "navigate") {5    event.respondWith(networkFirst(request, "/offline.html"));6    return;7  }8 9  if (request.destination === "style" || request.destination === "script") {10    event.respondWith(cacheFirst(request));11    return;12  }13 14  event.respondWith(staleWhileRevalidate(request));15});

Notice the early return after each respondWith(). A request gets one response decision. Also notice what is missing: there is no document, no DOM, and no React state inside the worker.

Offline fallbacks

Offline support should feel intentional. Precache a small app shell and a clear /offline.html page during install. During activate, delete old cache names so old files do not pile up forever. During fetch, send navigation requests through network-first and fall back to the offline page only when necessary.

1const STATIC_CACHE = "app-shell-v3";2const OLD_CACHES = ["app-shell-v1", "app-shell-v2"];3 4self.addEventListener("install", (event) => {5  event.waitUntil(6    caches.open(STATIC_CACHE).then((cache) =>7      cache.addAll(["/", "/styles.css", "/offline.html"]),8    ),9  );10});11 12self.addEventListener("activate", (event) => {13  event.waitUntil(14    Promise.all(OLD_CACHES.map((name) => caches.delete(name))).then(() =>15      self.clients.claim(),16    ),17  );18});

Push & background sync

Push and sync are not magic background JavaScript. Push requires a server, VAPID keys, a subscription, notification permission, and userVisibleOnly. Background sync retries named work later, mainly in Chromium browsers, so feature detection and fallbacks still matter.

1self.addEventListener("push", (event) => {2  event.waitUntil(3    self.registration.showNotification("New message", {4      body: event.data?.text() ?? "Open the app to read it.",5    }),6  );7});8 9self.addEventListener("sync", (event) => {10  if (event.tag === "send-outbox") {11    event.waitUntil(sendQueuedMessagesFromIndexedDB());12  }13});

A common pattern is an outbox: save a draft message in IndexedDB, try sending it, and if the network fails, register a sync event named send-outbox. When sync fires, read IndexedDB and retry.

Where you’ll use this

Use service workers when the app has a useful offline shape: documentation, dashboards with cached data, installable PWAs, field tools, or forms that can queue work. Start small: cache the app shell, add an offline page, then choose strategies resource by resource.

• Version static assets and serve them cache-first.
• Use network-first for HTML and freshness-sensitive API data.
• Use stale-while-revalidate for images and content that can be briefly old.
• Keep payments, analytics, and permission checks network-only or explicitly queued.

Common misconceptions

• “A registered worker controls everything.” Scope limits control, and an active worker may not control already-open pages unless claimed.
• “Install means active.” A new worker can be installed and waiting.
• “I can call respondWith later.” The call must happen synchronously in the fetch handler.
• “Globals are safe storage.” The browser can stop the worker; use Cache API or IndexedDB.
• “Workers can update the DOM.” Service workers have no DOM. Send messages to pages or respond with different resources.

Key takeaways

• A service worker is a scoped request interceptor with an event-driven lifetime.
• Install prepares, waiting protects old tabs, activate cleans up, and control may need clients.claim().
• Pick strategies by freshness, safety, and offline usefulness.
• Call respondWith() synchronously, then let promises do asynchronous work.
• Push needs server infrastructure; background sync needs feature detection and durable queued data.

Up next: History & navigation.