Caching Strategies¶

A caching strategy is the rule a service worker's fetch handler follows to decide where a response comes from: Cache Storage, the network, or some ordered or parallel combination of the two, plus what gets written back to the cache afterward. The strategy you choose for each class of request determines whether your PWA works offline, how fast repeat visits render, how stale the content can get, and how much storage and bandwidth you burn. This guide covers every canonical strategy with sequence diagrams, complete vanilla implementations, Workbox equivalents and the edge cases that break them in production. It ends with a full router that combines them and a flowchart for choosing one.

How a caching strategy plugs into the fetch event¶

Every strategy on this page is a function with the same shape: it receives a FetchEvent and returns a Promise<Response> that you hand to event.respondWith(). The browser dispatches a fetch event for every request made by a controlled client, including navigations, subresources and fetch()/XHR calls. The request flow is covered in Handling Fetch Events; the rules that matter for strategies are these:

• respondWith() must be called synchronously during event dispatch, and at most once. The spec throws InvalidStateError if the dispatch flag is unset (you awaited something first) or if respondWith() was already called. Pass it a promise and do the asynchronous work inside that promise.
• Not calling respondWith() is a valid strategy. If no listener calls it, the browser performs the request itself exactly as if there were no service worker. This is the cheapest possible "network only".
• A rejected promise, or a promise that resolves to something other than a Response, becomes a network error. For fetch() in the page that is a TypeError. For a navigation it is the browser's built-in offline or error page, which is the worst outcome a PWA can produce.
• respondWith() extends the event's lifetime as if waitUntil() had been called with the same promise, so the worker stays alive until the response promise settles. Anything that continues after that point, such as a cache write or a background revalidation, needs its own waitUntil().

The waitUntil window: why background work must be registered early¶

The Service Workers specification defines an ExtendableEvent as active while its dispatch flag is set or its pending promises count is greater than zero. waitUntil(promise) throws InvalidStateError when the event is not active. respondWith(r) adds r to the event's lifetime promises, so while the response promise is pending you can call waitUntil() from any later task. The moment that promise settles and nothing else is pending, the count drops to zero, the event becomes inactive, and a later waitUntil() call throws. The spec's own note puts it this way: if no lifetime extension promise has been added in the task that called the event handlers, calling waitUntil() in subsequent asynchronous tasks will throw.

That has a direct consequence for strategies that answer from one source and keep working on another, such as stale-while-revalidate or a cache/network race. This code looks reasonable and is broken:

self.addEventListener("fetch", (event) => {
  event.respondWith((async () => {
    const cached = await caches.match(event.request);
    const network = fetch(event.request);
    if (cached) {
      // BUG: this .then() runs after respondWith()'s promise has settled.
      // If nothing else is pending, waitUntil() throws InvalidStateError,
      // and the browser is free to terminate the worker before put() finishes.
      network.then((response) => {
        event.waitUntil(caches.open("v1").then((c) => c.put(event.request, response)));
      });
      return cached;
    }
    return network;
  })());
});

The fix is to register background work while the response promise is still pending. Workbox does it structurally: the StrategyHandler constructor calls event.waitUntil() on a deferred promise the moment a strategy starts handling a request, and resolves it only after handler.doneWaiting(), which loops until every promise passed to handler.waitUntil() (including ones added late) has settled. strategy.handleAll() exposes the same pair as [responseDone, handlerDone]. The vanilla helpers below do the simpler thing: every helper that starts background work calls event.waitUntil() immediately, while the strategy's own promise is still pending.

Cache Storage is not the HTTP cache¶

Two independent caches sit between a page and the origin, and a strategy only controls one of them directly:

The last row matters for revalidation. When a stale-while-revalidate strategy calls fetch(request) to refresh an entry, that request can be answered from the HTTP cache without touching the origin, if the HTTP cache still considers its copy fresh. To force a conditional request to the origin, fetch with cache: "no-cache" (the HTTP cache revalidates with If-None-Match / If-Modified-Since, and a 304 is transparently turned into the stored 200). See HTTP Caching & Service Workers for how to set headers so the two layers cooperate instead of stacking staleness.

What should be written to the cache¶

Cache.put() enforces only a few rules. Per the Service Workers specification, it rejects with a TypeError when the request URL's scheme is not http or https, when the request method is not GET, when the response status is 206, when the response has a Vary: * header, or when the response body is already disturbed or locked. Everything else is stored, including 404 pages, 500 error pages, opaque responses and responses marked Cache-Control: no-store. add() and addAll() are stricter: they reject if a response is not in the 200–299 range or is a 206, which is why they can't store opaque responses. addAll() is also atomic: if any request fails, nothing is stored.

Deciding what is worth caching is therefore your policy. The Workbox defaults are a reasonable baseline and worth knowing exactly: with no cacheWillUpdate plugin, CacheFirst only caches status 200, while StaleWhileRevalidate and NetworkFirst add a built-in plugin that caches status 0 (opaque) and 200. NetworkOnly and CacheOnly never write.

Shared helpers used by every strategy¶

The implementations on this page share one small module. It assumes a module service worker, registered with navigator.serviceWorker.register("/sw.js", { type: "module" }), which Chrome supports from 91, Safari from 15 and Firefox from 147. If you need a classic script, bundle the modules into one file (any bundler can emit a non-module build).

// Shared primitives for every strategy on this page.

export const CACHE_VERSION = "v1";

// One cache per resource class: each gets its own size and age policy,
// and each can be purged on its own when storage runs out.
export const CACHES = Object.freeze({
  shell: `shell-${CACHE_VERSION}`, // precached, versioned app shell + offline page
  pages: "pages",                  // HTML navigations
  immutable: "immutable-assets",   // content-hashed CSS/JS
  assets: "assets",                // unhashed CSS/JS
  images: "images",
  fonts: "fonts",
  api: "api",
  thirdParty: "third-party",
  media: "media",                  // audio/video the user explicitly downloaded
});

// Caches that can be dropped wholesale when a write hits the quota.
// Never list caches holding data the user asked to keep (CACHES.media).
const PURGEABLE = [CACHES.images, CACHES.thirdParty, CACHES.assets];

export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * Policy: is this response worth storing?
 * Cache.put() itself only rejects 206, Vary: *, non-GET and non-http(s);
 * everything else here is a deliberate choice.
 */
export function isCacheable(response, { allowOpaque = false } = {}) {
  if (!response) return false;
  if (response.type === "opaque") return allowOpaque; // status 0, unreadable
  if (response.type === "error" || response.type === "opaqueredirect") return false;
  if (response.status !== 200) return false; // no 404/500 pages, no 206 partials
  const vary = response.headers.get("Vary");
  if (vary && vary.split(",").some((field) => field.trim() === "*")) return false;
  // Respect an explicit instruction not to store this response anywhere.
  if (/\bno-store\b/i.test(response.headers.get("Cache-Control") ?? "")) return false;
  return true;
}

