Service Worker Primer

A service worker is a JavaScript file that runs in the background, separate from your page. It intercepts network requests, caches responses, and enables push notifications — all without a visible UI thread.

Why Nimbus uses one

The Meridian dashboard ships a service worker so license status, session tokens, and UI shell assets survive spotty connections. When a customer opens the dashboard on a flaky hotel Wi-Fi, the worker serves cached HTML and JSON instantly while a background sync reconciles state with Upstash KV.

Lifecycle in three acts

1. install — the browser downloads and caches the worker script. Nimbus pre-caches the shell (layout, CSS, offline fallback page).
2. activate — the worker takes control of pages. Old caches are purged so stale license data never sticks.
3. fetch — every network request passes through the worker. Cache-first for static assets, network-first for API calls, with a 3-second timeout before falling back to the last good response.

Scope and registration

A worker can only control pages under its scope path. Nimbus registers at / so every route is covered. Registration happens once in the root layout via a small inline script that calls navigator.serviceWorker.register.

Cache strategy

Nimbus uses three named caches:

• shell-v1 — immutable build artifacts (JS bundles, CSS).
• api-v1 — license checks and session data, network-first with stale fallback.
• static-v1 — images and fonts, cache-first with a 30-day TTL.

Debugging

Open Chrome DevTools → Application → Service Workers. Check “Update on reload” during development so you always get the latest worker. The console shows lifecycle events when verbose logging is enabled.

Next: read Offline Grace Caches to see how Nimbus combines service workers with HMAC-signed license caches for true offline resilience.