EVERYTHING
I WISH I KNEW
BEFORE SHIPPING
A PWA

It's Not a Cache. It's a Programmable Proxy.

When I first learned service workers, it was easy to file them next to localStorage - as a smarter cache. In production, that mental model can create hard-to-debug issues. A more reliable model is this: a service worker is a persistent, origin-scoped reverse proxy written in JavaScript that runs in a separate thread and outlives any page.

Think of it the way you'd think about an nginx config that you deploy once and that independently handles every request to your domain - except it's running in the user's browser, you cannot SSH into it, it updates asynchronously, and it can keep running even after the user closes all your tabs.

The Lifecycle Is a State Machine, Not a Simple Sequence

The docs show install → activate → fetch as a neat waterfall. Reality is messier.

• A new SW sits in waiting state indefinitely if any controlled client (tab) is open. Spec - WHATWG SW spec §7.3. A user who opened your app days ago and never closed the tab is blocking the update for every session on that device.
• The install event fires in a ServiceWorkerGlobalScope - no DOM, no window, no document. Spec. Obvious in hindsight, but this still catches many of us at least once when we try to read window.location.
• Between install completing and activate firing, the old SW remains in control. Spec. Two workers exist simultaneously. Any shared state (IndexedDB, Cache API) is accessible by both.
• After activation, existing clients remain controlled by the old SW until they navigate. Spec §7.9. Even after a new SW is "active," multiple SW versions can be handling requests from the same user concurrently across different tabs.

// What "waiting" looks like from the inside
self.addEventListener('install', (event) => {
  // The OLD SW is still handling ALL requests right now.
  // This SW is installed but not yet active.
  // Per spec (SW §7.3), it waits until every client
  // controlled by the old SW has been navigated or closed.
  // On mobile, where tabs are rarely closed, this can be days.
  event.waitUntil(precache());
});
sw.js

The Event Loop Is Separate - And It Has Teeth

Your SW runs in a ServiceWorkerGlobalScope - a separate event loop from both the page and from other workers. This has non-obvious consequences:

• event.waitUntil() keeps the SW alive until a promise settles - it does not provide a response. Spec. In a fetch handler, event.respondWith() supplies the response; waitUntil is for extending the worker's lifetime for background work (cache writes, analytics) that should outlive the response. Without it, the runtime may terminate the SW once it considers the event handled. The confusion: DevTools keeps the SW alive permanently during development, masking this in local testing.
• Module-level variables are reset after the SW is terminated - not after every event. Spec. The SW may stay alive across multiple sequential events without being killed. But when the browser does terminate it (which can happen at any idle point), the next wake starts from a clean global scope. Never rely on JS variables surviving across event handlers - use Cache API or IndexedDB for any state that must persist.
• Race conditions are structural, not bugs. Spec / Field. The fetch event can fire before activate completes on first install. Navigation preload responses can arrive before the SW is fully awake. These are normal operating conditions, not edge cases.

Why It "Feels Unpredictable"

SWs can feel random or flaky at first. It is not random - the SW's behaviour is a function of state you cannot observe: which version is installed, which tabs are open, how long ago the SW last woke, what the browser's eviction policy did to the cache overnight. When invisible variables change, behaviour changes. The fix is making this state observable - covered in section 7.

Common Production Failures

These are not hypotheticals. Each one is based on real production behavior seen in shipped apps.

When Every Strategy Fails

The Workbox docs present five strategies like menu items. What they omit are the conditions under which each one will cause a production incident.

The HTML/JS Chunk Version Mismatch Problem

This is the most under-documented failure mode in PWA engineering. Here is the exact sequence:

• User has index.html (v1) served and cached. It references app.a1b2c3.js.
• You deploy. New index.html references app.d4e5f6.js. Old chunk is no longer on the server (some CDNs expire old hashes quickly).
• New SW installs and activates. During activate, old caches are deleted. app.a1b2c3.js is gone from both cache and network.
• User has an open tab. Old index.html is rendered. User navigates. React Router lazy-loads ProductPage.a1b2c3.js - the old name. Cache miss. Network 404. React throws. White screen.

