Use the Service Worker Static Routing API to bypass the service worker for specific paths

Rachel Andrew

From Chrome 123, the Service Worker Static Routing API is available. This API lets you declaratively state how certain resource paths should be fetched, meaning that the browser does not need to run a service worker only to fetch responses from a cache, or directly from the network. This API has been in origin trial since Chrome 116, and this post details the API launching in Chrome 123.

Note: See the original post, Service Worker Static Routing API Origin Trial for the background to the feature.

Use the API

To use the API call event.addRoutes on the service worker install event. Pass this method a list of routes, with the following properties:

condition

Specifies when the rule applies. Accepts the following properties:

• urlPattern: A URLPattern instance, or a string representing a valid URLPattern, that can be passed into the URLPattern constructor.
• requestMethod: A string containing a Request method.
• requestMode: A string containing a Request mode.
• requestDestination: A string containing a Request destination.
• runningStatus: a string, either "running" or "not-running". This indicates the running status of the service worker.

source

Specifies how the resources matching condition are loaded. One of the following strings:

• "network"
• "cache"
• "fetch-event"
• "race-network-and-fetch-handler"

Note: source can optionally include a cache name, see the example later in this post.

In the following example, URLs that start with "/articles" are routed to the service worker if it is currently running. Where there are multiple conditions, for example urlPattern and runningStatus, all conditions must be met for the route to be used.

addEventListener('install', (event) => {
  event.addRoutes({
    condition: {

          urlPattern: "/articles/*",
          runningStatus: "running"
    },
    source: "fetch-event"
  });
});

In the following example, posts to a form are sent directly to the network and bypass the service worker.

addEventListener('install', (event) => {
  event.addRoutes({
    condition: {
          urlPattern: "/form/*",
          requestMethod: "post"
    },
    source: "network"
  });
});

In the following example, the cache storage named "pictures" is used for fetching files with a file extension of .png or .jpg.

addEventListener('install', (event) => {
  event.addRoutes({
    condition: {
      or: [
        {urlPattern: "*.png"},
        {urlPattern: "*.jpg"}
      ]
    },
    source: {
      cacheName: "pictures"
    }
  });
});

Changes from the origin trial

The original origin trial used InstallEvent.registerRouter() instead of InstallEvent.addRoutes(), the registerRouter() method could only be called once. This change was based on community feedback to the origin trial.

Note: If you have code that uses the deprecated registerRouter() method, you should migrate to addRoutes(). We plan to remove registerRouter() in Chrome 125.

The new API also takes advantage of changes to URLPattern introduced in Chrome 121, adds the ability to specify a request method, mode, and destination, and adds additional source options.

Support in Chrome DevTools

Registered router rules are displayed in the Service Worker Tab of the Application panel.

In the Network Panel, if the request matches the registered rule, this is indicated in the size column. When holding the pointer over the size column, the registered router ID is shown. Corresponding rules are displayed in the application tab.