Service Worker
Overview
Service workers are event-driven scripts that run in a separate thread from the main page, intercepting network requests, managing caches, and enabling offline functionality. Workbox v7.4 (maintained by the Chrome Aurora team) provides a production-ready abstraction over the low-level Cache API and fetch event handling.
When to use: Progressive web apps needing offline support, apps requiring push notifications, background data synchronization, app shell caching, network request optimization with static routing.
When NOT to use: Simple static sites served from a CDN, server-rendered apps with no offline requirements, apps where stale data is unacceptable (use network-only), prototypes where caching complexity is premature.
Quick Reference
| Pattern | API / Tool | Key Points |
|---|
| Registration | navigator.serviceWorker.register() | Register in window context, scope defaults to path |
| Precaching | workbox-precaching | Revision-hashed app shell, injected at build time |
| Cache-first | CacheFirst strategy | Static assets, fonts, images |
| Network-first | NetworkFirst strategy | API responses needing freshness |
| Stale-while-revalidate | StaleWhileRevalidate strategy | Balance between speed and freshness |
| Background sync | workbox-background-sync | Replay failed requests when back online |
| Push notifications | Push API + Notifications API | VAPID keys, server-sent push, offline-first display |
| Static routing | event.addRoutes() in install | Bypass fetch handler for known routes |
| Skip waiting | self.skipWaiting() | Activate new SW immediately, use with caution |
| Clients claim | self.clients.claim() | Control existing tabs without reload |
| Navigation preload | navigationPreload.enable() | Parallel network request during SW startup |
| Update prompt | workbox-window Workbox class | Detect updates, prompt user, postMessage to SW |
| Offline fallback | workbox-recipes offlineFallback | Serve fallback page when cache and network fail |
| Cache expiration | workbox-expiration | maxEntries and maxAgeSeconds per cache |
Browser Support Quick Reference
| Feature | Chrome | Firefox | Safari | Edge |
|---|
| Service Workers | 40+ | 44+ | 11.1+ | 17+ |
| Background Sync | 49+ | No | No | 79+ |
| Periodic Sync | 80+ | No | No | 80+ |
| Push API | 50+ | 44+ | 16.4+ | 17+ |
| Navigation Preload | 59+ | 99+ | 15.4+ | 18+ |
| Static Routing API | 123+ | No | No | 123+ |
| Background Fetch | 74+ | No | No | 79+ |
| Storage Persistence | 52+ | 55+ | 15.2+ | 79+ |
Common Mistakes
| Mistake | Correct Pattern |
|---|
| Caching API responses with CacheFirst | Use NetworkFirst or StaleWhileRevalidate for dynamic data |
| Calling skipWaiting unconditionally | Prompt user before activating to avoid breaking in-flight navigations |
| Not versioning precache manifests | Use workbox-build or workbox-webpack-plugin to inject revision hashes |
| Ignoring cache storage limits | Implement cache expiration with workbox-expiration plugin |
| Using sync access handle in service worker | OPFS createSyncAccessHandle is dedicated-worker only; use async methods |
| Assuming Background Sync works everywhere | Chrome/Edge only (~80%); implement navigator.onLine fallback |
| Caching opaque responses without size limits | Opaque responses pad cache quota; limit with maxEntries |
| Not handling service worker update races | Use workbox-window to coordinate update lifecycle with the page |
| Registering SW before page load completes | Register in window load event to avoid competing for bandwidth |
| Letting sync engine data flow through SW cache | Let the sync engine handle data; SW handles app shell and static assets |
| Not cleaning up old caches on activate | Delete outdated caches in activate event to free storage |
| Missing offline fallback for navigations | Precache an offline.html and serve it when network and cache both fail |
Workbox Package Reference
| Package | Purpose |
|---|
workbox-precaching | Build-time asset caching with revision management |
workbox-routing | URL pattern matching and strategy routing |
workbox-strategies | CacheFirst, NetworkFirst, StaleWhileRevalidate |
workbox-expiration | Cache size and age limits |
workbox-cacheable-response | Filter responses by status or header |
workbox-background-sync | Queue and replay failed requests |
workbox-window | Page-side registration and update management |
workbox-recipes | Pre-built patterns (offline fallback, warm cache) |
workbox-build | Build tool for generating precache manifests |
workbox-navigation-preload | Enable navigation preload in activate |
Delegation
If the local-first skill is available, delegate architecture decisions, sync engine selection, and offline data strategy to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y If the electricsql skill is available, delegate sync engine patterns, shape subscriptions, and real-time data replication to it. Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y
- Caching strategy review: Use
Task agent to audit route-to-strategy mappings - Offline testing: Use
Task agent to simulate offline scenarios and verify fallback behavior - Push notification design: Use
Plan agent to design notification payload and action strategies
References