// Defense: global chunk load error handler with reload-loop guard
window.addEventListener('unhandledrejection', (event) => {
  const err = event.reason;
  // Vite lazy chunk load failures have this signature
  if (
    err?.message?.includes('Failed to fetch dynamically imported module') ||
    err?.message?.includes('Importing a module script failed')
  ) {
    const lastReload = +localStorage.getItem('chunkErrorReload') || 0;
    const now = Date.now();
    // 30s cooldown prevents infinite reload loops on genuinely broken deploys
    if (now - lastReload > 30_000) {
      localStorage.setItem('chunkErrorReload', String(now));
      window.location.reload();
    }
  }
});
main.jsx

Cache Invalidation Is a Contract, Not a Strategy

The hardest part of SW caching is usually not choosing a strategy - it is defining an explicit contract for when a cached response is considered invalid. In my experience, if this is not written down early, it can lead to implicit, inconsistent rules across event handlers.

Before writing a single line of SW caching code, answer these questions for every resource type:

• How long is this response valid? (TTL in seconds, not "seems OK")
• What event should invalidate it immediately - deploy, user logout, user action?
• What happens if the user is offline when invalidation should have occurred?
• Is serving a stale version while revalidating acceptable for this resource?

Versioning Strategies and Their Pitfalls

Approach 1: Build hash in cache name. Simple. Works. Pitfall: if you precache 20MB of assets, every deploy requires downloading all 20MB again even if only one file changed.

Approach 2: Per-file content hash in filename. Only cache-busts changed files. What Workbox precacheAndRoute with a manifest does by default. Pitfall: the manifest generation must be airtight. Any missed file means stale content served silently; any incorrectly included file is re-downloaded on every deploy.

Approach 3: Runtime caching with TTL. Resources cached on demand with expiry metadata stored alongside them. Most flexible. Pitfall: TTL logic lives inside the SW - bugs there have no easy recovery path. Also, TTL is evaluated on read, not on expiry, so you don't know a cache entry is stale until someone requests it.

Why Users Are Still on Last Month's Build

The SW update mechanism is one of the most important things to understand, and also one of the easiest to misunderstand. In real projects, update confusion can leave broken experiences in production for days.

The Two Distinct Mechanisms Behind "The 24-Hour Rule"

A common misunderstanding is that browsers check for a new SW "at most once per 24 hours." This collapses two separate mechanisms into one and produces a misleading picture. Here is what actually happens:

// Force an update check when tab regains focus
// Catches long-lived tabs and sessions resumed after hours
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'visible') {
    navigator.serviceWorker.ready.then((reg) => {
      reg.update(); // triggers an explicit update check for sw.js
    });
  }
});
main.jsx

What skipWaiting() Actually Does - And What It Doesn't

The docs make skipWaiting() sound like a convenience method. It is a takeover operation. Here is the precise sequence:

1. Calling self.skipWaiting() from a waiting SW immediately transitions it to activating, bypassing the normal wait for all clients to close.
2. Fetch events that have already called respondWith() continue to completion normally - they are not dropped.
3. Fetch events that have not yet called respondWith() may be dropped - but this is a narrow window and the principal risk is elsewhere.
4. The real danger: pages whose HTML was served by the old SW (with old content-hashed asset filenames) are now controlled by the new SW. When those pages lazily load chunks, the new SW may not have the old chunk filenames in its precache. Result: 404, runtime error, white screen.

When to use it: The new SW is fully backwards-compatible with any page the old SW could have served. You have a reload-after-claim flow (see below). You are willing to accept rare mid-session disruption.

When not to use it: The new SW deletes old asset versions from cache during activate. The user may be mid-transaction (payment, form). You have not implemented the reload-after-claim flow.

The Clean Update Pattern

// sw.js - controlled update flow
self.addEventListener('install', (e) => {
  e.waitUntil(precache()); // cache new assets
  // Do NOT call skipWaiting() here unconditionally.
  // Wait for an explicit user-confirmed signal.
});

self.addEventListener('activate', (e) => {
  e.waitUntil(
    // Clean up old versioned caches - but NOT if you plan to use skipWaiting,
    // because old-SW-served pages may still need the old assets.
    // Only delete caches once you know all clients have reloaded.
    cleanOldCaches()
  );
});

self.addEventListener('message', (e) => {
  if (e.data === 'SKIP_WAITING') {
    self.skipWaiting(); // only called after user confirms "Reload"
  }
});

