agents-inc/web-pwa-service-workers

Service Worker Patterns

Quick Guide: Use Service Workers for offline-first applications with sophisticated caching. Implement cache-first for static assets, network-first for HTML, and stale-while-revalidate for API data. Always handle the install/activate/fetch lifecycle properly, version your caches, and provide user control over updates. Clone responses before caching (body can only be consumed once).

---

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST call event.waitUntil() in install and activate handlers to signal completion)

(You MUST version your caches and clean up old versions during activation)

(You MUST clone responses before caching - cache.put(request, response.clone()) - response body can only be consumed once)

(You MUST implement proper update detection and give users control over when updates apply)

(You MUST handle all fetch failures with appropriate offline fallbacks)

</critical_requirements>

---

Auto-detection: Service Worker, serviceWorker, sw.js, sw.ts, navigator.serviceWorker, caches, Cache API, CacheStorage, skipWaiting, clients.claim, precache, offline-first, PWA

When to use:

• Building Progressive Web Apps (PWAs) with offline support
• Implementing sophisticated caching strategies beyond browser defaults
• Providing offline fallback pages or cached content
• Controlling how network requests are handled and cached

When NOT to use:

• Simple websites without offline requirements
• When browser HTTP caching is sufficient
• For real-time data that must always be fresh (use network-only)

Detailed Resources:

• examples/core.md - Registration, lifecycle template, caching strategy implementations, types
• examples/caching.md - Advanced caching (expiration, selective API, storage cleanup, navigation preload)
• examples/updates.md - Version tracking, update strategies (aggressive, deferred, idle, rollout, migration)
• reference.md - Decision frameworks, anti-patterns, lifecycle reference, checklists

---

<philosophy>

Philosophy

Service Workers are programmable network proxies that run in a separate thread, intercepting requests between your application and the network. They enable offline functionality, sophisticated caching, and background operations.

The Service Worker lifecycle is designed for safety:

1. Install Phase: Download and cache critical assets. The worker is "waiting" until installation completes.
2. Waiting Phase: New workers wait for all tabs using the old worker to close, preventing version conflicts.
3. Activate Phase: Old caches are cleaned up, and the worker takes control.
4. Fetch Phase: The active worker intercepts all network requests within its scope.

Registration → Download → Install → Waiting → Activate → Fetch
                            ↓          ↓
                     (skipWaiting)  (claim)

Core Principles:

1. Safety First: The lifecycle prevents running multiple versions simultaneously, which could corrupt state.
2. User Control: Users should decide when updates apply, not be surprised by sudden behavior changes mid-session.
3. Graceful Degradation: Always provide fallbacks when network and cache both fail.
4. Cache Versioning: Version your caches to enable clean upgrades and prevent unbounded growth.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Service Worker Registration

Register from your main application with feature detection, update checking, and user-controlled updates.

const SW_PATH = "/sw.js";
const UPDATE_CHECK_INTERVAL_MS = 60 * 60 * 1000;

const registration = await navigator.serviceWorker.register(SW_PATH, {
  scope: "/",
  updateViaCache: "none", // Always check server for updates
});

// Periodic update checks
setInterval(() => registration.update(), UPDATE_CHECK_INTERVAL_MS);

// Track waiting worker for user-controlled updates
registration.addEventListener("updatefound", () => {
  const installing = registration.installing;
  installing?.addEventListener("statechange", () => {
    if (
      installing.state === "installed" &&
      navigator.serviceWorker.controller
    ) {
      // New version waiting - notify user
    }
  });
});

See examples/core.md Pattern 1 for complete registration with update tracking and reload handling.

---

Pattern 2: Lifecycle Handlers (Install / Activate / Message)

The three essential lifecycle event handlers: precache in install, cleanup in activate, user-controlled skipWaiting via message.

// Install - precache critical assets
self.addEventListener("install", (event: ExtendableEvent) => {
  event.waitUntil(
    caches.open(CACHES.static).then((cache) => cache.addAll(PRECACHE_URLS)),
  );
  // Do NOT call skipWaiting here - let user control updates
});

// Activate - cleanup old caches, claim clients
self.addEventListener("activate", (event: ExtendableEvent) => {
  event.waitUntil(
    caches
      .keys()
      .then((names) =>
        Promise.all(
          names
            .filter((n) => !currentCaches.includes(n))
            .map((n) => caches.delete(n)),
        ),
      )
      .then(() => self.clients.claim()),
  );
});

// Message - user-controlled skipWaiting
self.addEventListener("message", (event: ExtendableMessageEvent) => {
  if (event.data?.type === "SKIP_WAITING") self.skipWaiting();
});

See examples/core.md Pattern 2 for complete template with constants and type safety.

---

Pattern 3: Caching Strategies

Four strategies to match content types:

| Strategy | When to Use | Behavior | | ----------------------------- | ---------------------------------- | ------------------------------------------- | | Cache-first | Static assets, fonts, hashed files | Return cached immediately, network fallback | | Network-first | HTML pages, user-specific API data | Try network with timeout, cache fallback | | Stale-while-revalidate | Avatars, non-critical API, feeds | Return cached, refresh in background | | Cache-only / Network-only | Precached shells / real-time data | Single source, no fallback |

Key implementation details:

