Service Workers and Cache API

A comprehensive exploration of offline-first web architecture, examining how the Service Worker API (W3C Working Draft, January 2026) enables network interception and background processing, how the Cache API provides fine-grained storage for request/response pairs, and how update flows ensure clients transition safely between versions. These APIs form the foundation of Progressive Web Apps (PWAs): service workers intercept fetches and decide response sources, Cache API stores those responses durably, and the lifecycle model ensures exactly one version controls clients at any time.

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 notes “the lifetime of a service worker is tied to the execution lifetime of events”—workers may start and stop “many times a second.” Global state doesn’t persist; use IndexedDB or Cache API
• 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
• HTTPS mandatory: Service workers can intercept any request in their scope, including credentials. Without TLS, attackers could inject malicious workers via MITM

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:

3 collapsed lines
1
// Feature detection (collapsed)
2
if (!("serviceWorker" in navigator)) {
3
  console.log("Service workers not supported")
4
}
5

6
// Register with explicit scope
7
const registration = await navigator.serviceWorker.register("/sw.js", {
8
  scope: "/app/", // Controls /app/* URLs
9
})
10

11
console.log("Scope:", registration.scope) // "https://example.com/app/"
12
console.log("Active:", registration.active?.state) // "activated" if ready
13
console.log("Waiting:", registration.waiting?.state) // Worker pending activation
14
console.log("Installing:", registration.installing?.state) // Currently installing
15

16
// Default scope: directory containing the worker script
17
// /scripts/sw.js → scope defaults to /scripts/
2 collapsed lines
18
await navigator.serviceWorker.register("/scripts/sw.js")
19
// Only controls /scripts/* URLs unless Service-Worker-Allowed header expands it

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:

2 collapsed lines
1
// Cache version constant (collapsed)
2
const CACHE_NAME = "app-v1"
3

4
self.addEventListener("install", (event) => {
5
  event.waitUntil(
6
    caches.open(CACHE_NAME).then((cache) => {
7
      // addAll is atomic—fails entirely if any resource fails
8
      return cache.addAll(["/", "/app.js", "/styles.css", "/offline.html"])
9
    }),
10
  )
11
})
12

13
// ⚠️ addAll fetches with mode: 'cors' by default
14
// Cross-origin resources need proper CORS headers or use:
15
cache.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 becomes redundant.

Activate Event: Cleanup

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

3 collapsed lines
1
// Expected cache names (collapsed)
2
const CURRENT_CACHES = { app: "app-v2", images: "images-v1" }
3

