mdn · hamishwillee · Dec 12, 2025
@@ -8,22 +8,14 @@ browser-compat: api.ServiceWorkerContainer.register
 
 {{APIRef("Service Workers API")}}{{SecureContext_Header}}{{AvailableInWorkers}}
 
-The **`register()`** method of the {{domxref("ServiceWorkerContainer")}} interface creates or updates a {{domxref("ServiceWorkerRegistration")}} for the given scope.
-If successful, the registration associates the provided script URL to a _scope_, which is subsequently used for matching documents to a specific service worker.
+> [!WARNING]
+> The `scriptURL` parameter passed to this method represents the URL of an external script loaded into a service worker.
+> APIs like this are known as [injection sinks](/en-US/docs/Web/API/Trusted_Types_API#concepts_and_usage), and are potentially a vector for [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
+>
+> You can mitigate this risk by having a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) that restricts the locations from which scripts can be loaded, and by always assigning {{domxref("TrustedScriptURL")}} objects instead of strings and [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types).
+> See [Security considerations](#security_considerations) for more information.
 
-A single registration is created for each unique scope.
-If `register()` is called for a scope that has an existing registration, the registration is updated with any changes to the scriptURL or options.
-If there are no changes, then the existing registration is returned.
-Calling `register()` with the same scope and `scriptURL` does not restart the installation process, so it is generally safe to call this method unconditionally from a controlled page.
-However, it does send a network request for the service worker script, which may put more load on the server.
-If this is a concern, you can first check for an existing registration using {{domxref("ServiceWorkerContainer.getRegistration()")}}.
-
-A document can potentially be within the scope of several registrations with different service workers and options.
-The browser will associate the document with the matching registration that has the most specific scope.
-This ensures that only one service worker runs for each document.
-
-> [!NOTE]
-> It is generally safer not to define registrations that have overlapping scopes.
+The **`register()`** method of the {{domxref("ServiceWorkerContainer")}} interface creates or updates a {{domxref("ServiceWorkerRegistration")}} for the given scope.
 
 ## Syntax
 
@@ -35,8 +27,8 @@ register(scriptURL, options)
 ### Parameters
 
 - `scriptURL`
-  - : The URL of the service worker script.
-    The registered service worker file needs to have a valid [JavaScript MIME type](/en-US/docs/Web/HTTP/Guides/MIME_types#textjavascript).
+  - : A {{domxref("TrustedScriptURL")}} instance or a string defining the URL of the service worker script.
+    The registered service worker file needs to be served with a valid [JavaScript media type](/en-US/docs/Web/HTTP/Guides/MIME_types#textjavascript).
 - `options` {{optional_inline}}
   - : An object containing registration options. Currently available options are:
     - `scope`
@@ -86,10 +78,93 @@ A {{jsxref("Promise")}} that resolves with a {{domxref("ServiceWorkerRegistratio
   - : The `scriptURL` is not a potentially trustworthy origin, such as `localhost` or an `https` URL.
     The `scriptURL` and scope are not same-origin with the registering page.
 
+## Description
+
+The **`register()`** method creates or updates a {{domxref("ServiceWorkerRegistration")}} for the given scope.
+If successful, the registration associates the provided script URL to a _scope_, which is subsequently used for matching documents to a specific service worker.
+
+A single registration is created for each unique scope.
+If `register()` is called for a scope that has an existing registration, the registration is updated with any changes to the scriptURL or options.
+If there are no changes, then the existing registration is returned.
+Calling `register()` with the same scope and `scriptURL` does not restart the installation process, so it is generally safe to call this method unconditionally from a controlled page.
+However, it does send a network request for the service worker script, which may put more load on the server.
+If this is a concern, you can first check for an existing registration using {{domxref("ServiceWorkerContainer.getRegistration()")}}.
+
+A document can potentially be within the scope of several registrations with different service workers and options.
+The browser will associate the document with the matching registration that has the most specific scope.
+This ensures that only one service worker runs for each document.
+
+> [!NOTE]
+> It is generally safer not to define registrations that have overlapping scopes.
+
+### Security considerations
+
+The `scriptURL` parameter specifies the script for service worker, which can intercept network requests for pages within its scope and return respones that are fresh, cached, new, or modified.
+If the input is provided by a user, this is a possible vector for [cross-site scripting (XSS)](/en-US/docs/Web/Security/Attacks/XSS) attacks.
+
+It is extremely risky to accept and execute arbitrary URLs from untrusted origins.
+A website should control what scripts that are allowed to run using a [Content Security Policy (CSP)](/en-US/docs/Web/HTTP/Guides/CSP) with the [`worker-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/worker-src) directive (or a fallback defined in [`script-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/script-src) or [`default-src`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/default-src)).
+This can restrict scripts to those from the current origin, or a specific set of origins, or even particular files.
+
+If you're using this property and [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) (using the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) CSP directive), you will need to always assign {{domxref("TrustedScriptURL")}} objects instead of strings.
+This ensures that the input is passed through a transformation function, which has the chance to reject or modify the URL before it is injected.
+
 ## Examples
 
 The examples below should be read together to understand how service worker scope applies to a page.
 
+Note that the first example shows how to use the method with trusted types.
+The other examples omit this step for brevity.
+
+### Using TrustedScriptURL
+
+To mitigate the risk of XSS, we should always assign `TrustedScriptURL` instances to the `scriptURL` parameter.
+We also need to do this if we're enforcing trusted types for other reasons and we want to allow some script sources that have been permitted (by `CSP: worker-src`).
+
+Trusted types are not yet supported on all browsers, so first we define the [trusted types tinyfill](/en-US/docs/Web/API/Trusted_Types_API#trusted_types_tinyfill).
+This acts as a transparent replacement for the trusted types JavaScript API:
+
+```js
+if (typeof trustedTypes === "undefined")
+  trustedTypes = { createPolicy: (n, rules) => rules };
+```
+
+Next we create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createScriptURL", "createScriptURL()")}} method for transforming input strings into {{domxref("TrustedScriptURL")}} instances.
+
+For the purpose of this example we'll assume that we want to allow a predefined set of URLs in the `scriptAllowList` array and log any other scripts.
+
+```js
+const scriptAllowList = [
+  // Some list of allowed URLs
+];
+const policy = trustedTypes.createPolicy("script-url-policy", {
+  createScriptURL(input) {
+    if (scriptAllowList.includes(input)) {
+      return input; // allow the script
+    }
+    console.log(`Script not in scriptAllowList: ${input}`);
+    return ""; // Block the script
+  },
+});
+```
+
+Then we use the `policy` object to create a `trustedScript` object from a potentially unsafe input string:
+
+```js
+// The potentially malicious string
+// We won't be including untrustedScript in our scriptAllowList array
+const untrustedScript = "https://evil.example.com/service_worker.js";
+
+// Create a TrustedScriptURL instance using the policy
+const trustedScriptURL = policy.createScriptURL(untrustedScript);
+```
+
+The `trustedScriptURL` property can now be used to register our service worker.
+
+```js
+navigator.serviceWorker.register(trustedScriptURL).
+```
+
 ### Register a service worker with default scope
 
 The following example uses the default value of `scope` by omitting it, which sets it to be the same location as the script URL.