workbox-routing

    Summary

    Types

    NavigationRoute

    NavigationRoute makes it easy to create a workbox-routing.Route that matches for browser [navigation requests]https://developers.google.com/web/fundamentals/primers/service-workers/high-performance-loading#first_what_are_navigation_requests.

    It will only match incoming Requests whose https://fetch.spec.whatwg.org/#concept-request-mode|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.

    Properties

    • constructor

      function

      If both denylist and allowlist are provided, the denylist will take precedence and the request will not match this route.

      The regular expressions in allowlist and denylist are matched against the concatenated [pathname]https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/pathname and [search]https://developer.mozilla.org/en-US/docs/Web/API/HTMLHyperlinkElementUtils/search portions of the requested URL.

      Note: These RegExps may be evaluated against every destination URL during a navigation. Avoid using complex RegExps, or else your users may see delays when navigating your site.

      The constructor function looks like: (handler: RouteHandler, options?: NavigationRouteMatchOptions) => {...}

    • catchHandler
    • method

      HTTPMethod

    • setCatchHandler

      function

      The setCatchHandler function looks like: (handler: RouteHandler) => {...}

      • A callback function that returns a Promise resolving to a Response

    NavigationRouteMatchOptions

    Properties

    • allowlist

      RegExp[] optional

    • denylist

      RegExp[] optional

    RegExpRoute

    RegExpRoute makes it easy to create a regular expression based workbox-routing.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.

    Properties

    • constructor

      function

      If the regular expression contains [capture groups]https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#grouping-back-references, the captured values will be passed to the workbox-routing~handlerCallback params argument.

      The constructor function looks like: (regExp: RegExp, handler: RouteHandler, method?: HTTPMethod) => {...}

      • regExp

        RegExp

        The regular expression to match against URLs.

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

      • method

        HTTPMethod optional

    • catchHandler
    • method

      HTTPMethod

    • setCatchHandler

      function

      The setCatchHandler function looks like: (handler: RouteHandler) => {...}

      • A callback function that returns a Promise resolving to a Response

    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.

    Properties

    Router

    The Router can be used to process a FetchEvent using one or more workbox-routing.Route, responding with a Response 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.

    Properties

    • constructor

      function

      Initializes a new Router.

      The constructor function looks like: () => {...}

    • routes

      Map<HTTPMethodRoute[]>

    • addCacheListener

      function

      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'}],
          ],
        },
      }
      

      The addCacheListener function looks like: () => {...}

    • addFetchListener

      function

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

      The addFetchListener function looks like: () => {...}

    • findMatchingRoute

      function

      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.

      The findMatchingRoute function looks like: (options: RouteMatchCallbackOptions) => {...}

      • returns

        object

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

    • handleRequest

      function

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

      The handleRequest function looks like: (options: object) => {...}

      • options

        object

        • event

          ExtendableEvent

          The event that triggered the request.

        • request

          Request

          The request to handle.

      • returns

        Promise<Response>

        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

      function

      Registers a route with the router.

      The registerRoute function looks like: (route: Route) => {...}

      • route

        The route to register.

    • setCatchHandler

      function

      If a Route throws an error while handling a request, this handler will be called and given a chance to provide a response.

      The setCatchHandler function looks like: (handler: RouteHandler) => {...}

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

    • setDefaultHandler

      function

      Define a default handler that's called when no routes explicitly match the incoming request.

      Each HTTP method ('GET', 'POST', etc.) gets its own default handler.

      Without a default handler, unmatched requests will go against the network as if there were no service worker present.

      The setDefaultHandler function looks like: (handler: RouteHandler, method?: HTTPMethod) => {...}

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

      • method

        HTTPMethod optional

    • unregisterRoute

      function

      Unregisters a route with the router.

      The unregisterRoute function looks like: (route: Route) => {...}

      • route

        The route to unregister.

    Methods

    registerRoute

    workbox-routing.registerRoute(
      capture: string | RegExp | RouteMatchCallback | Route,
      handler?: RouteHandler,
      method?: HTTPMethod,
    )

    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 workbox-routing.Router#registerRoute.

    Parameters

    • capture

      string | RegExp | RouteMatchCallback | Route

      If the capture param is a Route, all other arguments will be ignored.

    • handler

      RouteHandler optional

    • method

      HTTPMethod optional

    Returns

    • The generated Route.

    setCatchHandler

    workbox-routing.setCatchHandler(
      handler: RouteHandler,
    )

    If a Route throws an error while handling a request, this handler will be called and given a chance to provide a response.

    Parameters

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

    setDefaultHandler

    workbox-routing.setDefaultHandler(
      handler: RouteHandler,
    )

    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.

    Parameters

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

    We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.