Intercept Network Requests with the `fetch` Event

Why it exists

To give developers fine-grained control over network requests originating from their web app. This enables powerful features like offline functionality and custom caching strategies that go beyond the browser's default behavior, making Progressive Web Apps (PWAs) more resilient and performant.

The mental model

Think of a Service Worker's fetch listener as a customs agent for your web app's network traffic. Every outgoing request—whether an API call, an image load, or a CSS file—must pass through this agent. The agent can then decide to let the request proceed to the network, redirect it to a local warehouse (the cache), or deny entry by creating a custom or error response on the spot.

How it works

When your app makes a network request, the browser fires a fetch event in the active Service Worker. Your event listener receives a FetchEvent object, which contains the original Request. To intercept it, you must synchronously call event.respondWith(). This method takes a Response object or, more commonly, a Promise that resolves to a Response. If you don't call respondWith(), the browser simply handles the request as if the Service Worker wasn't there, sending it to the network.

When to use it

This is the core mechanism for building offline-first applications. Use it to implement caching strategies like cache-first (serve from cache, fall back to network), network-first (try network, fall back to cache), or stale-while-revalidate. It's also useful for creating API mocks during development by intercepting fetch calls and returning synthetic JSON responses without a backend.

When not to use it

Avoid adding a fetch event listener if you don't intend to handle requests. An empty or slow listener adds overhead to every single network request your application makes, which can degrade performance. If you only need to cache assets when the Service Worker is installed, use the install event and the Cache API directly without intercepting fetch calls.

One canonical example

A cache-first strategy is a common use case. Inside the fetch event handler, you first check if a matching response exists in the Cache storage using caches.match(event.request). If a cached response is found, you return it immediately via event.respondWith(cachedResponse). If not, you proceed to make the actual network request with fetch(event.request), put the new response into the cache for future use, and then return that new response. This entire logic is wrapped in a promise chain passed to respondWith().