/**
 * Write a response without ever letting a failure reach the response path.
 * Resolves to true when the entry was stored.
 */
export async function putInCache(cacheName, request, response) {
  // Yield a task first. Workbox's StrategyHandler.cachePut() does the same
  // ("run in the next task to avoid blocking other cache reads", citing
  // w3c/ServiceWorker#1397): a cache write started immediately can queue
  // ahead of the cache.match() calls other requests are waiting on.
  await sleep(0);
  try {
    const cache = await caches.open(cacheName);
    await cache.put(request, response);
    return true;
  } catch (error) {
    if (error?.name === "QuotaExceededError") {
      await Promise.all(PURGEABLE.map((name) => caches.delete(name)));
    }
    console.warn("[sw] cache.put failed:", request.url ?? request, error);
    return false;
  }
}

/**
 * Network fetch that prefers the navigation preload response for navigations.
 */
export async function fromNetwork(event, request = event.request, init) {
  if (request === event.request && request.mode === "navigate" && event.preloadResponse) {
    try {
      const preloaded = await event.preloadResponse; // undefined if preload is disabled
      if (preloaded) return preloaded;
    } catch {
      // The preload failed (offline, aborted). Fall through: fetch() will
      // fail the same way if the network is really gone.
    }
  }
  // Never pass a RequestInit with a navigation request. The Request constructor
  // turns mode "navigate" into "same-origin" when init is non-empty (so the
  // server sees Sec-Fetch-Mode: same-origin), and older Chromium threw a TypeError.
  return request.mode === "navigate" ? fetch(request) : fetch(request, init);
}

/**
 * fetch() with a deadline. Rejects with a TimeoutError DOMException.
 */
export function fetchWithTimeout(event, request, timeoutMs, init = {}) {
  if (!timeoutMs) return fromNetwork(event, request, init);
  if (request.mode === "navigate") {
    // A signal needs a RequestInit, which would break navigate mode: race a timer instead.
    let timer;
    const deadline = new Promise((_, reject) => {
      timer = setTimeout(
        () => reject(new DOMException(`No response after ${timeoutMs} ms`, "TimeoutError")),
        timeoutMs,
      );
    });
    return Promise.race([fromNetwork(event, request), deadline]).finally(() => clearTimeout(timer));
  }
  // AbortSignal.timeout() actually cancels the request (and frees the socket).
  return fromNetwork(event, request, { ...init, signal: AbortSignal.timeout(timeoutMs) });
}

/**
 * Fetch, then write a copy to `cacheName` in the background.
 * The write is registered with waitUntil() synchronously, while the strategy's
 * promise (and therefore respondWith()) is still pending.
 */
export function fetchAndCache(event, request, cacheName, { allowOpaque = false, init } = {}) {
  const network = fromNetwork(event, request, init);
  // This reaction is registered before the caller awaits `network`, so clone()
  // runs before anyone starts reading the body.
  const written = network.then(
    (response) =>
      isCacheable(response, { allowOpaque })
        ? putInCache(cacheName, request, response.clone())
        : false,
    () => false,
  );
  event.waitUntil(written);
  return network;
}

Three details in that module deserve emphasis because they are where most hand-written strategies go wrong. First, response.clone() must happen before the body is consumed; a Response body is a stream that can be read once, and clone() on a used body throws TypeError. Second, fetchAndCache() returns the network response immediately and lets the cache write finish in the background. Awaiting cache.put() before returning would hold the response until the entire body had been downloaded and written, turning a streaming response into a buffered one. Third, putInCache() swallows errors: a quota error or a malformed response must never convert a successful network response into a failure.

Strategy overview¶

Cache only¶

Cache only answers exclusively from Cache Storage and never touches the network. It is only correct for URLs you guarantee are in the cache, which in practice means files precached during install, where the service worker refuses to install unless every file was stored.

How cache only works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Cache as Cache Storage
    Page->>SW: GET /app.3f9a2c1d.js
    SW->>Cache: match(request)
    alt entry found
        Cache-->>SW: Response
        SW-->>Page: Response from cache
    else miss
        Cache-->>SW: undefined
        SW-->>Page: 504 synthetic response
    end

Implementing cache only¶

import { CACHES } from "../lib/cache-helpers.js";

/**
 * Cache only. A miss is a bug (the router and the precache list disagree),
 * so it fails loudly instead of silently going to the network.
 */
export async function cacheOnly(event, { cacheName = CACHES.shell, matchOptions } = {}) {
  // Open the specific cache: caches.match() without a cacheName searches
  // every cache in creation order, which is slower and can return an entry
  // from a stale cache you forgot to delete.
  const cache = await caches.open(cacheName);
  const cached = await cache.match(event.request, matchOptions);
  if (cached) return cached;

  console.error(`[sw] cache-only miss for ${event.request.url} in "${cacheName}"`);
  // A real Response (not Response.error()) lets page code inspect the failure.
  return new Response("", { status: 504, statusText: "Not in cache" });
}

import { registerRoute } from "workbox-routing";
import { CacheOnly } from "workbox-strategies";

// CacheOnly never writes. Something else (precaching, warmStrategyCache,
// a user action) must have filled the cache.
registerRoute(
  ({ url, sameOrigin }) => sameOrigin && url.pathname.startsWith("/app/v2/"),
  new CacheOnly({ cacheName: "app-v2" }),
);

// For precached build output you don't need a route at all:
// precacheAndRoute(self.__WB_MANIFEST) registers a cache-only route
// (with URL normalization and revision handling) for every precached URL.

When to use cache only¶

• Files listed in your precache manifest: the versioned app shell, the offline page, fallback images. In Workbox, precacheAndRoute() already serves these cache-only, so you rarely write this route yourself.
• Assets the user explicitly saved for offline use (a downloaded podcast episode, an offline map region) that must never cost mobile data once saved.
• Any request where going to the network would be wrong, for example a kiosk build that must render exactly the version it installed.

Cache only pitfalls¶

• Query strings and URL variants miss. /app.js and /app.js?v=3 are different cache keys. Build tools and CDNs add cache-busting parameters; so do analytics tags (?utm_source=...) on navigations. Use ignoreSearch: true only when the query truly doesn't change the response, and never for API routes where it does.
• Vary headers can make a precached entry unmatchable. Matching compares every request header named in the stored response's Vary between the stored request and the lookup request. If the server sends Vary: Accept, an entry stored by cache.addAll() from a plain URL string won't match the browser's later stylesheet request, which carries a stylesheet-specific Accept value. Strip Vary for static assets on the server or pass ignoreVary: true.
• Redirected responses break navigations. If / redirects to /index.html during precaching, the stored response has redirected === true. Serving it for a navigation, whose redirect mode is manual, fails with a network error. Precache the final URL, or copy the response into a fresh Response before storing it (shown in Common pitfalls).

Network only¶

Network only sends the request to the network and returns whatever comes back, never reading or writing Cache Storage. It is the right answer for anything that must not be cached, and it is often best implemented by not handling the request at all.