// main.jsx - full update handshake
let waitingSW = null;

// Step 3: page reloads AFTER new SW has taken control
navigator.serviceWorker.addEventListener('controllerchange', () => {
  window.location.reload();
});

registration.addEventListener('updatefound', () => {
  const newSW = registration.installing;
  newSW.addEventListener('statechange', () => {
    if (newSW.state === 'installed' && navigator.serviceWorker.controller) {
      waitingSW = newSW;
      showUpdateBanner(); // "New version available - Refresh"
    }
  });
});

// User clicks "Refresh" in the banner
function applyUpdate() {
  waitingSW?.postMessage('SKIP_WAITING');
  // controllerchange fires → window.location.reload() above
}
sw.js + main.jsx

Multi-Tab Synchronisation Is Your Problem

The browser does not coordinate SW updates across tabs. Tab 1 triggers an update check. New SW installs, waits. User closes Tab 2 (the one keeping it in waiting). New SW activates. Tabs 1 and 3 are now controlled by the new SW. Tab 4, opened from a cached navigation, may still be on the old SW for that session.

Use the BroadcastChannel API or clients.matchAll() from the SW to coordinate and notify all tabs simultaneously. When this is skipped, it is common to see the same user end up with split state across tabs.

The Illusion of Infinite Cache

Storage Limits - Observed Behaviour, Not Guarantees Browser

Browsers do not publish contractual storage quotas. The numbers below are derived from documentation, storage API responses, and observed production behaviour. Treat them as approximations - especially Safari, which explicitly uses adaptive quota allocation based on total disk space.

Cache API vs IndexedDB - Real Tradeoffs

• Using Cache API for application state - technically works, but you are serialising objects into Response bodies. Querying by field requires reading everything out. Use IndexedDB for structured data.
• Using IndexedDB for assets - possible, but the Cache API integrates naturally with fetch interception and is more efficient for binary HTTP responses.
• IDB transaction auto-commit - a subtle data-loss trap. Spec - IDB §3.7: transactions commit when there are no more pending requests and the current event loop task is complete. If you await something unrelated between IDB operations, the transaction may have already auto-committed. Subsequent writes throw an InvalidStateError. Whether this surfaces as an observable error depends entirely on whether the calling code has a catch block - without one, it is effectively silent. This is the most common IDB production bug and its error message rarely points to the root cause.

Opaque Responses and Storage Quota - The 7 MB Accounting Quirk Browser

The "opaque responses take 7 MB in cache quota" claim that circulates online requires careful clarification. The response itself is not padded to 7 MB. Rather, Chromium's Cache API implementation charges a minimum of 7 MB of quota for any opaque (cross-origin, no CORS) cached response, regardless of its actual size. This is a conservative accounting mechanism to prevent attackers from inferring cross-origin response sizes through quota measurements. The actual bytes stored may be far smaller, but your quota is charged as if it were 7 MB. Chromium behaviour - Firefox/Safari differ

The practical advice is unchanged: never cache opaque responses. But the mechanism is quota accounting, not storage inflation.

Security Risks to Plan For

A service worker with a bug is not just a broken feature. It is a persistent, origin-level man-in-the-middle proxy that you installed in your user's browser and cannot easily remove. - From a production XSS incident postmortem

Cache Poisoning via SW

If your SW caches responses without validating them, an attacker who achieves any MITM position (compromised CDN edge, malicious Wi-Fi, BGP hijack) can inject a malicious response that gets cached by your SW and served to the user long after the MITM position is gone. The attacker achieves persistent presence without persistent network access.

Defense: only cache responses where response.ok === true and response.type === 'basic' (same-origin). It is usually safer not to cache opaque responses - you cannot inspect their status or content. If you must cache third-party content, validate a content hash on retrieval.

// Refuse to cache opaque or error responses
async function safePut(cache, request, response) {
  if (response.type === 'opaque') {
    // Opaque: status is always 0. Could be a 200 or a 503 or injected content.
    // You have no way to tell. Refuse to cache.
    console.warn('Refusing to cache opaque response for', request.url);
    return;
  }
  if (!response.ok) return; // never cache 4xx / 5xx
  await cache.put(request, response);
}
sw.js

Persistent XSS via Service Worker

