The team adds a manifest.json and the “install” button shows up in Chrome. They check the PWA box on the requirements doc. The first user takes the app on a flight and it stops working at the gate: a blank white page, no offline UI, no cached assets, no useful error. The “PWA” was decoration; the offline experience was never built.

Real PWAs need a service worker that does the work: cache the shell, serve cached responses when offline, queue mutations to retry later, fall back to a useful UI when navigation fails. About 80 lines of JavaScript. This post is the working pattern, the three traps that catch teams the first time they ship, and how to debug it.

What a service worker is

A service worker is a JavaScript file that runs outside your page, in its own thread, with a lifecycle the browser controls. It can intercept network requests for the pages it controls and decide what to do with them: serve from cache, fetch fresh, queue for retry.

Three lifecycle events you care about:

• install: fires when a new service worker is installed (or updated). The right time to pre-cache the app shell.
• activate: fires when the new service worker takes control. Right time to clean up old caches.
• fetch: fires for every request the service worker controls. Decide what to do.

The service worker is registered from your main page:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js').catch(console.error);
}

That’s it for the page side. The interesting code lives in /sw.js.

A working service worker (~80 lines)

// /sw.js
const CACHE_NAME = 'app-v3';
const APP_SHELL = [
  '/',
  '/index.html',
  '/css/main.css',
  '/js/app.js',
  '/offline.html',     // the page we serve if all else fails
];

// 1. Pre-cache the shell on install.
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => cache.addAll(APP_SHELL)),
  );
  self.skipWaiting();   // activate immediately, do not wait for old SW to die
});

// 2. Clean up old caches on activation.
self.addEventListener('activate', (event) => {
  event.waitUntil((async () => {
    const names = await caches.keys();
    await Promise.all(names
      .filter((n) => n !== CACHE_NAME)
      .map((n) => caches.delete(n)));
    await self.clients.claim();
  })());
});

// 3. Decide how to handle each request.
self.addEventListener('fetch', (event) => {
  const { request } = event;

  // Navigations: try network, fall back to cache, fall back to /offline.html.
  if (request.mode === 'navigate') {
    event.respondWith((async () => {
      try {
        const fresh = await fetch(request);
        const cache = await caches.open(CACHE_NAME);
        cache.put(request, fresh.clone()); // refresh cache in background
        return fresh;
      } catch {
        return (await caches.match(request)) || (await caches.match('/offline.html'));
      }
    })());
    return;
  }

  // Static assets (CSS, JS, images): cache-first, fall back to network.
  if (/\.(css|js|png|jpg|svg|woff2)$/.test(new URL(request.url).pathname)) {
    event.respondWith((async () => {
      const cached = await caches.match(request);
      if (cached) return cached;
      try {
        const fresh = await fetch(request);
        const cache = await caches.open(CACHE_NAME);
        cache.put(request, fresh.clone());
        return fresh;
      } catch {
        return new Response('', { status: 504 });
      }
    })());
    return;
  }

  // API requests: network-first; do NOT serve stale data by default.
  if (new URL(request.url).pathname.startsWith('/api/')) {
    event.respondWith(fetch(request).catch(() => new Response(JSON.stringify({
      error: 'offline',
    }), { status: 503, headers: { 'Content-Type': 'application/json' } })));
    return;
  }

  // Default: just go to the network.
});

The pattern: different request types get different strategies.

• Navigations (HTML pages): network-first with cache fallback. Keeps content fresh; falls back when offline.
• Static assets: cache-first. Never hit network for things that don’t change.
• API: network-only with offline error. Don’t serve stale data and pretend it’s fresh.

The three traps

1. Forgetting skipWaiting and clients.claim. Without them, a new service worker waits for all tabs of the old one to close before activating. Users get the old version until they restart their browser. Painful for fixing bugs.

2. Pre-caching too much. APP_SHELL with 50 files means the install hangs on a slow connection. Pre-cache only what’s needed for first paint; lazy-cache the rest on first use.

3. Caching API responses. Tempting and dangerous. The user’s profile is cached for 30 minutes, they update it, and they see the old data. Either don’t cache APIs, or cache them with explicit invalidation. Most teams should default to “don’t cache APIs.”

Update lifecycle

When you ship a new service worker, the browser downloads it, but doesn’t activate it until all old tabs are closed (unless you call skipWaiting). For a smooth update:

// In your page:
navigator.serviceWorker.register('/sw.js').then((reg) => {
  reg.addEventListener('updatefound', () => {
    const newSW = reg.installing;
    newSW.addEventListener('statechange', () => {
      if (newSW.state === 'installed' && navigator.serviceWorker.controller) {
        // New version available. Show a banner.
        showUpdateBanner(() => newSW.postMessage({ type: 'SKIP_WAITING' }));
      }
    });
  });
});