How network only works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Net as Network
    Page->>SW: POST /api/orders
    alt no respondWith call
        SW-->>Page: listener returns, event not handled
        Note over Page,Net: The browser sends the request natively
    else respondWith with fetch
        SW->>Net: fetch(request)
        Net-->>SW: 201 Created
        SW-->>Page: 201 Created
    end

Implementing network only¶

import { fetchWithTimeout } from "../lib/cache-helpers.js";

/**
 * Network only, with an optional deadline.
 * Prefer returning early from the fetch listener (no respondWith) when you
 * don't need the timeout: the browser then handles the request natively.
 */
export function networkOnly(event, { timeoutMs = 0 } = {}) {
  return fetchWithTimeout(event, event.request, timeoutMs);
}

self.addEventListener("fetch", (event) => {
  const { request } = event;
  // Cheapest network only: don't call respondWith() at all.
  if (request.method !== "GET") return;
  if (new URL(request.url).pathname.startsWith("/auth/")) return;
  // ...other routes
});

import { registerRoute } from "workbox-routing";
import { NetworkOnly } from "workbox-strategies";

// Workbox routes are registered per HTTP method (default "GET").
registerRoute(
  ({ url }) => url.pathname.startsWith("/api/"),
  new NetworkOnly({ networkTimeoutSeconds: 10 }),
  "POST",
);

// Anything that matches no route and has no default handler is not
// handled by Workbox, which is the same as the early return above.

NetworkOnly in Workbox 7 accepts plugins, fetchOptions and networkTimeoutSeconds; it deliberately omits cacheName and matchOptions because it never touches a cache. Its timeout is implemented as a Promise.race() against a timer, so the underlying request is not aborted; the vanilla version above uses AbortSignal.timeout() for non-navigation requests, which does cancel it.

When to use network only¶

• Non-GET requests. The Cache API can't store them (put() rejects any method other than GET). If a POST must survive going offline, queue it with Background Sync rather than caching it.
• Authentication, session, payment and checkout endpoints, where a cached answer is either a security problem or a correctness problem. See Service Worker Security.
• Analytics beacons and real-time data (prices, stock levels, live scores) where a stale value is worse than none.
• Server-Sent Events and long-polling endpoints, whose responses never end; the Cache API buffers the whole body before committing it.

Network only pitfalls¶

• A fetch listener that does nothing still costs you. Even if it returns without calling respondWith(), the browser must start the service worker and run the listener before the request proceeds. Chrome 112 added a console warning for listeners that are completely empty ("no-op"), and Chrome 115 started skipping them, but a listener with any logic in it is always run. For high-traffic network-only paths, the Static Routing API (event.addRoutes() with source: "network", Chromium 123+ and Safari 27+) bypasses the worker entirely.
• Wrapping in respondWith(fetch(request)) changes the error surface. If the fetch fails, the page sees a generic network error instead of the browser's native handling. Only wrap when you add value: a timeout, a fallback, logging.
• Timeouts on non-idempotent requests are dangerous. Aborting a POST on the client doesn't abort it on the server; the order may still be placed. Use timeouts for reads, and idempotency keys for writes.

Cache first (cache falling back to network)¶

Cache first looks in the cache and only goes to the network on a miss, storing the network response for next time. After the first load the resource never costs a network round trip again, which is exactly right for URLs whose content never changes and exactly wrong for everything else.

How cache first works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Cache as Cache Storage
    participant Net as Network
    Page->>SW: GET /fonts/inter.3b1c.woff2
    SW->>Cache: match(request)
    alt hit
        Cache-->>SW: Response
        SW-->>Page: Response from cache, no network
    else miss
        Cache-->>SW: undefined
        SW->>Net: fetch(request)
        Net-->>SW: 200 OK
        SW-->>Page: Response
        SW->>Cache: put(request, clone) in waitUntil
    end

Implementing cache first¶

import { fetchAndCache } from "../lib/cache-helpers.js";

/**
 * Cache first: serve from cache, go to the network only on a miss.
 * allowOpaque defaults to false because a cached opaque error is permanent.
 */
export async function cacheFirst(event, { cacheName, allowOpaque = false, matchOptions } = {}) {
  const cache = await caches.open(cacheName);
  const cached = await cache.match(event.request, matchOptions);
  if (cached) return cached;
  // Miss: fetch, respond, and store a copy in the background.
  // Network errors propagate so the router's fallback can handle them.
  return fetchAndCache(event, event.request, cacheName, { allowOpaque });
}

import { registerRoute } from "workbox-routing";
import { CacheFirst } from "workbox-strategies";
import { CacheableResponsePlugin } from "workbox-cacheable-response";
import { ExpirationPlugin } from "workbox-expiration";

registerRoute(
  ({ request, sameOrigin }) => sameOrigin && request.destination === "font",
  new CacheFirst({
    cacheName: "fonts",
    plugins: [
      // CacheFirst only caches status 200 by default; stating it documents intent.
      new CacheableResponsePlugin({ statuses: [200] }),
      new ExpirationPlugin({ maxEntries: 30, maxAgeSeconds: 365 * 24 * 60 * 60 }),
    ],
  }),
);

When to use cache first¶

• Content-hashed build output (app.3f9a2c1d.js, styles.8e21.css): a new version is a new URL, so a cached entry can never be stale. Serve these with Cache-Control: public, max-age=31536000, immutable as well.
• Web fonts, which are almost always versioned and are fetched in CORS mode (so the response is readable and its status can be checked).
• Images whose URL changes when the content changes: product photos with IDs, user uploads with content hashes, CDN URLs with transformation parameters.
• Anything you'd accept being stuck on a version until you explicitly purge it, combined with an expiration policy so the cache doesn't grow forever.

Cache first pitfalls¶