Classic XSS injects code into a page - it vanishes on reload. XSS that registers a service worker (or modifies an existing one's cache) achieves persistent XSS. The injected code can survive navigation and browser restart. Field. Remediation options include clearing all site data for the origin, unregistering the compromised SW via a "kill switch" deployment, or pushing a corrective SW update that cleans the poisoned cache - clearing site data is the most complete option but not always the only one.

This is why your SW file should be served with a strict Content-Security-Policy header and should not be dynamically generated or templated from any user-controlled input. A SW file that includes user-controlled data is a critical vulnerability, not a minor misconfiguration.

Auth Tokens in Cache - Silent PII Exposure

It is common to cache authenticated API responses without fully considering sensitivity. A cached response for GET /api/user/profile containing PII sits in Cache API storage. On a shared device, or after logout without cache purging, another user on the same device can potentially access it - especially if the SW does not gate cached responses on auth state.

Rule: On every logout event, explicitly clear all caches containing user-specific data. Scope user-data caches separately from your app-shell cache so you can delete them surgically without invalidating static assets.

The SW Scope Hijack Risk

A SW registered at / controls all requests from that origin. On platforms where users can upload content to paths like yourapp.com/uploads/, improperly validated HTML+JS file uploads at that path could register a SW controlling the entire origin. Modern browsers enforce that a SW can only control pages within its script's directory and below, and the Service-Worker-Allowed response header controls the maximum scope. Audit your upload endpoints and ensure uploaded content cannot be served with a content-type that triggers SW registration.

Seeing Inside the Black Box

Why SW Debugging Is Painful

Your SW runs in a separate thread with its own DevTools session. Breakpoints in the SW do not pause the page. The SW can be killed and restarted by the browser mid-debug. The DevTools "Application" tab shows you the currently registered SW but not the history of what it has served, what cache decisions it made, or why it returned a particular response. You are debugging a stateful proxy with no access log and no audit trail.

Useful DevTools Techniques

• "Update on reload" in DevTools Application tab - forces the SW to update on every page reload. Essential for development. But it changes SW lifecycle behaviour significantly: the waiting state is bypassed entirely. Try to avoid benchmarking or testing timing-sensitive update flows with this enabled. Production behaviour will differ.
• SW-specific breakpoints - in Sources, set breakpoints directly in sw.js. The SW has its own DevTools instance: click "inspect" next to the service worker in Application → Service Workers. Breakpoints there pause the SW thread independently of the page.
• Cache Storage inspector - Application → Cache Storage. Inspect every cached request/response pair including full headers and body. Manually delete entries to test cold-start behaviour. This is the fastest way to verify what is actually in the cache versus what you think is there.
• DevTools offline checkbox is not real offline - it blocks page-context network requests but may not block SW background sync or periodic sync fetches in all browsers. For accurate offline testing, use OS-level network disabling or a proxy tool.

Production Logging Strategy

console.log from a SW goes to the SW's DevTools console - invisible in production. The solution is forwarding logs to page clients and from there to your analytics pipeline:

// sw.js - forward structured logs to all controlled clients
async function swLog(level, ...args) {
  const clients = await self.clients.matchAll({ includeUncontrolled: true });
  const message = args.map(String).join(' ');
  clients.forEach((client) =>
    client.postMessage({
      type: 'SW_LOG',
      level,
      message,
      swVersion: SW_VERSION, // injected at build time
      timestamp: Date.now(),
    })
  );
}

// main.jsx - receive and forward to analytics
navigator.serviceWorker.addEventListener('message', (e) => {
  if (e.data?.type === 'SW_LOG') {
    analytics.track('sw_event', {
      level: e.data.level,
      message: e.data.message,
      sw_version: e.data.swVersion,
      timestamp: e.data.timestamp,
    });
  }
});
sw.js + main.jsx

Building a Mobile Debug Overlay

When a bug only reproduces on a specific physical device (as in the OAuth postmortem), the fastest path is a floating overlay rendering console output on-screen. Gate it to dev/staging only via a flag:

// MobileConsole.jsx - gate to dev/staging via env var or URL param
const [logs, setLogs] = useState([]);

useEffect(() => {
  if (!isDebugMode()) return;
  const origLog = console.log;
  const origError = console.error;
  const capture = (prefix) => (...args) => {
    origLog(...args);
    setLogs((prev) => [...prev.slice(-100), `[${prefix}] ` + args.join(' ')]);
  };
  console.log = capture('LOG');
  console.error = capture('ERR');
  return () => { console.log = origLog; console.error = origError; };
}, []);
MobileConsole.jsx

Safari Is a Different Planet

Chrome and Firefox have largely converged on SW behaviour. Safari is its own ecosystem, shaped in part by Apple's constraints on the platform. If you are shipping to iOS users, it helps to learn these differences early. The table below reflects behaviour as tested in the versions indicated - browser support changes; treat this as a snapshot.

iOS Safari PWA Quirks - Precisely Documented

• Each installed PWA on iOS gets an isolated storage context. Browser - verified iOS 17. Cookies, localStorage, IndexedDB, and SW registrations are not shared between the installed PWA and Safari browser - they are separate storage buckets. However, they share the same origin and network stack. Auth sessions set in Safari are invisible to the PWA. OAuth must complete within the PWA context specifically - test there, not in Safari browser.
• iOS PWAs relaunch from start_url on resume. If a user backgrounds the PWA and returns after a while, iOS relaunches from the start_url in the manifest, not from wherever they were. Unsaved state is lost. Deep linking and "continue where you left off" require explicit state persistence.
• theme_color in the manifest is ignored on iOS. Status bar styling requires <meta name="apple-mobile-web-app-status-bar-style"> instead. The manifest property works on Chrome Android.
• Full-screen video behaviour differs. The native iOS video player takes over in PWA standalone mode but not in Safari browser mode. Custom video controls require special handling.
• EU policy churn in iOS 17.4 caused brief PWA uncertainty. As of early 2026, full iOS PWA capabilities (offline, push, install UX) still effectively depend on WebKit PWAs installed through Safari.

Beyond the Basic Fetch Interceptor

Navigation Preload - The Hidden Performance Win

By default, when a user navigates to a page, the browser must wake the SW before any network request is made for the document. On a cold SW start, this adds 50–500 ms of latency to every navigation, making your PWA feel slower than a regular website. Navigation preload solves this by starting the document fetch in parallel with SW startup:

// Enable navigation preload in activate
// Supported: Chrome, Firefox, Safari 15.4+. Safe to enable universally.
// The optional chaining handles browsers where navigationPreload is undefined.
self.addEventListener('activate', (event) => {
  event.waitUntil(
    self.registration?.navigationPreload?.enable()
  );
});

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

  event.respondWith((async () => {
    // preloadResponse is already in-flight before the SW woke up
    const preload = await event.preloadResponse;
    if (preload) return preload;
    // Fallback: normal network fetch
    return fetch(event.request);
  })());
});
sw.js

