Service worker offline page: a fallback that actually helps

#Why an offline page matters

Without a service worker, a lost connection means the browser's own error screen, and in an installed app that looks broken. With one, every page navigation goes through your code first. You decide what to show: fresh content when the network answers, a cached copy when it does not, and a clear, branded page for the rest.

#Precache the page during install

The offline page has to be stored while the network still works. Add it to the install step of your worker:

const CACHE = 'pages-v3';

self.addEventListener('install', (event) => {
  event.waitUntil(caches.open(CACHE).then((cache) => cache.addAll(['offline.html', './'])));
});

Keep the page self contained. If it links a stylesheet or an image, those must be cached too, and a missing one leaves the offline page unstyled exactly when it matters. Inline the CSS and put small images in data URLs.

#Serve it for failed navigations, with a timeout

Navigations are the requests for whole pages. Try the network first so people get fresh content, then fall back. A plain fetch().catch() only falls back when the request fails, but on a weak signal requests hang for a long time instead of failing. Race the network against a timer:

const TIMEOUT = 3000;

self.addEventListener('fetch', (event) => {
  if (event.request.mode !== 'navigate') return;
  event.respondWith(page(event));
});

async function page(event) {
  const network = fetch(event.request).then(async (res) => {
    if (res.ok) (await caches.open(CACHE)).put(event.request, res.clone());
    return res;
  });
  const slow = new Promise((resolve) => setTimeout(resolve, TIMEOUT, 'slow'));
  const first = await Promise.race([network.catch(() => 'failed'), slow]);
  if (first instanceof Response) return first;

  const cached = await caches.match(event.request);
  if (cached) {
    event.waitUntil(network.catch(() => {})); // refresh it in the background
    return cached;
  }
  if (first === 'slow') {
    try { return await network; } catch {}
  }
  return caches.match('offline.html');
}

Three details matter here. Successful pages are stored, so every page someone reads becomes available offline. A slow response still finishes in the background and refreshes the cache. And a page with nothing cached waits for the slow network instead of jumping to the offline page while the content is on its way.

#Match folders and file names

Static hosts serve /menu/ from menu/index.html and often /menu from menu.html. If you precached menu/index.html, a navigation to /menu/ will not match it by default. Try the variants before giving up: the URL without its query string, the folder index, and the .html name. installkite's worker does this for every navigation.

#Point people to what they have

An offline page that says only "You are offline" is a dead end. The page can read the Cache Storage API itself and list the pages already saved on the device:

const names = await caches.keys();
const urls = [];
for (const name of names) {
  for (const req of await (await caches.open(name)).keys()) {
    const path = new URL(req.url).pathname;
    if (path.endsWith('/') || path.endsWith('.html')) urls.push(path);
  }
}
document.querySelector('#saved').innerHTML = [...new Set(urls)].map((p) => `<a href="${p}">${p}</a>`).join('');
addEventListener('online', () => location.reload());

Reloading on the online event brings the visitor back to what they wanted the moment the connection returns.

#The installkite offline page

npx installkite init writes offline.html in your theme and background colors, with your app icon inlined as a data URL, a Try again button, automatic reload when the connection returns and a list of the pages saved on the device. It is precached with a content hash, and the worker serves it for any navigation inside the scope that has no cached copy. The timeout is configurable:

"sw": {
  "offline": "offline.html",
  "navigationTimeout": 2500,
  "exclude": ["api/", "admin/"]
}

Run npx installkite init --yes again to apply config changes, and npx installkite doctor checks that the offline page exists and is precached.

#What not to cache

Be careful with pages that depend on the visitor: a cart, an account page, anything behind a login. Storing them in a shared cache can show stale or private data after a sign out. Exclude those paths from the worker, and let API calls and form posts go straight to the network. installkite only handles GET requests, never touches requests with a Range header such as video seeking, and takes an exclude list of path prefixes or regular expressions in its config, as shown above. Also avoid caching opaque responses from other origins: browsers count each one as several megabytes against your storage quota.

#Testing it

1. Load the site once so the worker installs, then reload so it controls the page.
2. In developer tools, Network panel, switch to Offline.
3. Open a page you visited: it loads from the cache. Open one you never visited: the offline page appears.
4. Switch back online: the offline page reloads itself.

To start fresh, use Application, Storage, Clear site data. On a phone, airplane mode is the honest test.

#Questions

#Keep reading