PWA Cache Strategies — Cache-First, Network-First, SWR & Workbox Patterns

Overview

Caching strategy is a per-resource-class decision. Hashed static assets love cache-first. HTML navigations usually want network-first. API lists often want stale-while-revalidate. Workbox encodes these patterns. Hand-rolled Cache Storage is fine if you own versioning and update UX.

This is the Cache API inside a Service Worker, not a server-side Redis tier and not the browser HTTP cache. Those layers can sit in front of the same URL and still disagree.

Strategy table

What if you choose the other? Cache-first on index.html sticks users on an old shell. Network-first on every /assets/app.abc123.js wastes round trips and breaks offline. Stale-while-revalidate on a bank balance, with no ETag and no copy in the UI, is a trust bug.

Decision path

flowchart TB
  a["1. Classify the GET"]
  b["2. Hashed asset is cache-first"]
  c["3. HTML navigation is network-first"]
  d["4. Stale lists use SWR"]
  a -->|1. Classify the GET| b
  b -->|2. Hashed asset is cache-first| c
  c -->|3. HTML navigation is network-first| d

The chain is a checklist, not seven caches. Each request takes one row. The versioned name is the last step for every row that writes.

Hand-rolled shapes

These are the browser shapes. They need Cache Storage and fetch, so they are not the sandbox. The next block runs the same decisions against a Map.

async function cacheFirst(req, cacheName) {
  const cache = await caches.open(cacheName);
  const hit = await cache.match(req);
  if (hit) return hit;
  const res = await fetch(req);
  if (res.ok) cache.put(req, res.clone());
  return res;
}

async function networkFirst(req, cacheName, timeoutMs = 3000) {
  const cache = await caches.open(cacheName);
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    const res = await fetch(req, { signal: controller.signal });
    clearTimeout(timer);
    if (res.ok) cache.put(req, res.clone());
    return res;
  } catch {
    clearTimeout(timer);
    return (await cache.match(req)) || new Response("Offline", { status: 503 });
  }
}

async function staleWhileRevalidate(req, cacheName) {
  const cache = await caches.open(cacheName);
  const hit = await cache.match(req);
  const refreshing = fetch(req)
    .then((res) => {
      if (res.ok) cache.put(req, res.clone());
      return res;
    })
    .catch(() => null);
  return hit || (await refreshing) || new Response("Offline", { status: 503 });
}

Same rules, in memory

Press Run. Snippets must be self-contained — no network, files, or native modules.

Cache-first returns v1 on the second call even though the network offered v2. Stale-while-revalidate shows stale and leaves fresh in the store for the next read.

Workbox versus hand-rolled

Rule of thumb: use Workbox when the build already emits an asset manifest. Hand-roll a tiny shell or a teaching worker. Either way, version the name (app-shell-v4) and delete old names on activate.

Offline UX and versioned caches

1. Keep the app shell in shell-vN and read it cache-first.
2. Use separate runtime caches for images and API responses, with a size or age cap.
3. On activate, delete every cache not in the allowlist.
4. When a worker is waiting, show "Update available", then skipWaiting, then reload.
5. Do not put secrets or Set-Cookie personalized HTML in a shared cache unless the key includes the user.

Interview Q&A

Pitfalls

• One caches.open("app") for shell, API, and avatars.
• Caching the opaque redirect that follows a login.
• Assuming Workbox's default route matches your HTML. Read the route you registered.
• Pruning on a timer in the page instead of on activate, so old names survive until the page is open.

Go deeper

• web.dev — Offline cookbook
• Chrome — Workbox strategies
• MDN — Cache