workbox-routing
Classes
NavigationRoute
NavigationRoute makes it easy to create a Route that matches for browser navigation requests.
It will only match incoming Requests whose
mode
is set to navigate
.
You can optionally only apply this route to a subset of navigation requests
by using one or both of the denylist
and allowlist
parameters.
RegExpRoute
RegExpRoute makes it easy to create a regular expression based Route.
For same-origin requests the RegExp only needs to match part of the URL. For requests against third-party servers, you must define a RegExp that matches the start of the URL.
Route
A Route
consists of a pair of callback functions, "match" and "handler".
The "match" callback determine if a route should be used to "handle" a
request by returning a non-falsy value if it can. The "handler" callback
is called when there is a match and should return a Promise that resolves
to a Response
.
Router
The Router can be used to process a FetchEvent through one or more Routes responding with a Request if a matching route exists.
If no route matches a given a request, the Router will use a "default" handler if one is defined.
Should the matching Route throw an error, the Router will use a "catch" handler if one is defined to gracefully deal with issues and respond with a Request.
If a request matches multiple routes, the earliest registered route will be used to respond to the request.
Methods
registerRoute
registerRoute(capture, handler, method) returns module:workbox-routing.Route
Easily register a RegExp, string, or function with a caching strategy to a singleton Router instance.
This method will generate a Route for you if needed and call registerRoute().
Parameter |
|
---|---|
capture |
(RegExp, string, module:workbox-routing.Route~matchCallback, or module:workbox-routing.Route) If the capture param is a |
handler |
Optional module:workbox-routing~handlerCallback A callback
function that returns a Promise resulting in a Response. This parameter
is required if |
method |
Optional string The HTTP method to match the Route against. |
- Returns
-
module:workbox-routing.Route
The generatedRoute
(Useful for unregistering).
setCatchHandler
setCatchHandler(handler)
If a Route throws an error while handling a request, this handler
will be called and given a chance to provide a response.
Parameter |
|
---|---|
handler |
module:workbox-routing~handlerCallback A callback function that returns a Promise resulting in a Response. |
setDefaultHandler
setDefaultHandler(handler)
Define a default handler
that's called when no routes explicitly
match the incoming request.
Without a default handler, unmatched requests will go against the network as if there were no service worker present.
Parameter |
|
---|---|
handler |
module:workbox-routing~handlerCallback A callback function that returns a Promise resulting in a Response. |
Abstract types
handlerCallback
handlerCallback(context) returns Promise containing Response
The "handler" callback is invoked whenever a Router
matches a URL to a
Route
via its match
callback. This callback should return a Promise that resolves with a
Response
.
If a non-empty array or object is returned by the
match callback it
will be passed in as the handler's context.params
argument.
Parameter |
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
context |
Object Values in
|
- Returns
-
Promise containing Response
The response that will fulfill the request.
matchCallback
matchCallback(context) returns any type
The "match" callback is used to determine if a Route
should apply for a
particular URL. When matching occurs in response to a fetch event from the
client, the event
object is supplied in addition to the url
, request
,
and sameOrigin
value. However, since the match callback can be invoked
outside of a fetch event, matching logic should not assume the event
object will always be available.
If the match callback returns a truthy value, the matching route's
handler callback will be
invoked immediately. If the value returned is a non-empty array or object,
that value will be set on the handler's context.params
argument.
Parameter |
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
context |
Object Values in
|
- Returns
-
any type
To signify a match, return a truthy value.