Service Workers and Cache API

A senior-engineer reference for offline-first web architecture: how the Service Worker API (W3C Candidate Recommendation Draft, 9 April 2026 publication) intercepts network requests and runs background work, how the Cache API stores Request → Response pairs durably, and how the lifecycle model lets you ship updates without two tabs running incompatible code. These APIs are the substrate of Progressive Web Apps (PWAs): the worker decides where each response comes from, the Cache API persists those responses across browser restarts, and the activation rules guarantee a single controlling version per scope at any moment.

Abstract

Service workers represent a fundamental shift from traditional web architecture: instead of the browser directly fetching resources, an intermediary script can intercept every network request and programmatically decide how to respond.

Mental model:

• Service Worker acts as a programmable network proxy scoped to a path prefix—it intercepts fetch events for matching URLs and can respond from cache, network, or synthesized responses
• Cache API stores Request → Response mappings durably, surviving browser restarts—unlike HTTP cache, you control exactly what’s cached and for how long
• Lifecycle ensures only one service worker version is active per scope at any time, preventing the “two tabs running different code” problem that plagued AppCache

Critical design decisions:

• Event-driven with termination: The spec is explicit that “the lifetime of a service worker is tied to the execution lifetime of events” and that workers “may be started and killed many times a second”¹. In-memory globals don’t persist between events; use IndexedDB or Cache API for state.
• Waiting state by default: New workers wait until all clients using the old version close. This prevents mid-session version mismatches but means updates don’t apply immediately.
• Secure context required: Service workers can intercept any request in their scope, including credentials, so registration is restricted to secure contexts. HTTPS is required in production; http://localhost (and 127.0.0.1) is exempt for development.

Service Worker Lifecycle

The lifecycle is the most complex part of service workers—and the most important to understand. Unlike regular scripts that run when the page loads, service workers progress through distinct states independently of any document.

State Machine

Registration and Scope

Registration binds a worker script to a scope URL prefix:

Show 3 hidden lines4}56// Register with explicit scope7const registration = await navigator.serviceWorker.register("/sw.js", {8  scope: "/app/", // Controls /app/* URLs9})1011console.log("Scope:", registration.scope) // "https://example.com/app/"12console.log("Active:", registration.active?.state) // "activated" if ready13console.log("Waiting:", registration.waiting?.state) // Worker pending activation14console.log("Installing:", registration.installing?.state) // Currently installing1516// Default scope: directory containing the worker script17// /scripts/sw.js → scope defaults to /scripts/Show 2 hidden lines

Scope rules:

• A worker at /sw.js defaults to scope / (entire origin)
• A worker at /app/sw.js defaults to scope /app/
• Scope cannot exceed the worker’s directory unless the server sends Service-Worker-Allowed: / header
• Multiple registrations with different scopes can coexist; most-specific scope wins

Install Event: Precaching

The install event fires once per worker version. Use it to cache critical resources:

