Service Worker Lifecycle

Technical Deep Dive & Specifications

The Service Worker State Machine

A Service Worker is an event-driven JavaScript worker running on the ServiceWorkerGlobalScope. It has no synchronous access to window or the DOM (document), communicating with pages exclusively via postMessage or network interception.

                  +-----------------------------------+
                  |   navigator.serviceWorker.        |
                  |          register()               |
                  +-----------------------------------+
                                    |
                                    v
+------------------+      +-------------------+
|      PARSED      | ===> |    INSTALLING     | (install event: Precaching assets)
+------------------+      +-------------------+
                                    |
                 +------------------+------------------+
                 | (Install Fails)                     | (Install Succeeds)
                 v                                     v
       +-------------------+                 +-------------------+
       |     REDUNDANT     |                 |  INSTALLED / WAIT | (Waiting for existing
       +-------------------+                 +-------------------+  tabs to close)
                                                       |
                                    +------------------+
                                    | (Old SW dies OR self.skipWaiting())
                                    v
                          +-------------------+
                          |    ACTIVATING     | (activate event: Purging old caches)
                          +-------------------+
                                    |
                                    v
                          +-------------------+
                          |      ACTIVE       | (fetch, sync, push events)
                          +-------------------+
                                    |
                                    | (Replaced by New Worker)
                                    v
                          +-------------------+
                          |     REDUNDANT     | (Old worker destroyed)
                          +-------------------+

Lifecycle Phases Explained

The Scope Rule & Directory Inheritance

A Service Worker can only control pages within its own directory scope or subdirectories. It can never control parent directories unless explicitly permitted via the Service-Worker-Allowed HTTP response header:

