Skip to content

Choosing a caching strategy

Published Updated

A caching strategy determines how a service worker answers a request from the cache or network. Choose among five strategies according to whether a resource is static, dynamic, or time-sensitive, and how stale a response your users can tolerate. Each trades freshness, speed, or offline availability. The plain functions can be added to sw.js.

You need a service worker with a fetch handler (see Offline strategies for the handler that routes requests to these functions). The Cache interface the functions use is separate from the HTTP cache: Cache-Control headers decide what the browser’s HTTP cache keeps, and have no influence on what cache.put() stores or how long caches.match() returns it.

Each function takes a Request and returns a Response, so a fetch handler can call event.respondWith(strategy(event.request)). cache.put() consumes the response body, which is why every function clones before storing.

Check the cache; go to the network only on a miss, and store what comes back.

async function cacheFirst(request, cacheName = 'static') {
const cached = await caches.match(request);
if (cached) return cached;
const response = await fetch(request);
if (response.ok) {
const cache = await caches.open(cacheName);
cache.put(request, response.clone());
}
return response;
}

Use it for hash-versioned assets (JavaScript bundles, CSS, images, fonts) that do not change under the same URL. The response is instant and works offline; the cost is that a cached entry is not refreshed until the service worker version changes or the entry is deleted.

Try the network; fall back to the cached copy when the request fails.

async function networkFirst(request, cacheName = 'dynamic', timeoutMs = 3000) {
const cache = await caches.open(cacheName);
try {
const response = await Promise.race([
fetch(request),
new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeoutMs)),
]);
if (response.ok) cache.put(request, response.clone());
return response;
} catch {
const cached = await cache.match(request);
if (cached) return cached;
throw new Error(`no network and no cached copy for ${request.url}`);
}
}

Use it for HTML and API responses where the newest version matters online and the last seen version is still useful offline. The cost is a full network wait on every request, and on a flaky connection the user waits for the failure before the cache answers; the timeout above caps that wait.

Return the cached response at once and refresh the cache in the background for next time.

async function staleWhileRevalidate(request, cacheName = 'dynamic') {
const cache = await caches.open(cacheName);
const cached = await cache.match(request);
const refresh = fetch(request).then((response) => {
if (response.ok) cache.put(request, response.clone());
return response;
});
return cached || refresh;
}

Use it for content that should be fast and reasonably current but can be one version behind: avatars, article lists, UI chrome. The cost is one extra request per load and a response that is stale by exactly one visit.

Do not consult the cache at all. In a fetch handler this means not calling respondWith() at all, so the browser handles the request as if no worker existed.

self.addEventListener('fetch', (event) => {
if (event.request.method !== 'GET') return; // network-only: POST, PUT, DELETE
});

Use it for non-GET requests, real-time data, and content that must stay current. It requires a network connection.

Serve exclusively from the cache and fail on a miss.

async function cacheOnly(request) {
const cached = await caches.match(request);
if (cached) return cached;
return new Response('Not precached', { status: 504 });
}

Use it for resources you precached in install: the app shell and the offline fallback page. The cost is that nothing updates until the next worker version precaches a new set.

Resource type Strategy Why
App shell (HTML, CSS, JavaScript) with hashed names Cache-first Immutable under one URL; instant after first visit
Images and fonts Cache-first Rarely change; large enough that refetching hurts
Navigation requests Network-first with an offline fallback page Fresh HTML online; cached shell or fallback offline
API data specific to the user Network-first Must be fresh; cache is the offline backstop
Shared or semi-static API data Stale-while-revalidate Paint from cache, refresh for next time
POST, PUT, DELETE, WebSocket upgrades Network-only Not servable from a cache
Precached offline page Cache-only Exists so the fallback does not depend on the network

Workbox ships the same five as classes in workbox-strategies: CacheFirst, NetworkFirst, StaleWhileRevalidate, NetworkOnly, and CacheOnly, registered per route with registerRoute(). NetworkFirst and NetworkOnly take a networkTimeoutSeconds option that plays the role of the timeout above; the Workbox StaleWhileRevalidate issues the revalidation request on every hit regardless of the cached entry’s age (workbox-strategies). Using the library adds a build step and a few kilobytes compared with maintaining these functions yourself.

Cache Storage has no expiry of its own, so a response stored a month ago is returned by caches.match() exactly as stored. For resources that are neither immutable nor critical, check the response’s Date header and treat an old entry as a miss.

async function cacheWithExpiry(request, maxAgeSeconds, cacheName = 'dynamic') {
const cache = await caches.open(cacheName);
const cached = await cache.match(request);
if (cached) {
const storedAt = new Date(cached.headers.get('date') || 0).getTime();
if (Date.now() - storedAt < maxAgeSeconds * 1000) return cached;
await cache.delete(request);
}
const response = await fetch(request);
if (response.ok) cache.put(request, response.clone());
return response;
}

The Date header is set by the server, so a clock that is wrong on either side shifts the expiry; storing your own timestamp in IndexedDB alongside the cache key is more work and more exact. Workbox’s ExpirationPlugin does this with maxAgeSeconds and maxEntries.

← Back to the Guides overview.