The register()
method of the ServiceWorkerContainer
interface creates or updates a ServiceWorkerRegistration
for the given scriptURL
.
If successful, a service worker registration ties the provided script URL to a scope, which is subsequently used for navigation matching. You can call this method unconditionally from the controlled page. I.e., you don't need to first check whether there's an active registration.
There is frequent confusion surrounding the meaning and use of scope. Since a service worker can't have a scope broader than its own location, only use the scope
option when you need a scope that is narrower than the default.
register(scriptURL)
register(scriptURL, options)
The examples described here should be taken together to get a better understanding of how service workers scope applies to a page.
The following example uses the default value of scope
(by omitting it). The service worker code in this case, if included in example.com/index.html
, will control example.com/index.html
, as well as pages underneath it, like example.com/product/description.html
.
if ("serviceWorker" in navigator) {
navigator.serviceWorker.register("/sw.js").then(
(registration) => {
console.log("Service worker registration succeeded:", registration);
},
(error) => {
console.error(`Service worker registration failed: ${error}`);
},
);
} else {
console.error("Service workers are not supported.");
}
The following code, if included in example.com/index.html
, at the root of a site, would apply to exactly the same pages as the example above. Remember the scope, when included, uses the page's location as its base.
Alternatively, if this code were included in a page at example.com/product/description.html
, with the JavaScript file residing at example.com/product/sw.js
, then the service worker would only apply to resources under example.com/product
.
if ("serviceWorker" in navigator) {
navigator.serviceWorker.register("/sw.js", { scope: "./" }).then(
(registration) => {
console.log("Service worker registration succeeded:", registration);
},
(error) => {
console.error(`Service worker registration failed: ${error}`);
},
);
} else {
console.error("Service workers are not supported.");
}
There is frequent confusion surrounding the meaning and use of scope. Since a service worker can't have a scope broader than its own location, only use the scope
option when you need a scope that is narrower than the default.
The following code, if included in example.com/index.html
, at the root of a site, would only apply to resources under example.com/product
.
if ("serviceWorker" in navigator) {
navigator.serviceWorker.register("/sw.js", { scope: "/product/" }).then(
(registration) => {
console.log("Service worker registration succeeded:", registration);
},
(error) => {
console.error(`Service worker registration failed: ${error}`);
},
);
} else {
console.error("Service workers are not supported.");
}
However, servers can remove this restriction by setting a Service-Worker-Allowed header on the service worker script, and then you can specify a max scope for that service worker above the service worker's location.