Service worker lifecycle failures need recovery plans, not just installing code

Why This Matters

A service worker that fails to install or activate leaves your PWA in a broken state. The browser continues serving an outdated version, and users might not realize something went wrong. Silent failures are the worst kind—they erode trust without giving anyone a chance to fix anything.

The Lifecycle Trap

Service workers don't automatically take control. A new worker goes through three states: installing, waiting, and activating. The transition between waiting and activating only happens when:

1. No open tabs or windows are controlled by the old worker, or
2. You explicitly call self.skipWaiting() in the install handler

If an installation fails—network error, malformed manifest, runtime exception—the old worker continues serving content. Your update is effectively blocked.

Recovery Checklist

Detect failed installations:

// In your install handler
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('v2').then((cache) => {
      return cache.addAll([
        '/',
        '/offline.html'
      ]);
    }).catch((error) => {
      // Track this error
      console.error('Service worker install failed:', error);
      throw error; // Let installation fail explicitly
    })
  );
});

Handle update conflicts:

// Track when a new worker is waiting
const isUpdateAvailable = () => {
  return navigator.serviceWorker.getRegistration().then((registration) => {
    return registration && registration.waiting;
  });
};

// Prompt users when an update is available
if (isUpdateAvailable()) {
  showUpdatePrompt();
}

Graceful degradation without a worker:

Your PWA should still work when the service worker is broken. Serve a cached shell or fall back to network. Don't block all user actions just because the worker failed.

When to Use skipWaiting()

Calling self.skipWaiting() in your install handler:

✅ Use it for:

• Critical security patches that need immediate deployment
• Bug fixes that prevent users from completing core tasks
• Updates that don't break in-progress operations

❌ Don't use it for:

• Major UI overhauls that might confuse users mid-session
• Data migration that could corrupt in-progress transactions
• Updates that change the API contracts your client pages depend on

Monitor and Alert

Track service worker health in production:

• Log installation failures to your error tracking
• Measure the time between new versions rolling out and users adopting them
• Alert if the waiting worker stays waiting too long (indicates stuck installs)

For Developers

The service worker lifecycle is a deferred-update system Lean into it. Design updates to be compatible with the previous version for at least one release cycle. This gives you the safety net of automatic rollback if something breaks.

Next Steps

1. Add error tracking to your service worker install handler
2. Implement a user-facing update prompt for waiting workers
3. Test failure scenarios: network cuts off mid-install, malformed cache entry, runtime exceptions
4. Build a "service worker health" dashboard for your production PWAs

Your PWA's reliability depends on how it handles the unexpected, not just how it performs when everything works.