Service workers: what they are, and a minimal one

A service worker is a script the browser runs in its own worker thread, separate from any page, which can intercept network requests from the pages it controls and answer them itself. That is what makes offline support, instant repeat loads, and push possible: the worker keeps running after the tab is gone.

It has no DOM access, and it only runs in a secure context (HTTPS, or localhost during development).

The smallest one that works

Register it from the page:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js');
} else {
  // No service worker: the site still works, it just has no offline layer.
}

And in /sw.js, answer requests from a cache, falling back to the network:

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((hit) => hit || fetch(event.request)),
  );
});

That is a complete, working service worker. Everything else — precaching, update strategy, expiry — is refinement on top of these two pieces.

The lifecycle, in one pass

A registered worker is installed, then activated, and only then does it start controlling pages. A page loaded before the worker activated stays uncontrolled until it is reloaded. When you ship a new sw.js, the browser installs it alongside the old one and leaves it waiting until the old worker releases its clients — which is why a deploy does not take effect on the very next reload unless you ask it to.

See Service worker lifecycle and The update flow and skipWaiting.

Where it commonly goes wrong

• Scope — a worker at /js/sw.js controls only /js/. Serve it from the root, or send Service-Worker-Allowed. See Registration and scope.
• Stale users after a deploy — the new worker sits waiting behind the old one.
• Caching everything reflexively — a cache-first strategy on HTML strands users on an old page. Choose per request type: Caching strategies.
• Debugging it like page code — it has its own lifecycle and its own DevTools pane. See Debugging service workers.

Every topic in this section

Service worker lifecycleregister, install, activate, the waiting worker, skipWaiting, clients.claim, and updates.

Registration and scopenavigator.serviceWorker.register(), scope rules, Service-Worker-Allowed, and updateViaCache.

The update flow and skipWaitingHow the browser detects new versions, the waiting state, skipWaiting(), and clients.claim().

The fetch event and routingFetchEvent, event.respondWith(), routing by destination or URL, and passthrough.

Caching strategiesCache First, Network First, Stale-While-Revalidate, Network Only, Cache Only — when to use each.

The Cache APIcaches.open(), cache.add(), cache.match(), expiration, and opaque responses.

The Clients APIReaching the pages a worker controls — matchAll, claim, and focusing or opening a window.

Navigation preloadStarting the navigation request in parallel with worker startup so boot time is not on the critical path.

Offline fallbackPre-caching a fallback page and serving it when both cache and network fail.

Background FetchHanding long downloads to the browser so they survive the page being closed.

Periodic Background SyncRefreshing content on a browser-decided schedule, and the narrow support it has.

WorkboxRouting, precaching, expiration, background sync, and workbox-window for update UX.

Debugging service workersChrome DevTools, Firefox, and Safari tooling for inspecting state, caches, and update flow.

Background sync: retrying failed requestsHow the Background Sync API defers a failed request until the device regains connectivity, its registration/event API, and execution-time limits.

Where to go next

• Web app manifest — the other half of an installable app.
• Install prompt — what browsers require before offering installation.

← Back to the Reference overview.