// In sw.js:
self.addEventListener('message', (e) => {
  if (e.data?.type === 'SKIP_WAITING') self.skipWaiting();
});

Now the user gets a “new version available, refresh” banner instead of mysterious behavior.

Background sync for mutations

A user submits a form while offline. Naive: lose the data. Better: queue the request, retry when online.

// In your page when submitting:
async function submitOfflineSafe(url, data) {
  try {
    return await fetch(url, { method: 'POST', body: JSON.stringify(data) });
  } catch {
    // Save to IndexedDB and ask the SW to sync when online.
    await db.outbox.add({ url, data, at: Date.now() });
    const reg = await navigator.serviceWorker.ready;
    if ('sync' in reg) await reg.sync.register('sync-outbox');
  }
}

// In sw.js:
self.addEventListener('sync', (event) => {
  if (event.tag === 'sync-outbox') {
    event.waitUntil(processOutbox());
  }
});

async function processOutbox() {
  const items = await db.outbox.getAll();
  for (const item of items) {
    try {
      await fetch(item.url, { method: 'POST', body: JSON.stringify(item.data) });
      await db.outbox.delete(item.id);
    } catch { /* leave in outbox; retry on next sync */ }
  }
}

Background Sync API is supported on Chromium-based browsers. Safari and Firefox do not support it (yet); fall back to retrying when the user reopens the page.

Push notifications

A separate API, not strictly part of “offline.” But often paired with PWAs:

self.addEventListener('push', (event) => {
  const data = event.data?.json() ?? {};
  event.waitUntil(self.registration.showNotification(data.title, {
    body: data.body,
    icon: '/icon-192.png',
  }));
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(self.clients.openWindow(event.notification.data.url));
});

Push notifications need a backend that holds Web Push subscriptions and a key pair (VAPID). It is more involved than the service worker itself.

Workbox, if you want batteries included

Workbox is a Google library that wraps service worker patterns: routing, runtime caching, precaching, background sync. The 80-line example above can be expressed in a few Workbox calls:

import { precacheAndRoute } from 'workbox-precaching';
import { registerRoute } from 'workbox-routing';
import { NetworkFirst, CacheFirst } from 'workbox-strategies';

precacheAndRoute(self.__WB_MANIFEST);
registerRoute(({ request }) => request.mode === 'navigate', new NetworkFirst());
registerRoute(({ request }) => request.destination === 'image', new CacheFirst());

For most teams, Workbox is the right call: well-tested, handles edge cases. The from-scratch version above is for understanding.

Debugging

Service workers are notoriously confusing to debug. The tools:

• Chrome DevTools → Application → Service Workers: see the registered SW, force update, simulate offline, check cache contents.
• chrome://serviceworker-internals/: more technical view.
• DevTools → Network → "Service Worker" filter: see which requests the SW served vs which went to network.

Common debug situation: “I changed sw.js but the old version is still running.” Check that you bumped the cache name (app-v3 → app-v4) and skipWaiting is being called.

When NOT to add a service worker

A few cases where the cost outweighs the benefit:

• No real offline use case. A B2B SaaS where users always have internet doesn’t need offline.
• Heavy real-time features. A video conferencing app’s offline experience is “the call dropped.” Don’t pretend otherwise.
• You don’t have time to maintain it. A misbehaving service worker can brick your site in production. If you ship one, also build the kill switch (navigator.serviceWorker.register('/sw.js') + an emergency unregister plan).

For most consumer apps with a meaningful chance of users being offline, a service worker is worth the investment.

The takeaway

A real PWA is the service worker, not the manifest. ~80 lines of code gets you cache the shell, serve assets offline, navigation fallbacks. Add background sync for mutations, push for notifications. Use Workbox if you want production-quality strategies without writing them yourself.

The first time a user opens your app on the subway and the dashboard renders without a network, that is the moment the PWA conversation pays off. Until then, it is just a manifest.json.

A note from Yojji

The kind of frontend engineering that turns “we have a PWA” from a checkbox into a meaningful offline experience is the kind of careful work Yojji’s teams build into the products they ship for clients.

Yojji is an international custom software development company founded in 2016, with teams across Europe, the US, and the UK. They specialize in the JavaScript ecosystem (React, Node.js, TypeScript), cloud platforms (AWS, Azure, GCP), and full-cycle product engineering, including the offline and PWA work that decides whether an app feels resilient or fragile.