Show 2 hidden lines34self.addEventListener("install", (event) => {5  event.waitUntil(6    caches.open(CACHE_NAME).then((cache) => {7      // addAll is atomic—fails entirely if any resource fails8      return cache.addAll(["/", "/app.js", "/styles.css", "/offline.html"])9    }),10  )11})1213// ⚠️ addAll fetches with mode: 'cors' by default14// Cross-origin resources need proper CORS headers or use:15cache.add(new Request("https://cdn.example.com/lib.js", { mode: "no-cors" }))16// Warning: no-cors responses are "opaque"—you can't inspect status or headers

waitUntil() is critical: The install event would complete immediately without it, potentially activating before caching finishes. If the promise rejects, the worker transitions to redundant and is discarded — so a single broken precache URL kills the entire install.

Activate Event: Cleanup

The activate event fires when the worker takes control. Use it to clean old caches:

Show 3 hidden lines4self.addEventListener("activate", (event) => {5  const expectedNames = new Set(Object.values(CURRENT_CACHES))67  event.waitUntil(8    caches.keys().then((cacheNames) => {9      return Promise.all(10        cacheNames.map((name) => {11          if (!expectedNames.has(name)) {12            console.log("Deleting old cache:", name)13            return caches.delete(name)14          }15        }),16      )17    }),18  )19})

Why clean on activate, not install? The old worker may still be serving requests. Deleting its caches during install would break active clients.

skipWaiting and clients.claim

Two methods bypass the default waiting behavior:

1// In install event: skip waiting state entirely2self.addEventListener("install", (event) => {3  self.skipWaiting() // Activate immediately after install4  event.waitUntil(/* caching */)5})67// In activate event: take control of existing clients8self.addEventListener("activate", (event) => {9  event.waitUntil(10    clients.claim(), // Control pages that loaded before this worker11  )12})

When to use skipWaiting():

• Critical bug fixes that must deploy immediately
• The new version is backward-compatible with pages loaded under the old version

When to avoid it: The spec warns that with skipWaiting(), “new service worker is likely controlling pages that were loaded with an older version.” If your JavaScript expects cached assets that changed, you’ll get broken pages.

clients.claim() use case: First-time installations where pages loaded before registration should immediately get service worker control. Jake Archibald notes that he rarely uses it himself because “it only really matters on the very first load”².

Update Mechanism

Service workers update when:

1. Navigation to an in-scope page (if >24 hours since last check)
2. Functional events (push, sync) fire while the worker has not been update-checked in the last 24 hours
3. registration.update() called explicitly
4. Worker script URL changes (rare; avoid this pattern — it strands the old registration)

The browser fetches the worker script and compares bytes. Any difference triggers a new install. The 24-hour cap is normative: the registration is “stale” once 86400 seconds have passed since the last check, and the browser then bypasses the HTTP cache regardless of Cache-Control.

1// Trigger manual update check2const registration = await navigator.serviceWorker.ready3await registration.update()45// Monitor for updates6registration.addEventListener("updatefound", () => {7  const newWorker = registration.installing8  newWorker?.addEventListener("statechange", () => {9    if (newWorker.state === "installed") {10      // New version ready, waiting to activate11      if (registration.active) {12        // Show "Update available" UI13        showUpdateNotification()14      }15    }16  })17})

Cache API

The Cache API provides a durable Request → Response storage mechanism. Unlike HTTP cache, you have explicit control over what’s stored, how matching works, and when entries expire.

CacheStorage Interface

caches (global CacheStorage) manages named caches:

Cache Interface

Individual Cache objects store request/response pairs:

Show 2 hidden lines34// Add single resource (fetches and stores)5await cache.add("/api/config")67// Add multiple resources (atomic—all or nothing)8await cache.addAll(["/api/config", "/api/user"])910// Put explicit request/response pair11const response = await fetch("/api/data")12await cache.put("/api/data", response.clone()) // Must clone—body consumed1314// Match with options15const match = await cache.match(request, {16  ignoreSearch: true, // Ignore query string17  ignoreMethod: true, // Match regardless of HTTP method18  ignoreVary: true, // Ignore Vary header19})2021// List all cached requests22const keys = await cache.keys()2324// Delete specific entry25const deleted = await cache.delete("/api/old-endpoint")

Critical: Response bodies are single-use. After cache.put(req, response), the response body is consumed. Always response.clone() if you need to return the response to the page.

Request Matching

Cache matching is exact by default—URL, method, and Vary headers must match:

1// These are different cache entries:2cache.put("/api?page=1", response1)3cache.put("/api?page=2", response2)45// Match with query string6await cache.match("/api?page=1") // Returns response17await cache.match("/api?page=2") // Returns response28await cache.match("/api") // Returns undefined910// Ignore query string11await cache.match("/api?page=1", { ignoreSearch: true }) // Returns first match

Vary header behavior: If a cached response has Vary: Accept-Language, the cache only returns it when the request’s Accept-Language matches the original request’s value. Use ignoreVary: true to bypass this.

Storage Limits and Quotas

Cache storage counts against the origin’s quota:

Safari’s 7-day limit is the dominant operational concern for PWAs targeting iOS/macOS. The clock measures Safari browser use without a meaningful first-party interaction on your origin. Web apps added to the home screen run as standalone PWAs and are exempt; everything else loses its precache (and any IndexedDB-backed offline state) after a week.

Check quota with the Storage API:

1const estimate = await navigator.storage.estimate()2console.log(`Used: ${estimate.usage} bytes`)3console.log(`Quota: ${estimate.quota} bytes`)4console.log(`Available: ${((estimate.quota! - estimate.usage!) / 1024 / 1024).toFixed(1)} MB`)56// Request persistent storage (immune to automatic eviction)7const persistent = await navigator.storage.persist()8if (persistent) {9  console.log("Storage will not be evicted under pressure")10}

Caching Strategies

The fetch event is where caching strategies execute. Each strategy trades off freshness, speed, and offline capability. Pick one per resource class — not one per service worker:

Cache-First (Cache Falling Back to Network)

Return cached response immediately; fetch from network only if not cached:

1self.addEventListener("fetch", (event) => {2  event.respondWith(3    caches.match(event.request).then((cached) => {4      if (cached) return cached56      return fetch(event.request).then((response) => {7        // Optionally cache the new response8        if (response.ok) {9          const clone = response.clone()10          caches.open("dynamic").then((cache) => cache.put(event.request, clone))11        }12        return response13      })14    }),15  )16})

Use for: Static assets (CSS, JS, images) with versioned URLs (app.v2.js). Immutable once deployed.

Trade-off: Fast and offline-capable, but stale until cache is explicitly invalidated.

Network-First (Network Falling Back to Cache)

Try network first; fall back to cache if offline or request fails:

1self.addEventListener("fetch", (event) => {2  event.respondWith(3    fetch(event.request)4      .then((response) => {5        // Update cache with fresh response6        const clone = response.clone()7        caches.open("api").then((cache) => cache.put(event.request, clone))8        return response9      })10      .catch(() => {11        // Network failed—try cache12        return caches.match(event.request)13      }),14  )15})

Use for: API responses, user data, anything where freshness matters more than speed.

Trade-off: Always fresh when online, but slower (waits for network). Provides offline fallback.

Stale-While-Revalidate

Return cached response immediately, then fetch and update cache in background:

1self.addEventListener("fetch", (event) => {2  event.respondWith(3    caches.open("swr").then((cache) => {4      return cache.match(event.request).then((cached) => {5        // Always fetch to update cache6        const fetchPromise = fetch(event.request).then((response) => {7          cache.put(event.request, response.clone())8          return response9        })1011        // Return cached immediately, or wait for network if no cache12        return cached || fetchPromise13      })14    }),15  )16})

Use for: Frequently-updated content where slight staleness is acceptable (avatars, news feeds, product listings).

Trade-off: Fast response from cache, eventual freshness. Uses more bandwidth (always fetches).

Network-Only

Pass through to network without caching:

1self.addEventListener("fetch", (event) => {2  event.respondWith(fetch(event.request))3})

Use for: Non-cacheable requests (POST, real-time data, authenticated content with unique tokens).

Cache-Only

Only serve from cache; fail if not cached:

1self.addEventListener("fetch", (event) => {2  event.respondWith(caches.match(event.request))3})

Use for: Offline-only apps after initial precaching. Rarely used alone.

Strategy Selection by Resource Type

Navigation Preload

Navigation preload solves a performance problem: when a user navigates, the browser must start the service worker before dispatching the fetch event. This startup delay (50-500ms) adds latency to every page load.

Navigation preload starts the network request in parallel with worker startup:

Enabling Navigation Preload

1self.addEventListener("activate", (event) => {2  event.waitUntil(3    (async () => {4      if (self.registration.navigationPreload) {5        await self.registration.navigationPreload.enable()6      }7    })(),8  )9})

Using the Preloaded Response

1self.addEventListener("fetch", (event) => {2  if (event.request.mode === "navigate") {3    event.respondWith(4      (async () => {5        // Try cache first6        const cached = await caches.match(event.request)7        if (cached) return cached89        // Use preloaded response if available10        const preloaded = await event.preloadResponse11        if (preloaded) return preloaded1213        // Fallback to regular fetch14        return fetch(event.request)15      })(),16    )17  }18})

Server-Side Detection

Navigation preload requests include the Service-Worker-Navigation-Preload header (default value: true). Servers can customize responses:

1// Set custom header value2await registration.navigationPreload.setHeaderValue("v2")3// Server receives: Service-Worker-Navigation-Preload: v245// Check current state6const state = await registration.navigationPreload.getState()7// { enabled: true, headerValue: "v2" }

Server optimization: Return minimal content (header + footer) for preload, let the service worker merge with cached content.

Important: If your response differs based on this header, include Vary: Service-Worker-Navigation-Preload to prevent caching issues.

Update Flows and Client Coordination

Managing updates is where service workers get tricky. The default behavior—waiting until all clients close—is safest but frustrating for users who keep tabs open.

Approach 1: Let It Wait (Default)

The simplest approach: don’t use skipWaiting(). Users get the update on their next visit after all tabs close.

1// No skipWaiting—new worker waits2self.addEventListener("install", (event) => {3  event.waitUntil(4    caches.open("v2").then((cache) =>5      cache.addAll([6        /* ... */7      ]),8    ),9  )10  // Worker enters "waiting" state after install11})

Pros: Safe—no version mismatches. Cons: Updates may never apply for users with persistent tabs.

Approach 2: Skip Waiting (Prompt User)

Use skipWaiting() only when user explicitly requests the update:

1self.addEventListener("message", (event) => {2  if (event.data?.type === "SKIP_WAITING") {3    self.skipWaiting()4  }5})

Show 3 hidden lines4}56const registration = await navigator.serviceWorker.ready78registration.addEventListener("updatefound", () => {9  const newWorker = registration.installing!1011  newWorker.addEventListener("statechange", () => {12    if (newWorker.state === "installed" && registration.active) {13      // New version ready—show UI14      showUpdateNotification(() => {15        newWorker.postMessage({ type: "SKIP_WAITING" })16      })17    }18  })19})Show 5 hidden lines

Pros: User controls when the update happens. Cons: Requires UI implementation; some users ignore update prompts.

Approach 3: Skip Waiting (Backward Compatible)

If new code can run with old-cached assets (or vice versa), skip immediately:

1self.addEventListener("install", (event) => {2  self.skipWaiting()3  event.waitUntil(/* caching */)4})56self.addEventListener("activate", (event) => {7  event.waitUntil(clients.claim())8})

Pros: Updates apply immediately. Cons: Risk of version mismatches. Only works if your code handles this gracefully.

Version Mismatch Scenarios

When skipWaiting() activates a new worker while old pages are open:

Mitigation strategies:

1. Versioned URLs: app.v2.js never conflicts with app.v1.js
2. Keep old caches during activate: Don’t delete immediately
3. Force reload on controller change: location.reload() after controllerchange

Offline Fallbacks and UX

A robust offline experience requires graceful degradation when resources aren’t available.

Generic Offline Page

1const OFFLINE_PAGE = "/offline.html"23self.addEventListener("install", (event) => {4  event.waitUntil(caches.open("offline").then((cache) => cache.add(OFFLINE_PAGE)))5})67self.addEventListener("fetch", (event) => {8  if (event.request.mode === "navigate") {9    event.respondWith(fetch(event.request).catch(() => caches.match(OFFLINE_PAGE)))10  }11})

Offline Image Placeholder

1const OFFLINE_IMAGE = "/images/offline-placeholder.svg"23self.addEventListener("fetch", (event) => {4  if (event.request.destination === "image") {5    event.respondWith(6      caches.match(event.request).then((cached) => {7        return cached || fetch(event.request).catch(() => caches.match(OFFLINE_IMAGE))8      }),9    )10  }11})

Background Sync for Offline Actions

Queue failed mutations for retry when online.

Show 3 hidden lines4  await queue.push(request)5  await navigator.serviceWorker.ready.then((reg) => reg.sync.register("sync-requests"))6}78// Use when fetch fails9try {10  await fetch("/api/submit", { method: "POST", body: data })11} catch {12  await queueForSync(new Request("/api/submit", { method: "POST", body: data }))13  showToast("Saved offline—will sync when connected")14}

1self.addEventListener("sync", (event) => {2  if (event.tag === "sync-requests") {3    event.waitUntil(processQueue())4  }5})67async function processQueue() {8  const queue = await getRequestQueue()9  for (const request of await queue.getAll()) {10    try {11      await fetch(request)12      await queue.remove(request)13    } catch {14      // Still offline—will retry on next sync15      break16    }17  }18}

Debugging and Observability

Browser DevTools

Chrome DevTools (Application tab):

• Service Workers panel: View registered workers, state, and messages
• Update on reload: Forces new worker on every page load (development only)
• Bypass for network: Disables service worker for all fetches
• Offline checkbox: Simulates offline mode
• Cache Storage: Inspect cached request/response pairs

Firefox DevTools:

• Application > Service Workers: Similar to Chrome
• Enable Service Workers over HTTP: Testing without HTTPS (toolbox open only)

Logging Strategy

1const DEBUG = true23function log(context: string, ...args: unknown[]) {4  if (DEBUG) {5    console.log(`[SW:${context}]`, ...args)6  }7}89self.addEventListener("install", (event) => {10  log("install", "Starting install...")11  // ...12})1314self.addEventListener("fetch", (event) => {15  log("fetch", event.request.method, event.request.url)16  // ...17})

Common Issues and Solutions

Error Handling in Fetch

1self.addEventListener("fetch", (event) => {2  event.respondWith(3    handleFetch(event.request).catch((error) => {4      console.error("Fetch handler error:", error)56      // Return appropriate fallback based on request type7      if (event.request.destination === "document") {8        return caches.match("/offline.html")9      }10      if (event.request.destination === "image") {11        return caches.match("/offline-placeholder.svg")12      }1314      // For other requests, let the error propagate15      return new Response("Service unavailable", { status: 503 })16    }),17  )18})

Workbox: Production-Ready Abstractions

Workbox (Google) provides battle-tested implementations of caching patterns. Use it unless you have specific requirements that demand custom code.

Strategy Modules

1import { registerRoute } from "workbox-routing"2import { CacheFirst, NetworkFirst, StaleWhileRevalidate } from "workbox-strategies"3import { ExpirationPlugin } from "workbox-expiration"45// Static assets: cache-first with expiration6registerRoute(7  ({ request }) => request.destination === "style" || request.destination === "script",8  new CacheFirst({9    cacheName: "static-v1",10    plugins: [new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 30 * 24 * 60 * 60 })],11  }),12)1314// API calls: network-first with 3-second timeout15registerRoute(16  ({ url }) => url.pathname.startsWith("/api/"),17  new NetworkFirst({18    cacheName: "api-v1",19    networkTimeoutSeconds: 3,20  }),21)2223// Images: stale-while-revalidate24registerRoute(({ request }) => request.destination === "image", new StaleWhileRevalidate({ cacheName: "images-v1" }))

Precaching with Versioning

1import { precacheAndRoute } from "workbox-precaching"23// Injected by build tool (Webpack, Vite, etc.)4precacheAndRoute(self.__WB_MANIFEST)5// Generates versioned URLs: [{ url: "/app.js", revision: "abc123" }, ...]

When to Use Custom Code

• Complex routing logic not expressible with Workbox’s route matching
• Custom cache invalidation beyond time/count expiration
• Streaming responses that need transformation
• Tight bundle size constraints (Workbox adds ~10-20KB)

Conclusion

Service workers fundamentally change the browser’s network model: instead of direct fetches, an intermediary script decides response sources. The Cache API provides the durable storage that makes offline experiences possible. The lifecycle model—with its waiting states and update flows—ensures clients don’t run inconsistent code.

The key architectural insight is that service workers are event-driven and stateless between events. Global variables don’t persist. The worker may terminate after handling a fetch and restart fresh for the next one. Design accordingly: use Cache API and IndexedDB for persistence, not in-memory state.

Caching strategies represent trade-offs, not best practices. Cache-first sacrifices freshness for speed. Network-first sacrifices speed for freshness. Stale-while-revalidate trades bandwidth for both. Choose based on the specific resource’s characteristics and your users’ expectations.

Appendix

Prerequisites

• JavaScript Promises and async/await
• HTTP request/response model (methods, headers, caching headers)
• Familiarity with the Fetch API

Terminology

• Scope: URL path prefix that a service worker controls (e.g., /app/ controls /app/*)
• Client: A window, worker, or shared worker controlled by a service worker
• Registration: The binding of a service worker script to a scope
• Precaching: Caching resources during the install event before they’re needed
• Opaque response: Cross-origin response with mode: 'no-cors' that hides status and headers
• Navigation preload: Parallel network request during service worker startup

Summary

• Lifecycle states: parsed → installing → installed → waiting → activating → activated → redundant
• Only activated workers handle fetch events; waiting workers queue behind the current active worker
• Cache API stores Request/Response pairs durably; you control expiration and invalidation
• Caching strategies: cache-first (speed), network-first (freshness), stale-while-revalidate (both with bandwidth cost)
• skipWaiting() bypasses waiting but risks version mismatches; use with versioned URLs or user prompts
• Navigation preload eliminates worker startup delay by fetching in parallel
• Safari’s 7-day limit deletes storage without user interaction; PWAs on home screen are exempt

References

Specifications (Primary Sources)

• Service Workers — W3C Candidate Recommendation Draft (registration, lifecycle, fetch events, cache interface, navigation preload)
• Fetch Standard — WHATWG Living Standard (Request, Response, fetch algorithm, opaque responses)
• Storage Standard — WHATWG Living Standard (quota, persistence, storage buckets)
• Web Background Synchronization — W3C WICG Editor’s Draft (Chromium-only)

Official Documentation

• Service Worker API - MDN
• Cache - MDN
• CacheStorage - MDN
• NavigationPreloadManager - MDN
• StorageManager - MDN

Core Maintainer Content

• The Service Worker Lifecycle - web.dev - Jake Archibald’s definitive lifecycle guide
• The Offline Cookbook - web.dev - Caching strategy patterns
• Service Worker Caching and HTTP Caching - web.dev
• Speed up Service Worker with Navigation Preloads - web.dev
• Workbox - Production service worker library from Chrome team

Safari Storage Policy

• Full Third-Party Cookie Blocking and More - WebKit Blog - Safari’s 7-day storage cap details

Browser Support

• Can I Use: Service Workers
• Can I Use: Cache API
• Can I Use: Navigation Preload