Background Sync - Offline Mutations Done Right

Background Sync lets you queue mutations while offline and replay them when connectivity returns - even if the tab is closed. The pattern: user submits a form → SW intercepts → network fails → SW registers a sync tag → browser wakes the SW on reconnect → SW replays the queued request.

What examples omit: you need idempotency keys on your API endpoints to handle re-delivery. You need a max-retry policy and exponential backoff. You need a way to surface replay results to a UI that may not have an open tab (use Push Notifications or Badge API where available). And the API is only reliably available on Chrome/Edge - design a synchronous fallback for Firefox and Safari.

Streaming Responses Through the SW

The SW can construct a streaming Response using ReadableStream, enabling the "app shell + content stream" architecture: serve the first part of a response from cache (the shell HTML) and stream the rest from network. This eliminates the "blank flash" before content appears and produces measurable 100–300 ms improvements in perceived navigation latency on typical connections. It is complex to implement correctly and requires careful handling of stream cancellation.

Workbox - Honest Assessment

Honest take: Workbox is excellent when you want offline capability without deep SW expertise on day one. It can become a liability when requirements diverge from its defaults, because you end up fighting the abstraction. For critical flows - auth callbacks, payment pages, any route where version mismatch is costly - write those handlers manually regardless of whether you use Workbox elsewhere. Understand the lifecycle before you rely on the abstraction.

Helpful Things to Keep in Mind

Twenty things that often take real time to learn in production. Claims are marked where they distinguish spec from field experience.