Service workers

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 lifecycleThe states a service worker passes through from register() to redundant, the event at each transition, why a new version waits, and what skipWaiting() changes.

Service worker registration and scopeHow register() binds a script to a URL-prefix scope, how the default scope and Service-Worker-Allowed bound it, how overlaps resolve, and updateViaCache.

skipWaiting() and the update flowHow the browser detects a byte-different worker script, why the new worker waits, and what skipWaiting(), clients.claim(), update(), and updateViaCache change.

FetchEvent and request routingThe FetchEvent members for every in-scope request, the respondWith() and waitUntil() rules and their error outcomes, and routing by destination, mode, and URL.

Caching strategies for service workersWhat each of the five fetch-handler strategies (Cache First, Network First, Stale-While-Revalidate, Network Only, Cache Only) returns, what it costs, the response-cloning and opaque-response traps, and the Workbox equivalents.

Cache APIThe CacheStorage and Cache interfaces behind the caches global, their members, the TypeError and QuotaExceededError conditions on add(), addAll(), and put(), and the versioned-cache pattern for install and activate.

Clients APIThe Clients interface a service worker reaches as self.clients, its get(), matchAll(), openWindow(), and claim() members, the InvalidAccessError and InvalidStateError conditions, and the notification-click focus-or-open pattern.

NavigationPreloadManagerHow registration.navigationPreload lets the browser fetch a navigation in parallel with service worker start-up, the enable(), disable(), setHeaderValue(), and getState() members, the InvalidStateError and TypeError conditions, and how FetchEvent.preloadResponse and the Service-Worker-Navigation-Preload header fit together.

Offline fallback for service workersHow a service worker returns a precached page, image, or JSON body when a navigation or subresource request fails with nothing cached for its URL, which requests qualify, what Response.error() does, and the Workbox setCatchHandler equivalent.

Background Fetch APIHow BackgroundFetchManager.fetch() hands a large download to the browser, which shows progress and a cancel control and wakes the service worker with backgroundfetchsuccess, backgroundfetchfail, backgroundfetchabort, or backgroundfetchclick, with the exceptions and failure reasons.

Periodic Background Sync APIHow PeriodicSyncManager.register() asks the browser to fire a periodicsync event in an installed PWA's service worker no more often than minInterval, why Chrome gates it on installation and site engagement, and the exceptions and detection pattern.

WorkboxWhat the Workbox 7 packages do, how precacheAndRoute() and __WB_MANIFEST build versioned caches, when GenerateSW or InjectManifest applies, and page updates.

Debugging service workersWhere Chrome DevTools, Firefox DevTools, and Safari Web Inspector expose a service worker's state, how to force an update, bypass the worker, simulate offline, inspect Cache Storage, and read worker console output, with the exact panel labels.

Background Sync APIHow SyncManager.register() defers a failed request until connectivity returns and replays it in the sync event, with exceptions, retry limits, and detection.

Service Worker Static Routing APIHow addRoutes() in the install event sends matching requests to the network, a cache, or the fetch handler before a service worker starts, and when it rejects.

Removing a service worker safely (kill switch)What registration.unregister() removes, why already-controlled pages keep the old worker until they unload, and how a replacement worker clears its own caches.

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.