Introduction: The Network Is Not Reliable#

As frontend developers, we often test applications on local development servers, where the network always responds instantly. But the real-world network is fragile: signals drop in the subway, café Wi-Fi is useless, and carriers only have 2G in remote areas. If your page only shows users a browser error page saying “This site can’t be reached” when offline, the experience will be terrible.

The Offline-First design philosophy holds that: applications should assume “network unavailable” is the norm, treating offline as a first-class citizen in design rather than patching it in afterward. And the Service Worker is precisely the core primitive the browser provides for this concept—it acts like a programmable network proxy, intercepting all requests made by the page and letting you decide whether to go to the network, go to the cache, or combine both.

Service Worker Lifecycle Recap#

The Service Worker runs in a separate thread, completely decoupled from the page, with its own lifecycle:

1
install → waiting → activate → fetch (intercept request)

Three key events form its skeleton:

1
self.addEventListener('install', (event) => {
2
  //Precache key resources, usually done during the install phase
3
  event.waitUntil(/*Precache the app shell */);
4
});
5

6
self.addEventListener('activate', (event) => {
7
  //Clean up old version caches, take over pages
8
  event.waitUntil(/*Delete old caches */);
9
  self.clients.claim(); //Immediately take over all pages
10
});
11

12
self.addEventListener('fetch', (event) => {
13
  //Core: decide the response strategy for each request
14
  event.respondWith(/*Return cache or network response */);
15
});

event.waitUntil() tells the browser “don’t end the current lifecycle phase until this async task completes”; event.respondWith() lets you take over requests and return a custom Response object. Once you understand these two APIs, you understand the entire mental model of the Service Worker.

Four Core Caching Strategies#

Implementing offline-first is essentially about applying these four strategies in a “divide and conquer” manner based on request type.

1
async function cacheFirst(request) {
2
  const cache = await caches.open('static-v1');
3
  const cached = await cache.match(request);
4
  if (cached) return cached;
5
  const response = await fetch(request);
6
  cache.put(request, response.clone());
7
  return response;
8
}

1
async function networkFirst(request) {
2
  const cache = await caches.open('dynamic-v1');
3
  try {
4
    const response = await fetch(request);
5
    cache.put(request, response.clone());
6
    return response;
7
  } catch (err) {
8
    const cached = await cache.match(request);
9
    if (cached) return cached;
10
    return new Response('Network unavailable, and no cache', { status: 503 });
11
  }
12
}

1
async function staleWhileRevalidate(request) {
2
  const cache = await caches.open('pages-v1');
3
  const cached = await cache.match(request);
4
  const fetchPromise = fetch(request).then((response) => {
5
    cache.put(request, response.clone());
6
    return response;
7
  });
8
  return cached || fetchPromise;
9
}

Complete Implementation: A Runnable Offline-First Service Worker#

Combining the above strategies gives you a production-grade Service Worker. The core idea is routing by URL:

1
const VERSION = 'v3';
2
const APP_SHELL = [
3
  '/',
4
  '/styles/main.css',
5
  '/scripts/app.js',
6
  '/images/logo.svg',
7
];
8

9
//1. Install: precache the app shell to ensure the skeleton can load offline on first visit
10
self.addEventListener('install', (event) => {
11
  event.waitUntil(
12
    caches.open(`static-${VERSION}`).then((cache) => cache.addAll(APP_SHELL))
13
  );
14
  self.skipWaiting(); //The new version activates immediately without waiting for old pages to close
15
});
16

17
//2. Activate: delete old version caches to prevent storage from growing indefinitely
18
self.addEventListener('activate', (event) => {
19
  event.waitUntil(
20
    caches.keys().then((keys) =>
21
      Promise.all(
22
        keys
23
          .filter((key) => key.startsWith('static-') && key !== `static-${VERSION}`)
24
          .map((key) => caches.delete(key))
25
      )
26
    )
27
  );
28
  self.clients.claim();
29
});
30

31
//3. Intercept requests: route to different strategies based on URL patterns
32
self.addEventListener('fetch', (event) => {
33
  const { request } = event;
34
  const url = new URL(request.url);
35

36
  //Only handle same-origin GET requests (cross-origin and non-GET are left to the browser's default behavior)
37
  if (request.method !== 'GET' || url.origin !== location.origin) return;
38

39
  //Navigation requests (HTML pages): fall back to the cached homepage when offline
40
  if (request.mode === 'navigate') {
41
    event.respondWith(
42
      fetch(request).catch(() => caches.match('/'))
43
    );
44
    return;
45
  }
46

47
  //Static assets: Cache-First
48
  if (url.pathname.startsWith('/static/') || url.pathname.startsWith('/scripts/')) {
49
    event.respondWith(cacheFirst(request));
50
    return;
51
  }
52

53
  //API data: Network-First, fall back to cache when offline
54
  if (url.pathname.startsWith('/api/')) {
55
    event.respondWith(networkFirst(request));
56
    return;
57
  }
58

59
  //Other resources: Stale-While-Revalidate
60
  event.respondWith(staleWhileRevalidate(request));
61
});

Note response.clone(): the body of Response can only be read once; to both write to the cache and return it to the page, you must first clone().

Offline Fallback: Give Users a Friendly Safety Net#

Compared to the browser’s built-in “can’t connect” error page, a custom offline page can greatly improve the impression. The approach is to pre-cache an offline.html and return it when a navigation request fails:

1
self.addEventListener('install', (event) => {
2
  event.waitUntil(
3
    caches.open(`static-${VERSION}`).then((cache) =>
4
      cache.addAll([...APP_SHELL, '/offline.html'])
5
    )
6
  );
7
});
8

9
self.addEventListener('fetch', (event) => {
10
  if (event.request.mode === 'navigate') {
11
    event.respondWith(
12
      fetch(event.request).catch(() =>
13
        caches.match('/offline.html')
14
      )
15
    );
16
  }
17
});

Common Pitfalls#

• Cache names should be versioned: static-v1, static-v2… changing the version number is safer than overwriting the old cache, and combined with cleanup logic in the activate phase, it avoids the classic disaster of “code was updated but users keep hitting the old cache.”
• Don’t cache cross-origin requests: cross-origin responses require CORS support to be cache.put(), otherwise they fail silently. Always check url.origin === location.origin first.
• cache.addAll is an atomic operation: if even one resource 404s, the entire install fails and the Service Worker cannot activate. Double-check the paths in the pre-cache manifest.
• Storage quota is limited: the browser may reclaim the cache at any time, so don’t stuff large files or videos into Cache Storage; important data should be persisted with IndexedDB.

Conclusion#

Service Worker turns “the network” from an uncontrollable external environment into a resource you can precisely orchestrate in code. The three strategies—Cache-First, Network-First, and Stale-While-Revalidate—cover the vast majority of scenarios, and the key lies in routing by request type—navigation, static assets, and APIs each have their own optimal solution. Offline-first isn’t about making the app “completely independent of the network,” but rather ensuring that when the network fails, users can still continue using it gracefully.

References#

• MDN — Service Worker API
• web.dev — The Offline Cookbook (Jake Archibald)
• Google Developers — PWA Offline-First Guide