Web/API/ServiceWorkerContainer/register

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.

Syntax

serviceWorkerContainer.register(scriptURL, options)
  .then(function(serviceWorkerRegistration) { ... });

Parameters

scriptURL: The URL of the service worker script. The registered service worker file needs to have a valid JavaScript MIME type.
options Optional: An object containing registration options. Currently available options are:

scope

A USVString 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 a relative URL. It is relative to the base URL of the application. By default, the scope value for a service worker registration is set to the directory where the service worker script is located. See the Examples section for more information on how it works.

Return value

A Promise that resolves with a ServiceWorkerRegistration object.

Examples

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) {
  // Register a service worker hosted at the root of the
  // site using the default scope.
  navigator.serviceWorker.register('/sw.js').then(function(registration) {
    console.log('Service worker registration succeeded:', registration);
  }, /*catch*/ function(error) {
    console.log('Service worker registration failed:', error);
  });
} else {
  console.log('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) {
  // declaring scope manually
  navigator.serviceWorker.register('/sw.js', {scope: './'}).then(function(registration) {
    console.log('Service worker registration succeeded:', registration);
  }, /*catch*/ function(error) {
    console.log('Service worker registration failed:', error);
  });
} else {
  console.log('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) {
  // declaring scope manually
  navigator.serviceWorker.register('/sw.js', {scope: '/product/'}).then(function(registration) {
    console.log('Service worker registration succeeded:', registration);
  }, /*catch*/ function(error) {
    console.log('Service worker registration failed:', error);
  });
} else {
  console.log('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.

Specifications

Specification	Status	Comment
Service WorkersThe definition of 'ServiceWorkerContainer: register' in that specification.	Working Draft	Initial definition.

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`register` Experimental'	Chrome Full support 40	Edge Full support 17 Full support 17 Full support 16 Disabled' Disabled' From version 16: this feature is behind the `Enable service workers` preference.	Firefox Full support 44 Notes' Full support 44 Notes' Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API.	IE No support No	Opera Full support 27	Safari Full support 11.1	WebView Android Full support 40	Chrome Android Full support 40	Firefox Android Full support 44	Opera Android Full support 27	Safari iOS Full support 11.3	Samsung Internet Android Full support 4.0

Legend

Full support: Full support
No support: No support
Experimental. Expect behavior to change in the future.': Experimental. Expect behavior to change in the future.
See implementation notes.': See implementation notes.
User must explicitly enable this feature.': User must explicitly enable this feature.

ServiceWorkerContainer.register() by Mozilla Contributors is licensed under CC-BY-SA 2.5.