Service Worker API

// Check support & register
if ("serviceWorker" in navigator) {
  navigator.serviceWorker.register("/sw.js");
}

// Register with custom scope
navigator.serviceWorker.register("/sw.js", {
  scope: "/app/",
});
// Returns: Promise<ServiceWorkerRegistration>

navigator.serviceWorker
  .register("/sw.js")
  .then((reg) => {
    console.log("Registered:", reg.scope);
  })
  .catch((error) => {
    console.error("Failed:", error);
  });

const CACHE = "v1";

self.addEventListener("install", (event) => {
  event.waitUntil(
    caches
      .open(CACHE)
      .then((cache) =>
        cache.addAll(["/", "/index.html", "/style.css", "/app.js"]),
      ),
  );
});

Pre-cache critical assets during installation.

self.addEventListener("activate", (event) => {
  const keep = ["v2"];
  event.waitUntil(
    caches
      .keys()
      .then((keys) =>
        Promise.all(
          keys.filter((k) => !keep.includes(k)).map((k) => caches.delete(k)),
        ),
      ),
  );
});

Clean up old caches on activation.

self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches
      .match(event.request)
      .then((cached) => cached || fetch(event.request)),
  );
});

Intercept network requests.

self.addEventListener("message", (event) => {
  console.log("Message:", event.data);
  event.source.postMessage("Reply");
});

Communicate with client pages.

self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches
      .match(event.request)
      .then((cached) => cached || fetch(event.request)),
  );
});

Serve from cache, fallback to network.

self.addEventListener("fetch", (event) => {
  event.respondWith(
    fetch(event.request).catch(() => caches.match(event.request)),
  );
});

Try network first, fallback to cache.

self.addEventListener("fetch", (event) => {
  event.respondWith(
    caches.open(CACHE).then((cache) =>
      cache.match(event.request).then((cached) => {
        const fetched = fetch(event.request).then((response) => {
          cache.put(event.request, response.clone());
          return response;
        });
        return cached || fetched;
      }),
    ),
  );
});

Serve cached, update in background.

self.addEventListener("fetch", (event) => {
  event.respondWith(caches.match(event.request));
});

Only serve from cache.

self.addEventListener("fetch", (event) => {
  event.respondWith(fetch(event.request));
});

Always fetch from network.

caches.open(name);
// Returns: Promise<Cache>

caches.delete(name);
// Returns: Promise<boolean>

caches.keys();
// Returns: Promise<string[]>

cache.add(request);
// Returns: Promise<void>

cache.addAll(["/index.html", "/style.css", "/app.js"]);
// Returns: Promise<void>

cache.put(request, response);
// Returns: Promise<void>

cache.match(request);
// Returns: Promise<Response|undefined>

cache.matchAll(request);
// Returns: Promise<Response[]>

cache.delete(request);
// Returns: Promise<boolean>

cache.keys();
// Returns: Promise<Request[]>

// In service worker
self.addEventListener("install", (event) => {
  self.skipWaiting();
});

Activate immediately without waiting.

self.addEventListener("activate", (event) => {
  event.waitUntil(self.clients.claim());
});

Take control of all open pages.

self.addEventListener("install", (event) => {
  self.skipWaiting();
});

self.addEventListener("activate", (event) => {
  event.waitUntil(clients.claim());
});

Force immediate activation and control.

self.clients.matchAll(options)
// Returns: Promise<Client[]>

// Options
{
  includeUncontrolled: false,
  type: 'window' // 'window', 'worker', 'all'
}

self.clients.get(id);
// Returns: Promise<Client>

self.clients.openWindow(url);
// Returns: Promise<WindowClient>

self.clients.claim();
// Returns: Promise<void>

client.postMessage(message);

client.id; // string
client.type; // 'window' | 'worker'
client.url; // string
client.frameType; // 'top-level' | 'nested'

const reg = await navigator.serviceWorker.ready;

const sub = await reg.pushManager.subscribe({
  userVisibleOnly: true,
  applicationServerKey: vapidPublicKey,
});

// Send subscription to server
await fetch("/subscribe", {
  method: "POST",
  body: JSON.stringify(sub),
  headers: { "Content-Type": "application/json" },
});

Subscribe to push notifications.

self.addEventListener("push", (event) => {
  const data = event.data.json();

  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body,
      icon: data.icon,
      badge: data.badge,
      tag: data.tag,
      data: data.url,
    }),
  );
});

Handle incoming push events.

self.addEventListener("notificationclick", (event) => {
  event.notification.close();

  event.waitUntil(clients.openWindow(event.notification.data));
});

