scriptURL

The URL of the service worker script.The registered service worker file needs to have a validJavaScript MIME type.

optionsOptional

An object containing registration options. Currently available options are:

scope

A string representing a URL that defines a service worker's registration scope; that is, what range of URLs a service worker can control.

This is usually specified as a URL that is relative to the base URL of the site (e.g.,/some/path/), so that the resolved scope is the same irrespective of what page the registration code is called from.The defaultscope for a service worker registration is the directory where the service worker script is located (resolving./ againstscriptURL).

The scope should be used to specify documents that are in the same directory or more deeply nested than the service worker.If you need a broader scope, this can be permitted via the HTTPService-Worker-Allowed header.See theExamples section for information on broadening the default scope of a service worker.

type

A string specifying the type of worker to create.Valid values are:

'classic'

The loaded service worker is in a standard script.This is the default.

'module'

The loaded service worker is in anES module and the import statement is available on worker contexts.For ES module compatibility info, see thebrowser compatibility data table for theServiceWorker interface.

updateViaCache

A string indicating how the HTTP cache is used for service worker scripts resources during updates.Note: This only refers to the service worker script and its imports, not other resources fetched by these scripts.

'all'

The HTTP cache will be queried for the main script, and all imported scripts. If no fresh entry is found in the HTTP cache, then the scripts are fetched from the network.

'imports'

The HTTP cache will be queried for imports, but the main script will always be updated from the network. If no fresh entry is found in the HTTP cache for the imports, they're fetched from the network.

'none'

The HTTP cache will not be used for the main script or its imports. All service worker script resources will be updated from the network.

APromise that resolves with aServiceWorkerRegistration object.

TypeError

ThescriptURL orscope URL is a failure.This can happen if the URL can't be resolved to a valid URL or uses a scheme that is nothttp: orhttps.It may also happen ifscriptURL is not aTrustedScriptURL, and this is a requirement of the site'sTrusted Types Policy.

The exception is also raised if thescriptURL orscope URL path contains the case-insensitive ASCII "%2f" (*) or "%5c" (=)

SecurityErrorDOMException

ThescriptURL is not a potentially trustworthy origin, such aslocalhost or anhttps URL.ThescriptURL and scope are not same-origin with the registering page.

The examples below should be read together to understand how service worker scope applies to a page.

The following example uses the default value ofscope by omitting it, which sets it to be the same location as the script URL.

Suppose the service worker code is atexample.com/sw.js, and the registration code atexample.com/index.html.The service worker code will controlexample.com/index.html, as well as pages underneath it, likeexample.com/product/description.html.

if ("serviceWorker" in navigator) {  // Register a service worker hosted at the root of the  // site using the default scope.  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.");}

Note that we have registered thescriptURL relative to the site root rather than the current page.This allows the same registration code to be used from any page.

The code below is almost identical, except we have specified the scope explicitly using{ scope: "/" }.We've specified the scope as site-relative so the same registration code can be used from anywhere in the site.

if ("serviceWorker" in navigator) {  // declaring scope manually  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.");}

This scope is the same as the default scope, so the registration applies to exactly the same pages as the previous example.Note that if we were to run this code after the previous example, browsers should recognize that we're updating an existing registration rather than a new one.

There is nothing to stop you from using page-relative URLs except that this makes it harder to move your pages around, and it is easy to accidentally create unwanted registrations if you do so.

In this example the service worker code is atexample.com/product/sw.js, and the registration code atexample.com/product/description.html.We're using URLs that are relative to the current directory for thescriptURL and thescope, where the current directory is the base URL of the page that is callingregister() (example.com/product/).The service worker applies to resources underexample.com/product/.

if ("serviceWorker" in navigator) {  // declaring scope manually  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.");}

A service worker can't have a scope broader than its own location, unless the server specifies a broader maximum scope in aService-Worker-Allowed header on the service worker script.Use thescope option when you need anarrower scope than the default.

The following code, if included inexample.com/index.html, at the root of a site, would only apply to resources underexample.com/product.

if ("serviceWorker" in navigator) {  // declaring scope manually  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.");}

As noted above, servers can change the default scope by setting theService-Worker-Allowed header on the service worker script.This allows thescope option to be set outside the path defined by the service worker's location.

The following code, if included inexample.com/product/index.html, would apply to all resources underexample.com if the server set theService-Worker-Allowed header to/ orhttps://example.com/ when servingsw.js. If the server doesn't set the header, the service worker registration will fail, as the requestedscope is too broad.

if ("serviceWorker" in navigator) {  // Declaring a broadened scope  navigator.serviceWorker.register("./sw.js", { scope: "/" }).then(    (registration) => {      // The registration succeeded because the Service-Worker-Allowed header      // had set a broadened maximum scope for the service worker script      console.log("Service worker registration succeeded:", registration);    },    (error) => {      // This happens if the Service-Worker-Allowed header doesn't broaden the scope      console.error(`Service worker registration failed: ${error}`);    },  );} else {  console.error("Service workers are not supported.");}

• ServiceWorkerRegistration:unregister() method
• Service worker API
• Using service workers
• Service-Worker-Allowed HTTP header