service-worker

Service Worker

Table of Contents

• Constraints
• Lifecycle
• Registration
• Install / Activate / Fetch Events
• Common Pitfalls
• Next.js Integration
• Reference files

Constraints

• HTTPS required (localhost exempt for dev)
• No DOM access — runs on separate thread
• Fully async — no synchronous XHR, no localStorage
• No dynamic import() — only static import statements
• Scope defaults to the directory containing the SW file
• self refers to ServiceWorkerGlobalScope

<quick_reference>

Lifecycle

register() → Download → Install → [Wait] → Activate → Fetch control

1. Register from main thread via navigator.serviceWorker.register()
2. Install event fires once — use to pre-cache static assets
3. Wait — new SW waits until all tabs using old SW are closed (skip with self.skipWaiting())
4. Activate event fires — use to clean up old caches
5. Fetch events start flowing — SW controls page network requests

A document must reload to be controlled (or call clients.claim() during activate).

Updating a Service Worker

• Browser byte-compares the SW file on each navigation (or every 24h)
• New version installs in background while old version still serves
• Increment the cache name (e.g., v1 → v2) in the new version
• Delete old caches in the activate handler
• Call self.skipWaiting() in install to activate immediately
• Call self.clients.claim() in activate to take control of open pages

DevTools

• Chrome: chrome://inspect/#service-workers or Application > Service Workers
• Firefox: about:debugging#/runtime/this-firefox or Application > Service Workers
• Edge: edge://inspect/#service-workers or Application > Service Workers

Unregister, update, and inspect caches from the Application panel. Use "Update on reload" checkbox during development.