Handle notification clicks.

const reg = await navigator.serviceWorker.ready;
const sub = await reg.pushManager.getSubscription();

if (sub) {
  await sub.unsubscribe();
}

Unsubscribe from push notifications.

const reg = await navigator.serviceWorker.ready;

await reg.sync.register("sync-messages");

Register background sync task.

self.addEventListener("sync", (event) => {
  if (event.tag === "sync-messages") {
    event.waitUntil(sendOutboxMessages());
  }
});

Handle sync events.

async function sendOutboxMessages() {
  const outbox = await getOutboxMessages();

  await Promise.all(
    outbox.map((msg) =>
      fetch("/api/messages", {
        method: "POST",
        body: JSON.stringify(msg),
      }).then(() => removeFromOutbox(msg.id)),
    ),
  );
}

Process queued tasks.

reg.installing; // ServiceWorker | null
reg.waiting; // ServiceWorker | null
reg.active; // ServiceWorker | null
reg.scope; // string

reg.update();
// Returns: Promise<void>

reg.unregister();
// Returns: Promise<boolean>

reg.pushManager;
// PushManager instance

reg.sync;
// SyncManager instance

reg.showNotification(title, options);
reg.getNotifications(options);

// From page
navigator.serviceWorker.controller.postMessage({
  type: "CACHE_URLS",
  urls: ["/page1.html", "/page2.html"],
});

Send messages from page.

// In service worker
self.addEventListener("message", (event) => {
  event.source.postMessage({
    type: "CACHE_COMPLETE",
  });
});

Reply to page.

self.clients.matchAll().then((clients) => {
  clients.forEach((client) =>
    client.postMessage({
      type: "UPDATE_AVAILABLE",
    }),
  );
});

Send to all open pages.

navigator.serviceWorker.addEventListener("message", (event) => {
  if (event.data.type === "UPDATE_AVAILABLE") {
    showUpdatePrompt();
  }
});

Receive messages in page.

const CACHE_DURATION = 24 * 60 * 60 * 1000; // 24 hours

async function cachedFetch(request) {
  const cache = await caches.open(CACHE);
  const cached = await cache.match(request);

  if (cached) {
    const cachedTime = new Date(cached.headers.get("date"));
    const age = Date.now() - cachedTime.getTime();

    if (age < CACHE_DURATION) {
      return cached;
    }
  }

  const response = await fetch(request);
  cache.put(request, response.clone());
  return response;
}

Cache with time-based expiration.

self.addEventListener("fetch", (event) => {
  const url = new URL(event.request.url);

  // Only cache same-origin requests
  if (url.origin !== location.origin) {
    event.respondWith(fetch(event.request));
    return;
  }

  // Only cache GET requests
  if (event.request.method !== "GET") {
    event.respondWith(fetch(event.request));
    return;
  }

  event.respondWith(
    caches
      .match(event.request)
      .then((cached) => cached || fetch(event.request)),
  );
});

Cache only specific requests.

async function trimCache(cacheName, maxItems) {
  const cache = await caches.open(cacheName);
  const keys = await cache.keys();

  if (keys.length > maxItems) {
    await cache.delete(keys[0]);
    return trimCache(cacheName, maxItems);
  }
}

Limit cache entry count.

Application → Service Workers
- View status (activated/waiting/installing)
- Update on reload
- Bypass for network
- Unregister

Application → Cache Storage
- Inspect cached entries
- Delete caches

Chrome debugging features.

Application → Service Workers
- View registrations
- Start/stop workers
- Unregister

Storage → Cache Storage
- Browse caches
- Delete entries

Firefox debugging features.

navigator.serviceWorker.getRegistration().then((reg) => reg.update());

Manually check for updates.

navigator.serviceWorker
  .getRegistrations()
  .then((regs) => Promise.all(regs.map((reg) => reg.unregister())));

Remove all service workers.

Service Workers require HTTPS in production (localhost exempt for development).

Scope is determined by file location. /scripts/sw.js can only control /scripts/*. To control /, place at root or use Service-Worker-Allowed header.

New service worker waits until old one no longer controls clients. Use skipWaiting() + clients.claim() for immediate activation.

Service workers run in worker context. Use postMessage() to communicate with pages.

Cross-origin requests without CORS create opaque responses. These inflate cache size (may report 7MB for 1KB file).

Old caches persist unless explicitly deleted in activate event. Always clean up outdated caches.

Browser checks for updated service worker on navigation. Force check with registration.update().

If any file in cache.addAll() fails to fetch, entire installation fails. Handle errors appropriately.