• Unversioned URLs get stuck. /styles.css served cache first will never update until the entry is deleted, even after you deploy and even after the service worker updates, because caches outlive worker versions. Either version the URL or use stale-while-revalidate.
• Opaque responses make errors permanent. A cross-origin no-cors image that returned a 503 during a CDN incident is stored as an indistinguishable opaque response and served forever. Keep allowOpaque off for cache first, and use CORS (crossorigin attribute) or stale-while-revalidate for third-party assets. The Workbox runtime caching guide recommends network first or stale-while-revalidate for opaque responses for the same reason.
• Unbounded growth. Every distinct URL adds an entry. Pair cache first with maxEntries/maxAgeSeconds, especially for images, and remember that superseded hashed files pile up too: after five deploys you hold five copies of the bundle unless something evicts the old ones.
• Cache first may not keep the browser off the network. Chrome 154 (stable since September 22, 2026) includes an optional browser optimization, ServiceWorkerAutoPreload, in which the browser may issue the network request in parallel with service worker startup. Per its Chrome Platform Status entry, if the handler responds with respondWith(), the network result is consumed inside the fetch handler; if the handler falls back, the network response goes straight to the browser. A cache-first handler that answers from cache simply doesn't use it, but your origin can still see the request, so don't treat "served from cache" as "no server traffic" when capacity planning. Chrome applies it only by heuristics (for example, for sites whose handler usually falls back, or when the worker isn't already running), and not when you have enabled navigation preload yourself. The ServiceWorkerAutoPreloadEnabled enterprise policy, available from Chrome 140 during the rollout, is listed on Chrome Platform Status for removal in Chrome 154.

Network first (network falling back to cache) with a timeout¶

Network first always tries the network, stores successful responses, and falls back to the cached copy when the network fails. It gives users the freshest content whenever they are online and the last good copy when they are not. On its own it has one serious flaw: a network that is slow rather than down (a captive portal, one bar of signal, a congested train Wi-Fi, often called "lie-fi") doesn't make fetch() reject. It just hangs, often far longer than any user will wait, while the user stares at a blank screen with a perfectly good cached page available. A timeout fixes that.

How network first with a timeout works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Net as Network
    participant Cache as Cache Storage
    Page->>SW: navigate to /articles/42
    SW->>Net: fetch or preloadResponse
    SW->>SW: start 3 s timer
    alt network answers first
        Net-->>SW: 200 OK
        SW-->>Page: fresh response
        SW->>Cache: put clone in waitUntil
    else timer fires and cache has an entry
        SW->>Cache: match(request)
        Cache-->>SW: cached response
        SW-->>Page: cached response
        Net-->>SW: late 200 OK
        SW->>Cache: put clone, refreshed for next time
    else network fails
        Net--xSW: TypeError
        SW->>Cache: match(request)
        Cache-->>SW: cached response or undefined
        SW-->>Page: cached response or fallback
    end

Note the middle branch: when the timeout wins, the network request is not abandoned. It keeps running inside waitUntil(), and when it completes the cache is refreshed, so the next visit gets the newer copy. That is the behavior of Workbox's NetworkFirst too, and it's usually what you want. The alternative, aborting the request at the deadline, saves bandwidth but guarantees the cache never improves on a slow connection.

Implementing network first with a timeout¶

import { fetchAndCache } from "../lib/cache-helpers.js";

/**
 * Network first with an optional timeout.
 * - Network answers within timeoutMs: respond with it and refresh the cache.
 * - Network fails (or returns 5xx and fallbackOn5xx is set): respond from cache.
 * - Network is slow: after timeoutMs respond from cache if there's an entry;
 *   the request keeps running in waitUntil() and refreshes the cache.
 */
export async function networkFirst(event, {
  cacheName,
  timeoutMs = 0,
  allowOpaque = false,
  fallbackOn5xx = true,
  matchOptions,
} = {}) {
  const { request } = event;
  // Start the network request before any await, so opening the cache
  // doesn't delay it.
  const network = fetchAndCache(event, request, cacheName, { allowOpaque });
  const cache = await caches.open(cacheName);
  const fromCache = () => cache.match(request, matchOptions);

  const networkOrCache = network.then(
    async (response) => {
      // An overloaded origin returning 503 is an outage from the user's
      // point of view: prefer the last good copy when there is one.
      if (fallbackOn5xx && response.status >= 500) return (await fromCache()) ?? response;
      return response;
    },
    async (error) => {
      const cached = await fromCache();
      if (cached) return cached;
      throw error; // nothing cached: let the router's fallback decide
    },
  );

  if (!timeoutMs) return networkOrCache;

  let timer;
  const cacheAfterTimeout = new Promise((resolve) => {
    timer = setTimeout(async () => {
      // Resolve only on a hit. On a miss (or a failed lookup) this promise
      // never settles and the race keeps waiting for the network, which is
      // still the best source.
      const cached = await fromCache().catch(() => undefined);
      if (cached) resolve(cached);
    }, timeoutMs);
  });

  try {
    return await Promise.race([networkOrCache, cacheAfterTimeout]);
  } finally {
    clearTimeout(timer);
  }
}

import { registerRoute } from "workbox-routing";
import { NetworkFirst } from "workbox-strategies";
import { CacheableResponsePlugin } from "workbox-cacheable-response";
import * as navigationPreload from "workbox-navigation-preload";

// Strategies use event.preloadResponse automatically for navigations,
// but navigation preload still has to be enabled.
navigationPreload.enable();

// Throwing from fetchDidSucceed turns a 5xx into a "network failure",
// which makes NetworkFirst fall back to the cache.
const fallbackOn5xx = {
  fetchDidSucceed: async ({ response }) => {
    if (response.status >= 500) throw new Error(`HTTP ${response.status}`);
    return response;
  },
};

registerRoute(
  ({ request }) => request.mode === "navigate",
  new NetworkFirst({
    cacheName: "pages",
    networkTimeoutSeconds: 3,
    plugins: [
      // NetworkFirst would cache status 0 and 200 by default; pages are
      // same-origin, so only 200 is meaningful.
      new CacheableResponsePlugin({ statuses: [200] }),
      fallbackOn5xx,
    ],
  }),
);

The Workbox implementation is worth reading because its edge-case behavior is well tested. NetworkFirst._handle() races two promises: a timeout promise that resolves to handler.cacheMatch(request) after networkTimeoutSeconds, and a network promise that calls handler.fetchAndCachePut(request) and falls back to cacheMatch() on error. If the race resolves to undefined (the timer fired but the cache was empty), it waits for the network promise instead: (await Promise.race(promises)) || (await networkPromise). When the network wins, it calls clearTimeout(). When everything fails, it throws a no-response WorkboxError, which reaches your setCatchHandler(). The pageCache recipe in workbox-recipes uses exactly this strategy for navigations, with a default networkTimeoutSeconds of 3.

Choosing a timeout value¶

The timeout trades freshness against perceived speed, and there is no universal number:

• Navigations: 2 to 4 seconds is common; Workbox's pageCache recipe defaults to 3. Measure your own TTFB distribution and set the timeout above the 95^th percentile of healthy responses, so that only genuinely degraded connections fall back.
• API JSON that drives the UI: often shorter (1 to 3 seconds), because the page can render cached data and then refresh; this is where cache then network shines.
• Never for non-idempotent requests. A timeout on a POST doesn't cancel the server-side effect.
• Adaptive timeouts are possible in Chromium through the Network Information API (navigator.connection.effectiveType, saveData), which is also exposed in workers. It is Chromium-only, so treat it as an optimization and keep a sane default for Firefox and Safari.

When to use network first¶

• HTML navigations for sites whose pages change (news, e-commerce, dashboards). Serving a cached article from last week is acceptable offline and unacceptable online.
• API data where freshness matters but offline access is still valuable: order history, account settings, messages.
• Anything personalized, provided you clear the cache on logout (see Common pitfalls).

Network first pitfalls¶

• No timeout means lie-fi hangs. Without a deadline, a stalled TCP connection leaves the page blank until the browser gives up, which can take far longer than any user waits.
• The first visit is never covered. Network first only has something to fall back to after a successful load. Precache the offline page and use a generic fallback for URLs never visited.
• Navigation preload interacts with caching. With navigation preload enabled, the network request for a navigation starts in parallel with service worker startup, and fromNetwork() above uses event.preloadResponse. If your server returns a different body for preload requests (it can detect the Service-Worker-Navigation-Preload header, for example to send only the content partial), don't cache that body as the full page, and send Vary: Service-Worker-Navigation-Preload so HTTP caches keep the variants apart. If you enable preload but never consume preloadResponse, Chrome warns in the console that the preload request was cancelled before preloadResponse settled.
• Every visit writes to the cache. For large HTML pages that is real I/O on every navigation. That is usually fine, but skip the write when the response is identical (compare ETag) if storage writes show up in traces.

Stale-while-revalidate¶

Stale-while-revalidate (SWR) responds immediately from the cache when it can, and at the same time fetches a fresh copy from the network to update the cache for next time. If there is no cached copy, it waits for the network. The name comes from the HTTP Cache-Control: stale-while-revalidate extension defined in RFC 5861, which gives the HTTP cache the same behavior; a service worker lets you apply it to any request, with your own rules.

How stale-while-revalidate works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Cache as Cache Storage
    participant Net as Network
    Page->>SW: GET /api/categories
    SW->>Cache: match(request)
    alt cached copy exists
        Cache-->>SW: stale response
        SW-->>Page: stale response, instantly
        SW->>Net: fetch with cache no-cache, inside waitUntil
        Net-->>SW: 200 OK
        SW->>Cache: put(request, response)
        SW-->>Page: optional CACHE_UPDATED message
    else nothing cached
        SW->>Net: fetch(request)
        Net-->>SW: 200 OK
        SW-->>Page: response
        SW->>Cache: put clone in waitUntil
    end

SWR's defining property is that the user always sees content that is at most one fetch behind: the response they get was current as of their previous request for that URL. For a resource requested on every page view, that's minutes old. For one requested once a month, it's a month old, which is why SWR is often paired with a freshness window or an expiration policy.

Implementing stale-while-revalidate¶

The vanilla version adds three production features beyond the textbook pattern: an in-flight map so that concurrent requests for the same URL (five tabs, or the same avatar rendered ten times) trigger one revalidation instead of many; a freshForMs window that skips revalidation entirely while the entry is young, equivalent to max-age plus stale-while-revalidate in HTTP; and an onUpdate hook used later to broadcast updates.

import { fetchAndCache, fromNetwork, isCacheable, putInCache } from "../lib/cache-helpers.js";

// Revalidations in flight, keyed by URL. Lives only as long as this worker
// instance, which is exactly as long as it needs to.
const inflight = new Map();

/** Age from the Date header (origin clock), or Infinity when unknown/opaque. */
export function responseAgeMs(response) {
  const date = Date.parse(response.headers.get("Date") ?? "");
  return Number.isNaN(date) ? Infinity : Math.max(0, Date.now() - date);
}

export async function staleWhileRevalidate(event, {
  cacheName,
  allowOpaque = true, // SWR self-heals on the next request, so opaque is tolerable
  freshForMs = 0,     // skip revalidation while the entry is younger than this
  onUpdate,           // async ({ event, request, cacheName, oldResponse, newResponse })
} = {}) {
  const { request } = event;
  const cache = await caches.open(cacheName);
  const cached = await cache.match(request);

  if (!cached) {
    // Cold cache: plain "network, then store". Errors reach the fallback.
    return fetchAndCache(event, request, cacheName, { allowOpaque });
  }

  if (freshForMs > 0 && responseAgeMs(cached) < freshForMs) {
    return cached; // still fresh: no network traffic at all
  }

  // Registered while respondWith() is still pending (see "The waitUntil window").
  event.waitUntil(revalidate(event, cache, cacheName, { allowOpaque, onUpdate }));
  return cached;
}

function revalidate(event, cache, cacheName, { allowOpaque, onUpdate }) {
  const { request } = event;
  const key = request.url;
  if (inflight.has(key)) return inflight.get(key);

  const task = (async () => {
    // cache: "no-cache" forces the HTTP cache to revalidate with the origin
    // instead of answering from its own still-fresh copy. Navigation
    // requests can't take a RequestInit (see fromNetwork), so they don't get it.
    const init = request.mode === "navigate" ? undefined : { cache: "no-cache" };
    const response = await fromNetwork(event, request, init);
    if (!isCacheable(response, { allowOpaque })) return;

    // Read the previous entry *before* overwriting it; onUpdate compares them.
    const oldResponse = onUpdate ? await cache.match(request) : undefined;
    const newResponse = onUpdate ? response.clone() : undefined;
    const stored = await putInCache(cacheName, request, response);
    if (stored && oldResponse) {
      await onUpdate({ event, request, cacheName, oldResponse, newResponse });
    }
  })()
    // Offline or failing origin: the user already has the stale copy.
    .catch((error) => console.info("[sw] revalidation failed, keeping stale copy:", key, error))
    .finally(() => inflight.delete(key));

  inflight.set(key, task);
  return task;
}

import { registerRoute } from "workbox-routing";
import { StaleWhileRevalidate } from "workbox-strategies";
import { CacheableResponsePlugin } from "workbox-cacheable-response";
import { ExpirationPlugin } from "workbox-expiration";
import { BroadcastUpdatePlugin } from "workbox-broadcast-update";

registerRoute(
  ({ url, sameOrigin }) => sameOrigin && url.pathname.startsWith("/api/categories"),
  new StaleWhileRevalidate({
    cacheName: "api",
    fetchOptions: { cache: "no-cache" }, // bypass a fresh HTTP-cache copy
    plugins: [
      new CacheableResponsePlugin({ statuses: [200] }),
      new ExpirationPlugin({ maxEntries: 50 }),
      new BroadcastUpdatePlugin(), // posts CACHE_UPDATED when ETag etc. change
    ],
  }),
);

// A freshness window needs a small subclass: StaleWhileRevalidate always
// revalidates. (Response headers are readable for CORS/same-origin only.)
export class FreshThenStaleWhileRevalidate extends StaleWhileRevalidate {
  constructor({ freshForSeconds = 60, ...options } = {}) {
    super(options);
    this.freshForMs = freshForSeconds * 1000;
  }
  async _handle(request, handler) {
    // Note: super._handle() calls cacheMatch() again, so plugins with a
    // cachedResponseWillBeUsed callback (ExpirationPlugin) run twice on
    // the revalidating path. That is harmless for expiration bookkeeping.
    const cached = await handler.cacheMatch(request);
    const date = Date.parse(cached?.headers.get("Date") ?? "");
    if (cached && Date.now() - date < this.freshForMs) return cached;
    return super._handle(request, handler);
  }
}

Workbox's StaleWhileRevalidate._handle() starts handler.fetchAndCachePut(request) first, attaches a no-op .catch() and registers it with handler.waitUntil(), then looks in the cache. If there is a hit, it returns it; if not, it awaits the network promise, and if that fails too it throws no-response. Unlike the vanilla version, it has no in-flight deduplication and no freshness window: every request for a cached URL causes a network request. Its default cacheability, without a cacheWillUpdate plugin, is status 0 or 200.

When to use stale-while-revalidate¶

• Unhashed CSS and JavaScript such as third-party widgets or a CMS theme file: fast from cache, corrected on the next load. Workbox's staticResourceCache recipe uses SWR for style, script and worker destinations.
• Avatars, logos and other images that change rarely and where a stale copy is harmless.
• API responses for reference data: category trees, feature flags, configuration, translation bundles.
• HTML for content sites where speed beats freshness (documentation, blogs), ideally combined with update broadcasting so an open page can offer "This page has been updated. Reload?".
• Cross-origin opaque resources where you can't check status codes: the next request replaces a bad entry, so an error self-heals after one view.

Stale-while-revalidate pitfalls¶

• Every cache hit costs a background request. SWR never saves bandwidth, only latency. On metered connections that is a real cost; add a freshness window or honor navigator.connection.saveData in Chromium.
• The HTTP cache can make revalidation a no-op. If the origin sends Cache-Control: max-age=3600, a plain fetch() in the worker gets the HTTP-cached copy for an hour and SWR "revalidates" against itself. Use cache: "no-cache" for the background fetch.
• Stale by one request is unbounded in time. A monthly-visited page is a month stale. Use freshForMs, a maxAgeSeconds expiration (which turns an expired entry into a miss, so the user waits for the network), or network first for such pages.
• The Date header measures the origin clock, not the device clock. Freshness windows computed from Date are off by the device's clock skew, and a CDN may serve a response whose Date is hours old (check Age). For precise windows, record your own timestamp when you write the entry, as the expiration helper does.
• Deduplicating by URL ignores Vary. If a URL legitimately varies by a request header, key the in-flight map by URL plus that header.

Cache then network: the UI pattern¶

Cache then network is not a service worker strategy at all; it's a page-side pattern. The page makes two requests in parallel: one straight to Cache Storage (which windows can read through window.caches) and one to the network. It renders the cached data as soon as it arrives, then re-renders with the network data. The user sees content instantly and fresh content moments later. Jake Archibald's Offline Cookbook describes it for frequently updated content such as articles and social timelines.

How cache then network works¶

sequenceDiagram
    participant UI as Page code
    participant Cache as Cache Storage
    participant SW as Service worker
    participant Net as Network
    par read cache directly
        UI->>Cache: caches.open then match
        Cache-->>UI: cached JSON
        UI->>UI: render cached data, mark as stale
    and ask the network
        UI->>SW: fetch /api/feed
        SW->>Net: fetch(request)
        Net-->>SW: 200 OK
        SW->>Cache: put clone
        SW-->>UI: fresh JSON
        UI->>UI: render fresh data
    end

The service worker's job on this route is "network, and store what you get". It must not fall back to the cache on failure, because the page already rendered the cached copy; falling back would just make the page render the same data twice and hide the fact that it's offline.

Implementing cache then network¶

/**
 * Render cached data immediately, then fresh data from the network.
 * @param {string} url  Same URL string the service worker caches under.
 * @param {(data: unknown, meta: { source: "cache" | "network" }) => void} render
 * @returns {Promise<"network" | "cache" | "none">} which source ended up on screen
 */
export async function cacheThenNetwork(url, render, { cacheName = "api", signal } = {}) {
  let networkRendered = false;

  const network = fetch(url, { headers: { Accept: "application/json" }, signal })
    .then(async (response) => {
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      const data = await response.json();
      networkRendered = true;
      render(data, { source: "network" });
    });

  const cached = (async () => {
    if (!("caches" in window)) return false; // insecure context or old browser
    const cache = await caches.open(cacheName);
    const response = await cache.match(url);
    if (!response) return false;
    const data = await response.json();
    // The network may have won while we were parsing: never overwrite
    // fresh data with stale data.
    if (networkRendered || signal?.aborted) return false;
    render(data, { source: "cache" });
    return true;
  })().catch(() => false); // a corrupt entry must not break the network path

  try {
    await network;
    return "network";
  } catch (error) {
    if (error.name === "AbortError") throw error;
    // Offline or failing: whatever the cache gave us is all there is.
    return (await cached) ? "cache" : "none";
  }
}

import { fetchAndCache } from "../lib/cache-helpers.js";

/** Service worker half: network only, but keep a copy for the page to read. */
export function networkAndCache(event, { cacheName }) {
  return fetchAndCache(event, event.request, cacheName);
}

import { registerRoute } from "workbox-routing";
import { Strategy } from "workbox-strategies";

// "Network, and store what you get": fetchAndCachePut() fetches, runs
// plugins, and writes the clone inside the handler's waitUntil().
class NetworkAndCache extends Strategy {
  _handle(request, handler) {
    return handler.fetchAndCachePut(request);
  }
}

registerRoute(
  ({ url, sameOrigin }) => sameOrigin && url.pathname === "/api/feed",
  new NetworkAndCache({ cacheName: "api" }),
);

// The page-side cacheThenNetwork() helper is identical: Workbox has no
// window-side equivalent, and none is needed.

import { cacheThenNetwork } from "./cache-then-network.js";

const controller = new AbortController();
const list = document.querySelector("#feed");
const banner = document.querySelector("#offline-banner");

const source = await cacheThenNetwork("/api/feed", (items, { source }) => {
  list.replaceChildren(...items.map(renderItem));
  list.toggleAttribute("aria-busy", source === "cache"); // still refreshing
}, { signal: controller.signal });

banner.hidden = source === "network";
if (source === "none") list.textContent = "You're offline and nothing is saved yet.";

When to use cache then network¶

• Feeds, timelines, inboxes and dashboards, where showing something immediately and updating in place is the expected UX.
• Single-page app views that own their rendering and can reconcile two renders without layout jumps.
• Data that must be both instant and fresh, when network first's timeout would still feel slow.

Cache then network pitfalls¶

• Double rendering has UX cost. Content that jumps when fresh data arrives causes layout shifts (CLS) and can move the element under the user's finger. Reconcile by key, keep scroll position, and consider showing "3 new items" instead of re-rendering.
• The cache key must match exactly. The page reads caches.match("/api/feed") with a plain URL; if the service worker stored the entry under a Request whose response has Vary: Accept or Vary: Authorization, the lookup misses. Keep API responses free of unnecessary Vary, or pass { ignoreVary: true } knowing what it means.
• It doesn't work without a controlling worker writing the cache, and it needs a secure context for window.caches. On the very first visit there is nothing to render from cache.
• Race conditions are real. The network can win; the cached branch must check whether fresh data is already on screen, as the helper does.

Race: cache and network, fastest wins¶

The race strategy sends the request to both the cache and the network at the same time and responds with whichever produces a usable response first. The cookbook motivates it with devices where storage is slow: with some combinations of older hard drives, virus scanners and fast internet connections, fetching from the network can be quicker than reading from disk. It is also a way to hedge against cache lookups that are slow because the cache is huge.

How the race works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Cache as Cache Storage
    participant Net as Network
    Page->>SW: GET /img/thumb/881.webp
    par cache lookup
        SW->>Cache: match(request)
    and network request
        SW->>Net: fetch(request)
    end
    Cache-->>SW: hit after 40 ms
    SW-->>Page: cached response wins
    Net-->>SW: 200 after 180 ms
    SW->>Cache: put clone, refreshed for next time

Implementing the race¶

The textbook version, Promise.race([caches.match(request), fetch(request)]), has two bugs. Promise.race() settles with the first promise to settle, including a rejection, so an instant offline TypeError beats a cache hit. And caches.match() resolves with undefined on a miss, so a fast miss "wins" and respondWith() receives undefined, which is a network error. Use Promise.any() (Chrome 85, Firefox 79, Safari 14), turn a miss into a rejection, and decide whether an HTTP error status counts as a win.

import { fetchAndCache } from "../lib/cache-helpers.js";

/**
 * Race cache and network; the first *usable* response wins.
 * A 5xx or 4xx from the network doesn't beat a cache hit.
 */
export async function raceCacheAndNetwork(event, { cacheName, allowOpaque = false } = {}) {
  const { request } = event;
  // Starts immediately and registers its cache write with waitUntil().
  const network = fetchAndCache(event, request, cacheName, { allowOpaque });

  const usableNetwork = network.then((response) =>
    response.ok || response.type === "opaque" ? response : Promise.reject(response),
  );
  const cacheHit = caches
    .open(cacheName)
    .then((cache) => cache.match(request))
    .then((hit) => hit ?? Promise.reject(new Error("cache miss")));

  try {
    return await Promise.any([cacheHit, usableNetwork]);
  } catch {
    // Both lost. Prefer a real HTTP error response over a network error:
    // if the network answered 404, the page should see the 404.
    return network; // rejects with the fetch TypeError when offline
  }
}

import { registerRoute } from "workbox-routing";
import { Strategy } from "workbox-strategies";

// Adapted from the CacheNetworkRace example in the Workbox docs, with a
// miss/HTTP-error aware winner selection.
class CacheNetworkRace extends Strategy {
  _handle(request, handler) {
    const network = handler.fetchAndCachePut(request);
    const usableNetwork = network.then((r) =>
      r.ok || r.type === "opaque" ? r : Promise.reject(r),
    );
    const cacheHit = handler
      .cacheMatch(request)
      .then((hit) => hit ?? Promise.reject(new Error("cache miss")));
    return Promise.any([cacheHit, usableNetwork]).catch(() => network);
  }
}

registerRoute(
  ({ request, sameOrigin }) => sameOrigin && request.destination === "image",
  new CacheNetworkRace({ cacheName: "images" }),
);

When to use the race¶

• Small, frequently used assets on devices where you have evidence (from RUM data) that cache reads are slow.
• As a hedge for enormous caches, although fixing the cache size with expiration is usually the better fix.

Browsers are experimenting with racing at the platform level too. The Static Routing API includes a "race-network-and-fetch-handler" source that races a network request against your fetch handler without waiting for the worker to boot, and Chrome's ServiceWorkerAutoPreload optimization issues the network request in parallel with worker startup. Both address service worker startup latency rather than slow disks.

Race pitfalls¶

• The network request is always made, even when the cache wins, so the race never saves bandwidth; it only saves latency. Don't race large resources or anything on a metered connection.
• Opaque responses can't be judged. ok is false and status is 0 for opaque responses, so the helper lets them win unconditionally; with allowOpaque off they are still returned but never cached.
• Responses are not interchangeable. If the cached and network versions differ (a new deploy), consecutive loads can alternate between versions depending on which source wins. Only race immutable or version-agnostic resources.

Generic fallback¶

A generic fallback is what the router returns when the chosen strategy fails completely: no network and nothing in the cache. Without one, respondWith() receives a rejected promise and the browser shows its own error page, or the page's fetch() rejects with a bare TypeError. A fallback turns those into something your UI controls. The full UX design of offline states lives in Offline UX & Fallbacks; this section covers the mechanics.

How the generic fallback works¶

sequenceDiagram
    participant Page
    participant SW as Service worker
    participant Net as Network
    participant Cache as Cache Storage
    Page->>SW: navigate to /never-visited
    SW->>Net: network first
    Net--xSW: TypeError, offline
    SW->>Cache: match /never-visited
    Cache-->>SW: undefined
    SW->>Cache: match /offline.html in the precache
    Cache-->>SW: offline page
    SW-->>Page: offline page, URL bar still shows /never-visited

Implementing the generic fallback¶

The fallback responses must be precached at install time, so they're guaranteed to exist exactly when the network isn't there to fetch them. Select the fallback by request.destination ("document" for navigations, "image", "font", "style", "script", and the empty string for fetch() and XHR calls), not by URL extension.

import { CACHES } from "../lib/cache-helpers.js";

export const FALLBACK_URLS = ["/offline.html", "/img/offline.svg"];

// Precache fallbacks as an install dependency: if they can't be stored,
// installation fails and the previous worker stays in control.
export function precacheFallbacks(installEvent) {
  installEvent.waitUntil(
    caches.open(CACHES.shell).then((cache) => cache.addAll(FALLBACK_URLS)),
  );
}

/** Wrap any strategy so that a total failure produces a controlled response. */
export function withFallback(strategy) {
  return async (event, options) => {
    try {
      return await strategy(event, options);
    } catch (error) {
      return offlineFallback(event.request, error);
    }
  };
}

export async function offlineFallback(request, error) {
  const cache = await caches.open(CACHES.shell);
  switch (request.destination) {
    case "document":
      // Navigations: the precached offline page. Response.error() only if
      // even that is missing (should be impossible after a good install).
      return (await cache.match("/offline.html")) ?? Response.error();
    case "image":
      return (await cache.match("/img/offline.svg")) ??
        new Response(
          '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>',
          { headers: { "Content-Type": "image/svg+xml" } },
        );
    case "": {
      // fetch()/XHR. Only synthesize JSON for callers that asked for it.
      if (request.headers.get("Accept")?.includes("application/json")) {
        return new Response(
          JSON.stringify({ error: "offline", message: String(error?.message ?? error) }),
          {
            status: 503,
            statusText: "Service Unavailable (offline)",
            headers: { "Content-Type": "application/json", "Cache-Control": "no-store" },
          },
        );
      }
      return Response.error();
    }
    default:
      // Fonts, scripts, styles: a network error lets the browser apply its
      // own fallback (font-display, onerror handlers, noscript paths).
      return Response.error();
  }
}

import { setCatchHandler, setDefaultHandler } from "workbox-routing";
import { NetworkOnly } from "workbox-strategies";
import { matchPrecache, precacheAndRoute } from "workbox-precaching";

// offline.html and offline.svg must be in the precache manifest.
precacheAndRoute(self.__WB_MANIFEST);
setDefaultHandler(new NetworkOnly());

// Called whenever a route's handler throws (including "no-response").
setCatchHandler(async ({ request }) => {
  switch (request.destination) {
    case "document":
      return (await matchPrecache("/offline.html")) ?? Response.error();
    case "image":
      return (await matchPrecache("/img/offline.svg")) ?? Response.error();
    default:
      return Response.error();
  }
});

// Alternatives: the offlineFallback() recipe from workbox-recipes, or
// PrecacheFallbackPlugin({ fallbackURL }) from workbox-precaching on a
// single strategy (it hooks the handlerDidError plugin callback).

When to use a generic fallback¶

Always, as the last layer of every route that can fail. The only question is what to return for each destination:

Generic fallback pitfalls¶

• Fallbacks outside the precache don't exist when you need them. Never fetch the offline page lazily.
• Don't cache a fallback under the original URL. If the synthetic 503 or the offline page is written into the runtime cache for /articles/42, that URL is broken until evicted. Fallback responses are generated or read from the precache, never stored.
• Keep the offline page self-contained. It is served under whatever URL the user navigated to, so relative URLs inside it resolve against that URL. Inline its CSS and images or reference precached absolute URLs.
• Response.error() is not "no response". It resolves respondWith() with a network error response. Use it deliberately when you want the browser's native failure behavior.

Cache with expiration¶

Cache Storage has no expiration mechanism of any kind, so "cache with expiration" is a policy layered on top of another strategy: cache first, network first or stale-while-revalidate, plus rules that delete entries when a cache holds more than maxEntries items or when an entry is older than maxAgeSeconds. Without it, a runtime image cache on a busy site grows until the browser's quota evicts all of your origin's storage, as described in Storage Quotas & Persistence.

How expiration works¶

sequenceDiagram
    participant SW as Service worker
    participant Cache as Cache Storage
    participant IDB as IndexedDB metadata
    SW->>Cache: match(request)
    Cache-->>SW: cached response
    SW->>IDB: read cachedAt for URL
    alt older than maxAge
        SW->>SW: treat as a miss, fetch from network
    else fresh
        SW->>IDB: update usedAt, in waitUntil
    end
    SW->>Cache: put(request, response) on refresh
    SW->>IDB: write cachedAt and usedAt
    SW->>IDB: cursor over entries, newest usedAt first
    IDB-->>SW: URLs beyond maxEntries or past maxAge
    SW->>Cache: delete(url, ignoreVary true)

The metadata has to live somewhere other than the cached Response, for three reasons. Responses from cache.match() have immutable headers, so you can't stamp a timestamp onto them in place. Opaque responses have no readable headers and can't be re-wrapped (a Response can't be constructed with status 0). And cache.keys() has no access-time information: the spec returns entries in insertion order, with a put() of an existing URL moving it to the end, which gives you "least recently written", not "least recently used". IndexedDB is the natural home, and it's what Workbox's ExpirationPlugin uses.

Implementing cache with expiration¶

// Per-entry metadata for Cache Storage: when an entry was written (for
// maxAge) and when it was last served (for LRU eviction by maxEntries).
const DB_NAME = "sw-cache-expiration";
const STORE = "entries";
let dbPromise;

function openDB() {
  dbPromise ??= new Promise((resolve, reject) => {
    const req = indexedDB.open(DB_NAME, 1);
    req.onupgradeneeded = () => {
      const store = req.result.createObjectStore(STORE, { keyPath: "id" });
      store.createIndex("byCacheAndUse", ["cacheName", "usedAt"]);
    };
    req.onsuccess = () => {
      const db = req.result;
      db.onversionchange = () => {
        db.close(); // never block a future upgrade
        dbPromise = undefined; // reopen lazily on the next call
      };
      resolve(db);
    };
    req.onerror = () => reject(req.error);
  }).catch((error) => {
    dbPromise = undefined; // allow a retry on the next call
    throw error;
  });
  return dbPromise;
}

function run(mode, work) {
  return openDB().then((db) => new Promise((resolve, reject) => {
    const tx = db.transaction(STORE, mode);
    const result = work(tx.objectStore(STORE));
    tx.oncomplete = () => resolve(result.value);
    tx.onerror = () => reject(tx.error);
    tx.onabort = () => reject(tx.error);
  }));
}

const idFor = (cacheName, url) => `${cacheName}|${url}`;

export function getEntry(cacheName, url) {
  return run("readonly", (store) => {
    const out = {};
    store.get(idFor(cacheName, url)).onsuccess = (e) => { out.value = e.target.result; };
    return out;
  });
}

/** Record a write (resets age) or a read (refreshes LRU position). */
export function touch(cacheName, url, { written = false } = {}) {
  return run("readwrite", (store) => {
    const id = idFor(cacheName, url);
    const now = Date.now();
    store.get(id).onsuccess = (e) => {
      const prev = e.target.result;
      store.put({
        id, cacheName, url,
        cachedAt: written || !prev ? now : prev.cachedAt,
        usedAt: now,
      });
    };
    return {};
  });
}

/**
 * Delete entries past maxAgeSeconds (by write time) or beyond maxEntries
 * (least recently used first). Returns the deleted URLs.
 */
export async function expire(cacheName, { maxEntries, maxAgeSeconds } = {}) {
  const oldest = maxAgeSeconds ? Date.now() - maxAgeSeconds * 1000 : -Infinity;
  const doomed = await run("readwrite", (store) => {
    const out = { value: [] };
    const range = IDBKeyRange.bound([cacheName, -Infinity], [cacheName, Infinity]);
    let kept = 0;
    // "prev" walks from most to least recently used.
    store.index("byCacheAndUse").openCursor(range, "prev").onsuccess = (e) => {
      const cursor = e.target.result;
      if (!cursor) return;
      const { url, cachedAt } = cursor.value;
      if (cachedAt < oldest || (maxEntries && kept >= maxEntries)) {
        out.value.push(url);
        cursor.delete();
      } else {
        kept += 1;
      }
      cursor.continue();
    };
    return out;
  });
  if (doomed.length) {
    const cache = await caches.open(cacheName);
    // ignoreVary: a plain URL has none of the headers a Vary'd entry was
    // stored with, and would otherwise fail to match (and to delete).
    await Promise.all(doomed.map((url) => cache.delete(url, { ignoreVary: true })));
  }
  return doomed;
}

/** Drop all metadata for a cache you are deleting. */
export async function forgetCache(cacheName) {
  const range = IDBKeyRange.bound([cacheName, -Infinity], [cacheName, Infinity]);
  await run("readwrite", (store) => {
    store.index("byCacheAndUse").openCursor(range).onsuccess = (e) => {
      const cursor = e.target.result;
      if (cursor) { cursor.delete(); cursor.continue(); }
    };
    return {};
  });
}