• Always check response.ok before caching (avoid caching 404/500)
• Always response.clone() before cache.put() (body consumed once)
• Add timeout to network-first to avoid hanging on slow connections
• Limit cache size to prevent unbounded storage growth

// The clone pattern - response body can only be consumed once
const networkResponse = await fetch(request);
if (networkResponse.ok) {
  cache.put(request, networkResponse.clone()); // Clone for cache
}
return networkResponse; // Original for client

See examples/core.md Pattern 2 for all strategy implementations in the complete template, and examples/caching.md for advanced patterns (expiration, selective API caching, storage cleanup).

---

Pattern 4: Fetch Event Routing

Route requests to appropriate caching strategies based on request type and URL.

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

  if (request.method !== "GET") return; // Skip non-GET
  if (url.origin !== location.origin) return; // Skip cross-origin

  if (request.mode === "navigate") {
    event.respondWith(networkFirst(request, CACHES.pages));
  } else if (request.destination === "image") {
    event.respondWith(
      cacheFirstWithLimit(request, CACHES.images, MAX_CACHE_ITEMS.images),
    );
  } else if (url.pathname.startsWith("/api/")) {
    event.respondWith(staleWhileRevalidate(request, CACHES.api));
  } else {
    event.respondWith(cacheFirst(request, CACHES.static));
  }
});

---

Pattern 5: Offline Fallback

Always precache an offline.html page and return it when both cache and network fail for navigation requests.

// In install handler: precache offline.html
// In fetch error handling:
if (request.mode === "navigate") {
  const offlinePage = await caches.match("/offline.html");
  if (offlinePage) return offlinePage;
}

// Last resort: inline response
return new Response(
  "<html><body><h1>Offline</h1><p>Check your connection.</p></body></html>",
  { status: 503, headers: { "Content-Type": "text/html" } },
);

---

Pattern 6: Navigation Preload

Fetch navigation requests in parallel with service worker bootup, reducing latency for network-first HTML. Enable in activate, consume via event.preloadResponse in fetch.

// Activate: enable navigation preload
if (self.registration.navigationPreload) {
  await self.registration.navigationPreload.enable();
}

// Fetch: use preloaded response (avoids double fetch)
const preloadResponse = await event.preloadResponse;
if (preloadResponse) {
  cache.put(event.request, preloadResponse.clone());
  return preloadResponse;
}

Warning: If you enable navigation preload, you MUST use event.preloadResponse. Using fetch(event.request) instead results in two network requests for the same resource.

When to use: Network-first HTML pages with dynamic/authenticated content. Not needed for precached app shells.

See examples/caching.md Pattern 8 for complete implementation.

---

Pattern 7: Update Handling

Users should control when updates apply. Detect waiting workers, notify users, and let them trigger skipWaiting.

// Client: detect and apply updates
if (registration.waiting) {
  showUpdateBanner();
}

function applyUpdate() {
  registration.waiting?.postMessage({ type: "SKIP_WAITING" });
}

// Reload when new worker takes control
navigator.serviceWorker.addEventListener("controllerchange", () => {
  window.location.reload();
});

See examples/updates.md for version tracking, aggressive updates, deferred updates, idle-time updates, progressive rollout, and data migration patterns.

</patterns>

---

<red_flags>

RED FLAGS

High Priority Issues:

• No event.waitUntil() in install/activate - browser may terminate SW before async operations complete
• Calling skipWaiting() unconditionally in install - users experience unexpected behavior changes mid-session
• No cache versioning - old cached content persists forever, storage grows unbounded
• Not cleaning up old caches in activate - storage quota eventually exceeded
• Missing offline fallback - users see browser error page instead of helpful message
• Not checking response.ok before caching - error responses (404, 500) get cached and served

Medium Priority Issues:

• No timeout on network requests in network-first strategy - fetch hangs indefinitely on slow connections
• Not cloning response before caching - response body consumed, client gets empty response
• No cache size limits - unbounded growth leads to quota issues
• Attempting to cache POST requests - only GET requests are cacheable

Gotchas & Edge Cases:

• Service workers only work over HTTPS (exception: localhost for development)
• Scope determined by SW file location - /sw.js controls /, but /scripts/sw.js only controls /scripts/
• Browser may terminate idle service workers - do not rely on in-memory state
• clients.claim() does not trigger reload - clients keep running old page with new SW
• Chrome DevTools "Update on reload" bypasses waiting - useful for dev, not representative of production
• Web app manifest changes do not trigger SW update - only byte changes to SW file itself
• IndexedDB transactions cannot span await - complete DB work in single transaction
• Opaque responses (cross-origin without CORS) count against storage quota at inflated cost
• Service worker bootup varies: ~50ms desktop, ~250ms mobile, 500ms+ slow devices - navigation preload mitigates this

</red_flags>

---

<critical_reminders>

CRITICAL REMINDERS

All code must follow project conventions in CLAUDE.md

(You MUST call event.waitUntil() in install and activate handlers to signal completion)

(You MUST version your caches and clean up old versions during activation)

(You MUST clone responses before caching - cache.put(request, response.clone()) - response body can only be consumed once)

(You MUST implement proper update detection and give users control over when updates apply)

(You MUST handle all fetch failures with appropriate offline fallbacks)

Failure to follow these rules will result in broken updates, unbounded cache growth, and poor offline experience.

</critical_reminders>