Service Worker Lifecycle

## The two things people conflate A service worker registration has a **lifecycle** (installing → installed → activating → activated → redundant) and separately each open document has a **controller** — the worker, if any, that gets `fetch` events for that document's requests. Registering a worker advances the lifecycle. It does not retroactively hand an already-loaded document a controller. ## What register() actually does ```js const reg = await navigator.serviceWorker.register('/sw.js'); ``` The browser resolves the script URL, checks it is same-origin and in a secure context (HTTPS, or `localhost` for development), downloads it, and if it is new it creates a worker in the *installing* state. The `install` event fires; when it finishes the worker becomes *installed*. If no other worker is active for that registration, it moves straight on to *activating*, fires `activate`, and becomes *activated*. All of that is asynchronous and typically completes after the page has already finished loading its HTML, CSS and scripts from the network. ## The controller is chosen at navigation time When the browser navigates to a URL, it looks for a registration whose scope matches that URL and which already has an **active** worker. If it finds one, the new document is created *controlled* by that worker, and from then on the worker receives a `fetch` event for the document's subresource requests and for later `fetch()`/`XMLHttpRequest` calls. If there is no active worker at navigation time, the document is created **uncontrolled**, and that is permanent for the document unless the worker claims it. This is why the very first visit — the one that installs the worker — is never intercepted. You can observe it directly: ```js navigator.serviceWorker.register('/sw.js').then((reg) => { console.log(navigator.serviceWorker.controller); // null on the first visit console.log(reg.active); // may be non-null moments later }); ``` Note the asymmetry: `reg.active` can be a worker while `navigator.serviceWorker.controller` is still `null`. The registration has an active worker; *this document* simply is not one of its clients. ## clients.claim() The escape hatch is `self.clients.claim()`, called from the worker's `activate` handler: ```js self.addEventListener('activate', (event) => { event.waitUntil(self.clients.claim()); }); ``` This makes the newly activated worker take control of in-scope clients that currently have no controller. Each such page fires `controllerchange` on `navigator.serviceWorker`, and `navigator.serviceWorker.controller` becomes non-null. Be honest about what this buys you: the page's HTML, CSS and initial scripts were already fetched from the network before the claim happened, so claiming does not retroactively serve them from the worker. It only affects requests the page makes *after* it is claimed — lazily loaded chunks, API calls, images added later. Its real value is making the first session behave consistently instead of half-controlled. ## How to tell what state you are in - `navigator.serviceWorker.controller` — `null` means this document is uncontrolled. - `navigator.serviceWorker.ready` — resolves with a registration that has an active worker. It does **not** promise that this document is controlled; a first-load page can have `ready` resolve while `controller` is still `null`. - `navigator.serviceWorker.addEventListener('controllerchange', …)` — fires when the document's controller changes, e.g. after a claim or after a new worker skips waiting. ## Traps worth knowing - **Hard reload bypasses the worker.** A shift-reload (or "Empty cache and hard reload") loads the page uncontrolled on purpose, which is why a bug "disappears" for the developer testing it that way. - **Secure context required.** Registration only works over HTTPS or on `localhost`; on plain HTTP over a network the promise rejects. - **Scope matters.** A page outside the registration's scope is never controlled, no matter how many times it registers the worker. - **Registering repeatedly is cheap.** Calling `register()` with the same URL on every page load is the normal pattern; if the byte content is unchanged the browser keeps the existing registration.