workbox.routing.Router

class   static
Version     v4.3.1

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.

Constructor

Router

new Router()

Initializes a new Router.

Property

routes

Returns

Object with Array of workbox.routing.Route properties routes A Map of HTTP method name ('GET', etc.) to an array of all the corresponding Route instances that are registered.

Methods

addCacheListener

addCacheListener()

Adds a message event listener for URLs to cache from the window. This is useful to cache resources loaded on the page prior to when the service worker started controlling it.

The format of the message data sent from the window should be as follows. Where the urlsToCache array may consist of URL strings or an array of URL string + requestInit object (the same as you'd pass to fetch()).

{
  type: 'CACHE_URLS',
  payload: {
    urlsToCache: [
      './script1.js',
      './script2.js',
      ['./script3.js', {mode: 'no-cors'}],
    ],
  },
}

addFetchListener

addFetchListener()

Adds a fetch event listener to respond to events when a route matches the event's request.

findMatchingRoute

findMatchingRoute(options) returns Object

Checks a request and URL (and optionally an event) against the list of registered routes, and if there's a match, returns the corresponding route along with any params generated by the match.

Parameter

options

Object

Values in options have the following properties:

Parameter

url

URL

request

Request

The request to match.

event

Optional

FetchEvent

The corresponding event (unless N/A).
Returns

Object An object with route and params properties. They are populated if a matching route was found or undefined otherwise.

handleRequest

handleRequest(options) returns (Promise containing Response or undefined)

Apply the routing rules to a FetchEvent object to get a Response from an appropriate Route's handler.

Parameter

options

Object

Values in options have the following properties:

Parameter

request

Request

The request to handle (this is usually from a fetch event, but it does not have to be).

event

Optional

FetchEvent

The event that triggered the request, if applicable.
Returns

(Promise containing Response or undefined) A promise is returned if a registered route can handle the request. If there is no matching route and there's no defaultHandler, undefined is returned.

registerRoute

registerRoute(route)

Registers a route with the router.

Parameter

route

workbox.routing.Route

The route to register.

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

workbox.routing.Route~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

workbox.routing.Route~handlerCallback

A callback function that returns a Promise resulting in a Response.

unregisterRoute

unregisterRoute(route)

Unregisters a route with the router.

Parameter

route

workbox.routing.Route

The route to unregister.