Reference

Fetch & respondWith

Policy surface for controlled clients. Strategies catalog: Cache API · strategies · Offline Cookbook.

When fetch fires

• Only for controlled clients in scope (page has a controller).
• Navigations + subresources (JS, CSS, images, XHR/fetch from the page).
• No handler / no respondWith → browser continues normal network path (HTTP cache, then network).

Core API

self.addEventListener("fetch", (event) => {
  // event.request — Request (url, method, mode, headers, …)
  event.respondWith(
    // must return a Response or Promise<Response>
    caches.match(event.request).then((cached) => {
      return cached || fetch(event.request);
    })
  );
});

Rules that bite

• Call respondWith synchronously in the event handler (don’t wait for an async gap first).
• A Response body can be read once — use response.clone() if you both return it and cache.put it.
• You may answer with a synthetic new Response("…", { status, headers }).
• Cross-origin opaque responses are limited — see Cache API dealbreakers if you cache them.

Navigation vs subresource (decision hints)

Signal	Often means
request.mode === "navigate"	Document navigation — shell / HTML policy
Same-origin static asset	Cache-first / precached shell (versioned)
API / frequently changing JSON	Network-first or network-only

Minimal cache-first sketch

self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches.match(event.request).then((hit) => {
      if (hit) return hit;
      return fetch(event.request).then((res) => {
        const copy = res.clone();
        caches.open("runtime-v1").then((c) => c.put(event.request, copy));
        return res;
      });
    })
  );
});