How to change the scope of a service worker

The scope of a service worker defines when it is active and usually depends on the path where it is located. However in this tutorial we'll see some directives that allow to change the default scope of a service worker, regardless of its location.

What is the scope of a service worker?

The scope of a service worker defines where a service worker is active.

For example:

• https://example.com/service-worker.js is active on the whole website because it is in the root directory
• https://example.com/assets/service-worker.js is active only when you are surfing pages under the /assets/ directory

The scope of the service worker depends on the path where the service worker is located. In the examples above, the scopes are "/" and "/assets/" respectively.

Changing the scope with the scope option

We have seen that the scope is determined by the path of the service worker file. However sometimes you may need to overcome this limitation.

Fortunately there is a way to place a service worker in an arbitrary path and then change its scope:

navigator.serviceWorker.register('/path/to/sw.js', { scope: '/path/to/something/else/' });

In the above example the scope of the service worker has been changed from "/path/to/" to "/path/to/something/else/".

Basically we are narrowing the scope of the service worker… What if we want to enlarge the scope?

navigator.serviceWorker.register('/path/to/sw.js', { scope: '/' });

Unfortunately this last example does not work and you will get a security exception in the browser. But don't worry there is a solution.

The trick to broaden the service worker scope

Let's say that you need to place a service worker in a specific directory, but you also want to enable that service worker for the entire website (root scope).

First you need to set the scope option:

navigator.serviceWorker.register('/path/to/sw.js', { scope: '/' });

Then add this HTTP header to the response when you serve the service worker file:

Service-Worker-Allowed: /

Thanks to this special header, the browser will not complain about the larger scope. Basically you have installed a service worker in the root, even if it's not physically located in the root.

This solution works for any scope, you can simply adjust the path based on your needs.

Keep it simple

Finally remember that, for simplicity, it is often convenient to place the service worker file in the root directory of your website. In this way you avoid all the complexities described above.

This recommendation is especially true if you are using the service worker for web push notifications. For Pushpad we recommend to place the service worker in the root directory of your website whenever possible - use the other solutions only if you really need them.

There are however some situations where changing the scope of a service worker can be really useful. For example the solution described above should be used if your website builder doesn't support the upload of custom files (the service worker) in the root directory: in this case you can upload the file in any subdirectory and then change the scope.