4
self.addEventListener("activate", (event) => {
5
  const expectedNames = new Set(Object.values(CURRENT_CACHES))
6

7
  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 entirely
2
self.addEventListener("install", (event) => {
3
  self.skipWaiting() // Activate immediately after install
4
  event.waitUntil(/* caching */)
5
})
6

7
// In activate event: take control of existing clients
8
self.addEventListener("activate", (event) => {
9
  event.waitUntil(
10
    clients.claim(), // Control pages that loaded before this worker
11
  )
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: “I rarely do so myself. 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. Push/sync event fires (if >24 hours since last check)
3. registration.update() called explicitly
4. Worker script URL changes (rare, avoid this pattern)

The browser fetches the worker script and compares bytes. Any difference triggers a new install. The spec notes: “Most browsers default to ignoring caching headers when checking for updates.”

1
// Trigger manual update check
2
const registration = await navigator.serviceWorker.ready
3
await registration.update()
4

5
// Monitor for updates
6
registration.addEventListener("updatefound", () => {
7
  const newWorker = registration.installing
8
  newWorker?.addEventListener("statechange", () => {
9
    if (newWorker.state === "installed") {
10
      // New version ready, waiting to activate
11
      if (registration.active) {
12
        // Show "Update available" UI
13
        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:

2 collapsed lines
1
// Open or create cache (collapsed)
2
const cache = await caches.open("api-v1")
3

4
// Add single resource (fetches and stores)
5
await cache.add("/api/config")
6

7
// Add multiple resources (atomic—all or nothing)
8
await cache.addAll(["/api/config", "/api/user"])
9

10
// Put explicit request/response pair
11
const response = await fetch("/api/data")
12
await cache.put("/api/data", response.clone()) // Must clone—body consumed
13

14
// Match with options
15
const match = await cache.match(request, {
16
  ignoreSearch: true, // Ignore query string
17
  ignoreMethod: true, // Match regardless of HTTP method
18
  ignoreVary: true, // Ignore Vary header
19
})
20

21
// List all cached requests
22
const keys = await cache.keys()
23

24
// Delete specific entry
25
const 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:
2
cache.put("/api?page=1", response1)
3
cache.put("/api?page=2", response2)
4

5
// Match with query string
6
await cache.match("/api?page=1") // Returns response1
7
await cache.match("/api?page=2") // Returns response2
8
await cache.match("/api") // Returns undefined
9

10
// Ignore query string
11
await 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: Since March 2020, Safari deletes all script-writable storage (IndexedDB, Cache API, service worker registrations) after 7 days without user interaction. This resets when the user visits the site. PWAs added to home screen are exempt.

Check quota with the Storage API:

1
const estimate = await navigator.storage.estimate()
2
console.log(`Used: ${estimate.usage} bytes`)
3
console.log(`Quota: ${estimate.quota} bytes`)
4
console.log(`Available: ${((estimate.quota! - estimate.usage!) / 1024 / 1024).toFixed(1)} MB`)
5

6
// Request persistent storage (immune to automatic eviction)
7
const persistent = await navigator.storage.persist()
8
if (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:

Cache-First (Cache Falling Back to Network)

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

1
self.addEventListener("fetch", (event) => {
2
  event.respondWith(
3
    caches.match(event.request).then((cached) => {
4
      if (cached) return cached
5

6
      return fetch(event.request).then((response) => {
7
        // Optionally cache the new response
8
        if (response.ok) {
9
          const clone = response.clone()
10
          caches.open("dynamic").then((cache) => cache.put(event.request, clone))
11
        }
12
        return response
13
      })
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:

1
self.addEventListener("fetch", (event) => {
2
  event.respondWith(
3
    fetch(event.request)
4
      .then((response) => {
5
        // Update cache with fresh response
6
        const clone = response.clone()
7
        caches.open("api").then((cache) => cache.put(event.request, clone))
8
        return response
9
      })
10
      .catch(() => {
11
        // Network failed—try cache
12
        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:

1
self.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 cache
6
        const fetchPromise = fetch(event.request).then((response) => {
7
          cache.put(event.request, response.clone())
8
          return response
9
        })
10

11
        // Return cached immediately, or wait for network if no cache
12
        return cached || fetchPromise
13
      })
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:

1
self.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:

1
self.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

1
self.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

1
self.addEventListener("fetch", (event) => {
2
  if (event.request.mode === "navigate") {
3
    event.respondWith(
4
      (async () => {
5
        // Try cache first
6
        const cached = await caches.match(event.request)
7
        if (cached) return cached
8

9
        // Use preloaded response if available
10
        const preloaded = await event.preloadResponse
11
        if (preloaded) return preloaded
12

13
        // Fallback to regular fetch
14
        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 value
2
await registration.navigationPreload.setHeaderValue("v2")
3
// Server receives: Service-Worker-Navigation-Preload: v2
4

5
// Check current state
6
const 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 waits
2
self.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 install
11
})

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:

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

3 collapsed lines
1
// UI notification (collapsed)
2
function showUpdateNotification(onUpdate: () => void) {
3
  /* ... */
4
}
5

6
const registration = await navigator.serviceWorker.ready
7

8
registration.addEventListener("updatefound", () => {
9
  const newWorker = registration.installing!
10

11
  newWorker.addEventListener("statechange", () => {
12
    if (newWorker.state === "installed" && registration.active) {
13
      // New version ready—show UI
14
      showUpdateNotification(() => {
15
        newWorker.postMessage({ type: "SKIP_WAITING" })
16
      })
17
    }
18
  })
19
})
5 collapsed lines
20

21
// Reload when new worker takes control
22
navigator.serviceWorker.addEventListener("controllerchange", () => {
23
  window.location.reload()
24
})

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:

1
self.addEventListener("install", (event) => {
2
  self.skipWaiting()
3
  event.waitUntil(/* caching */)
4
})
5

6
self.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

1
const OFFLINE_PAGE = "/offline.html"
2

3
self.addEventListener("install", (event) => {
4
  event.waitUntil(caches.open("offline").then((cache) => cache.add(OFFLINE_PAGE)))
5
})
6

7
self.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

1
const OFFLINE_IMAGE = "/images/offline-placeholder.svg"
2

3
self.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:

3 collapsed lines
1
// Queue the request for background sync
2
async function queueForSync(request: Request) {
3
  const queue = await getRequestQueue() // IndexedDB-backed
4
  await queue.push(request)
5
  await navigator.serviceWorker.ready.then((reg) => reg.sync.register("sync-requests"))
6
}
7

8
// Use when fetch fails
9
try {
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
}

1
self.addEventListener("sync", (event) => {
2
  if (event.tag === "sync-requests") {
3
    event.waitUntil(processQueue())
4
  }
5
})
6

7
async 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 sync
15
      break
16
    }
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

1
const DEBUG = true
2

3
function log(context: string, ...args: unknown[]) {
4
  if (DEBUG) {
5
    console.log(`[SW:${context}]`, ...args)
6
  }
7
}
8

9
self.addEventListener("install", (event) => {
10
  log("install", "Starting install...")
11
  // ...
12
})
13

14
self.addEventListener("fetch", (event) => {
15
  log("fetch", event.request.method, event.request.url)
16
  // ...
17
})

Common Issues and Solutions

Error Handling in Fetch

1
self.addEventListener("fetch", (event) => {
2
  event.respondWith(
3
    handleFetch(event.request).catch((error) => {
4
      console.error("Fetch handler error:", error)
5

6
      // Return appropriate fallback based on request type
7
      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
      }
13

14
      // For other requests, let the error propagate
15
      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

1
import { registerRoute } from "workbox-routing"
2
import { CacheFirst, NetworkFirst, StaleWhileRevalidate } from "workbox-strategies"
3
import { ExpirationPlugin } from "workbox-expiration"
4

5
// Static assets: cache-first with expiration
6
registerRoute(
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
)
13

14
// API calls: network-first with 3-second timeout
15
registerRoute(
16
  ({ url }) => url.pathname.startsWith("/api/"),
17
  new NetworkFirst({
18
    cacheName: "api-v1",
19
    networkTimeoutSeconds: 3,
20
  }),
21
)
22

23
// Images: stale-while-revalidate
24
registerRoute(({ request }) => request.destination === "image", new StaleWhileRevalidate({ cacheName: "images-v1" }))

Precaching with Versioning

1
import { precacheAndRoute } from "workbox-precaching"
2

3
// Injected by build tool (Webpack, Vite, etc.)
4
precacheAndRoute(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 Working Draft (defines registration, lifecycle, fetch events, cache interface)
• Fetch Standard - WHATWG Living Standard (defines Request, Response, fetch algorithm)
• Storage Standard - WHATWG Living Standard (defines quota, persistence, storage buckets)

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