Module: workbox-routing

workbox-routing

module

Version     6.2.0

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.

See the module docs for info.

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

static

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 Route, all other arguments will be ignored.
handler	Optional module:workbox-routing~handlerCallback A callback function that returns a Promise resulting in a Response. This parameter is required if capture is not a Route object.
method	Optional string The HTTP method to match the Route against.

Returns

module:workbox-routing.Route The generated Route(Useful for unregistering).

setCatchHandler

static

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

static

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

inner

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 context have the following properties: Parameter request (Request or string) The corresponding request. url URL The URL that matched, if available. event ExtendableEvent The corresponding event that triggered the request. params Optional Object Array or Object parameters returned by the Route's match callback. This will be undefined if an empty array or object were returned.

Returns

Promise containing Response The response that will fulfill the request.

matchCallback

inner

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 context have the following properties: Parameter request Request The corresponding request. url URL The request's URL. event ExtendableEvent The corresponding event that triggered the request. sameOrigin boolean The result of comparing url.origin against the current origin.

Returns

any type To signify a match, return a truthy value.