A service worker script is served from /static/js/sw.js and the page calls navigator.serviceWorker.register('/static/js/sw.js', { scope: '/' }). Why does that registration fail, and what would make it work?

## Scope decides which pages the worker controls A registration's scope is a URL. Any client whose URL starts with that string — a plain prefix match on the serialized URL — is eligible to be controlled by that registration. `scope: '/app/'` controls `/app/`, `/app/settings`, `/app/a/b/c`, but not `/help`. Because it is a string prefix and not a path-segment match, a scope of `/app` (no trailing slash) also matches `/apple.html`, which is a small but real footgun; write scopes with a trailing slash. ## The default and the maximum are both derived from the script URL When you omit the option, the scope defaults to the directory part of the script's URL. `/sw.js` → `/`. `/static/js/sw.js` → `/static/js/`. Separately, the *maximum* allowed scope is derived the same way, and an explicit `scope` option is validated against it. So: - `register('/sw.js')` → scope `/` ✅ - `register('/sw.js', { scope: '/app/' })` → narrower than the max, ✅ - `register('/static/js/sw.js', { scope: '/' })` → wider than the max, ❌ rejects with `SecurityError` The rejection is a promise rejection, so it is easy to swallow. Always attach a `.catch()` to `register()` — a silently rejected registration looks exactly like a worker that never updates. ## Widening the maximum: Service-Worker-Allowed The server can raise the ceiling by sending a response header on the worker script itself: ``` HTTP/1.1 200 OK Content-Type: text/javascript Service-Worker-Allowed: / ``` With that header on `/static/js/sw.js`, the explicit `{ scope: '/' }` registration succeeds. Note both halves are required: the header raises the maximum, and you still pass the `scope` option, because the *default* is still the script's directory. This matters in practice when a bundler emits hashed asset paths, or when a CDN serves your JS from a subdirectory while the app lives at the origin root. ## Why the restriction exists Controlling a scope is a lot of power — the worker sees and can answer every request from every page under it. The platform uses "where the file is served from" as a cheap proof of authority over that path. Any site that lets users upload files into a directory would otherwise be handing each uploader the ability to intercept the entire origin. The `Service-Worker-Allowed` header is the deliberate opt-in: only something that can set response headers — that is, the site operator, not an uploader — can widen the scope. ## Related rules worth knowing - **Scope selects clients, not URLs.** A page inside the scope is controlled, and then *all* of that page's requests go to the `fetch` handler — including requests for URLs outside the scope and even cross-origin ones. Scope is about which documents are controlled, not about which request URLs are interceptable. - **Overlapping registrations.** An origin may hold several registrations. For a given client URL, the registration with the longest matching scope wins; only one worker controls a document. - **Same origin only.** The script URL must be same-origin with the page; you cannot register a worker from a CDN on another origin. Serve it from your own origin, proxying if you must. - **Secure context.** HTTPS, or `localhost` for development. - **The scope you get back.** `registration.scope` is the absolute, resolved URL — log it when debugging, since a relative script path resolves against the *page's* URL, which is a frequent source of surprise on nested routes. ## Practical guidance Put the worker at the root when the app owns the origin: `/sw.js`, no options, no headers, nothing to explain to the next engineer. Reach for `Service-Worker-Allowed` only when your build pipeline genuinely cannot emit a root-level file, and when you do, treat it as a deployment requirement — a cache or proxy tier that strips unknown response headers will break registration in production while everything works locally.