File Location: /js/sw.js
Default Maximum Scope: /js/*
Will NOT control: /index.html or /dashboard/

File Location: /sw.js (At Root)
Default Maximum Scope: /*
Controls: All pages on the entire origin!

skipWaiting() vs clients.claim() Matrix

                          +----------------------------------------------+
                          |             CLIENT BROWSER TABS              |
                          |   [ Tab 1: v1.0 ]          [ Tab 2: v1.0 ]   |
                          +----------------------------------------------+
                                                 ^
                                                 | (Controlled by)
+------------------------+             +-------------------+
|  NEW WORKER (v2.0)     |             |  OLD WORKER (v1.0)|
|  Calls: skipWaiting()  |             |      ACTIVE       |
+------------------------+             +-------------------+
           |                                     |
           +============ Kills & Replaces =======+
           |
           v
+------------------------+
|  NEW WORKER (v2.0)     |
|      ACTIVATED         |
|  Calls: clients.claim()| === Immediate control of Tab 1 & Tab 2 without reload!
+------------------------+

• self.skipWaiting(): Forces the waiting worker to activate immediately, bypassing the requirement that all active tabs be closed.
• self.clients.claim(): Tells an activated worker to immediately take control of all uncontrolled or legacy-controlled open tabs without requiring those pages to be refreshed.

💻 Interactive Code Playground

Starter Code: Production Service Worker Harness

1. File: app.js (Main UI Thread)

2. File: sw.js (Service Worker Background Thread)

Line-by-Line Code Breakdown

• app.js Line 5 (registration.scope): The path prefix over which this Service Worker intercepts network requests.
• app.js Line 13 (registration.addEventListener('updatefound')): Fires whenever a byte-level difference is detected in sw.js during page load.
• app.js Line 31 (navigator.serviceWorker.addEventListener('controllerchange')): Fires when the active controlling worker changes; provides a reliable trigger to reload the DOM without race conditions.
• sw.js Line 11 (event.waitUntil(...)): Extends the lifecycle phase until the passed promise resolves; prevents the browser from terminating the worker prematurely.
• sw.js Line 29 (self.clients.claim()): Instructs the newly activated worker to immediately begin controlling open tabs without waiting for subsequent navigations.
• sw.js Line 37 (self.skipWaiting()): Causes the waiting worker to advance directly into the active state.

Expected Browser Render Output

// Register Service Worker and monitor lifecycle state changes
if ('serviceWorker' in navigator) {
  window.addEventListener('load', async () => {
    try {
      const registration = await navigator.serviceWorker.register('/sw.js');
      console.log('[UI] SW Registered with scope:', registration.scope);

      // Check if an update is already waiting
      if (registration.waiting) {
        notifyUserOfUpdate(registration.waiting);
      }

      // Detect future updates
      registration.addEventListener('updatefound', () => {
        const installingWorker = registration.installing;
        console.log('[UI] New service worker installing...');

        installingWorker.addEventListener('statechange', () => {
          if (installingWorker.state === 'installed' && navigator.serviceWorker.controller) {
            console.log('[UI] New version installed and waiting for activation.');
            notifyUserOfUpdate(installingWorker);
          }
        });
      });

    } catch (error) {
      console.error('[UI] SW registration failed:', error);
    }
  });

  // Listen for the controllerchange event when a new SW activates
  let refreshing = false;
  navigator.serviceWorker.addEventListener('controllerchange', () => {
    if (!refreshing) {
      refreshing = true;
      console.log('[UI] Controller changed! Auto-reloading client to load fresh assets.');
      window.location.reload();
    }
  });
}

function notifyUserOfUpdate(worker) {
  const updateBanner = document.createElement('div');
  updateBanner.style.cssText = 'position:fixed;bottom:20px;right:20px;background:#2563eb;color:white;padding:1rem;border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.3);z-index:9999;';
  updateBanner.innerHTML = `
    <span>A new version is available!</span>
    <button id="reload-btn" style="margin-left:10px;background:white;color:#2563eb;border:none;padding:5px 10px;border-radius:4px;cursor:pointer;font-weight:bold;">Update Now</button>
  `;
  document.body.appendChild(updateBanner);

  document.getElementById('reload-btn').addEventListener('click', () => {
    // Send postMessage to tell waiting worker to call skipWaiting()
    worker.postMessage({ type: 'SKIP_WAITING' });
  });
}

const CACHE_NAME = 'app-cache-v2';
const ASSETS_TO_CACHE = [
  '/',
  '/index.html',
  '/styles.css',
  '/app.js',
  '/logo.svg'
];

// 1. INSTALL PHASE: Precache assets
self.addEventListener('install', (event) => {
  console.log('[SW] Install event triggered. Caching static shell...');
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => {
      return cache.addAll(ASSETS_TO_CACHE);
    })
  );
});

// 2. ACTIVATE PHASE: Delete old cache versions
self.addEventListener('activate', (event) => {
  console.log('[SW] Activate event triggered. Cleaning legacy caches...');
  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames.map((name) => {
          if (name !== CACHE_NAME) {
            console.log('[SW] Deleting obsolete cache bucket:', name);
            return caches.delete(name);
          }
        })
      );
    }).then(() => {
      // Claim all open clients immediately
      console.log('[SW] Claiming clients...');
      return self.clients.claim();
    })
  );
});

// 3. LISTEN FOR SKIP_WAITING MESSAGE
self.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'SKIP_WAITING') {
    console.log('[SW] Received SKIP_WAITING signal. Activating immediately...');
    self.skipWaiting();
  }
});

// 4. FETCH PHASE: Intercept network traffic
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((cachedResponse) => {
      return cachedResponse || fetch(event.request);
    })
  );
});

[UI] SW Registered with scope: https://example.com/
[SW] Install event triggered. Caching static shell...
[SW] Activate event triggered. Cleaning legacy caches...
[SW] Deleting obsolete cache bucket: app-cache-v1
[SW] Claiming clients...

(When user clicks [Update Now] banner):
[SW] Received SKIP_WAITING signal. Activating immediately...
[UI] Controller changed! Auto-reloading client to load fresh assets.