InstallEvent: addRoutes() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The addRoutes()
method of the InstallEvent
interface specifies one or more static routes, which define rules for fetching specified resources that will be used even before service worker startup. This allows you to, for example, bypass a service worker in cases where you always want to fetch a resource from the network or a browser Cache
, and avoids the performance overhead of unnecessary service worker cycles.
Syntax
addRoutes(routerRules)
Parameters
routerRules
-
A single object, or an array of one or more objects, representing rules for how certain resources should be fetched. Each
routerRules
object contains the following properties:condition
-
An object defining one or more conditions that specify which resources should match this rule. The following properties can be included; if multiple properties are used, a resource must meet all specified conditions to match the rule.
not
Optional-
A
condition
object defining conditions that must explicitly not be met to match the rule. Conditions defined inside anot
condition are mutually exclusive with other conditions. or
Optional-
An array of
condition
objects. One set of these defined conditions must be met to match the rule. Conditions defined inside anor
condition are mutually exclusive with other conditions. requestMethod
Optional-
A string representing the HTTP method a request should be sent by for it to match the rule, such as
"get"
,"put"
, or"head"
. requestMode
Optional-
A string representing the mode a request should have for it to match the rule, for example
"same-origin"
,"no-cors"
, or"cors"
. requestDestination
Optional-
A string representing the destination of a request, i.e. what content type should be requested, for it to match the rule. Examples include
"audio"
,"document"
,"script"
, and"worker"
. runningStatus
Optional-
An enumerated value representing the required running status of the service worker for a request to match the rule. Values can be
"running"
or"not-running"
. urlPattern
Optional-
A
URLPattern
instance, or aURLPattern()
constructorinput
pattern representing the URLs that match the rule.
source
-
An enumerated value or an object specifying the source from which matching resources will be loaded. Possible enumerated values are:
"cache"
-
Resources will be loaded from a browser
Cache
. "fetch-event"
-
Resources will be loaded via the service worker's
fetch
event handler. This can be combined with the"runningStatus"
condition to load resources from a service worker if it is running and fall back to a static route on the network if it is not. "network"
-
Resources will be loaded from the network.
"race-network-and-fetch-handler"
-
Attempts are made to load resources from the network and the service worker's
fetch
event handler simultaneously. Whichever one completes first is used.
The
source
value can also be set to an object containing a single property,cacheName
, the value of which is a string representing the name of a browserCache
. Matching resources will be loaded from this specific named cache if it exists.
Return value
A Promise
that fulfills with undefined
.
Exceptions
TypeError
DOMException
-
Thrown if one or more of the rules objects inside
routerRules
is invalid, or has asource
value of"fetch-event"
when the associated service worker does not have afetch
event handler. Also thrown if you try to combineor
with another condition type.
Examples
Route specific requests to the network if the service worker is not running
In the following example, URLs that start with /articles
are routed to the network if the service worker is not currently running:
addEventListener("install", (event) => {
event.addRoutes({
condition: {
urlPattern: "/articles/*",
runningStatus: "not-running",
},
source: "network",
});
});
Route form post requests to the network
In the following example, POST
requests 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",
});
});
Route certain image type requests to a named cache
In the following example, the browser Cache
named "pictures"
is used for fetching files with extensions of .png
or .jpg
:
addEventListener("install", (event) => {
event.addRoutes({
condition: {
or: [{ urlPattern: "*.png" }, { urlPattern: "*.jpg" }],
},
source: {
cacheName: "pictures",
},
});
});
Note: If the cache does not exist, the browser defaults to using the network so that the requested resources can still be obtained provided the network is available.
You can't combine or
with another condition — this results in a TypeError
. If for example you wanted to match files with extensions of .png
or .jpg
but only when the requestMethod
is get
, you'd need to specify two separate conditions:
addEventListener("install", (event) => {
event.addRoutes(
{
condition: {
urlPattern: "*.png",
requestMethod: "get",
},
source: {
cacheName: "pictures",
},
},
{
condition: {
urlPattern: "*.jpg",
requestMethod: "get",
},
source: {
cacheName: "pictures",
},
},
);
});
Specifications
Specification |
---|
Service Workers # register-router-method |
Browser compatibility
BCD tables only load in the browser
See also
InstallEvent
install
event- Service Worker API
- Use the Service Worker Static Routing API to bypass the service worker for specific paths on
developer.chrome.com
(2024)