Get Inspired
Docs
Blog
Articles
Workbox
Service worker overview A service worker's life Strategies for service worker caching What is Workbox?
Expectations around service worker deployment Removing buggy service workers Improving the service worker development experience Troubleshooting and logging Different service worker strategies for different architectures Service workers and the application shell model Navigation Preload for Network-first HTML Faster multipage applications with streams Precaching dos and don'ts Understanding storage quota
The ways of Workbox Precaching with Workbox Using Workbox without precaching Framework integrations
Using workbox-window Caching resources during runtime Forcing a network timeout Access caches from the window Serving cached audio and video Managing fallback responses Handling service worker updates with immediacy Retrying requests when back online Using plugins
Workbox Modules API Reference Migration Guides Workbox on GitHub
Workbox
Service worker overview A service worker's life Strategies for service worker caching What is Workbox?
Expectations around service worker deployment Removing buggy service workers Improving the service worker development experience Troubleshooting and logging Different service worker strategies for different architectures Service workers and the application shell model Navigation Preload for Network-first HTML Faster multipage applications with streams Precaching dos and don'ts Understanding storage quota
The ways of Workbox Precaching with Workbox Using Workbox without precaching Framework integrations
Using workbox-window Caching resources during runtime Forcing a network timeout Access caches from the window Serving cached audio and video Managing fallback responses Handling service worker updates with immediacy Retrying requests when back online Using plugins
Workbox Modules API Reference Migration Guides Workbox on GitHub

workbox-strategies

    Summary

    Types

    CacheFirst

    An implementation of a cache-first request strategy.

    A cache first strategy is useful for assets that have been revisioned, such as URLs like /styles/example.a8f5f1.css, since they can be cached for long periods of time.

    If the network request fails, and there is no cache match, this will throw a WorkboxError exception.

    Properties

    • constructor

      void

      Creates a new instance of the strategy and sets all documented option properties as public instance properties.

      Note: if a custom strategy class extends the base Strategy class and does not need more than these properties, it does not need to define its own constructor.

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

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • _awaitComplete

      void

      The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • responseDone

        Promise<Response>

      • request

        Request

      • event

        ExtendableEvent

      • returns

        Promise<void>

    • _getResponse

      void

      The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • returns

        Promise<Response>

    • handle

      void

      Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.

      When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.

      Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().

      The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        Promise<Response>

    • handleAll

      void

      Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.

      You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.

      The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        [Promise<Response>, Promise<void>]

        A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

    CacheOnly

    An implementation of a cache-only request strategy.

    This class is useful if you want to take advantage of any Workbox plugins.

    If there is no cache match, this will throw a WorkboxError exception.

    Properties

    • constructor

      void

      Creates a new instance of the strategy and sets all documented option properties as public instance properties.

      Note: if a custom strategy class extends the base Strategy class and does not need more than these properties, it does not need to define its own constructor.

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

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • _awaitComplete

      void

      The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • responseDone

        Promise<Response>

      • request

        Request

      • event

        ExtendableEvent

      • returns

        Promise<void>

    • _getResponse

      void

      The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • returns

        Promise<Response>

    • handle

      void

      Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.

      When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.

      Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().

      The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        Promise<Response>

    • handleAll

      void

      Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.

      You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.

      The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        [Promise<Response>, Promise<void>]

        A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

    NetworkFirst

    An implementation of a network first request strategy.

    By default, this strategy will cache responses with a 200 status code as well as opaque responses. Opaque responses are are cross-origin requests where the response doesn't support CORS.

    If the network request fails, and there is no cache match, this will throw a WorkboxError exception.

    Properties

    • constructor

      void

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

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • _awaitComplete

      void

      The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • responseDone

        Promise<Response>

      • request

        Request

      • event

        ExtendableEvent

      • returns

        Promise<void>

    • _getResponse

      void

      The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • returns

        Promise<Response>

    • handle

      void

      Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.

      When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.

      Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().

      The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        Promise<Response>

    • handleAll

      void

      Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.

      You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.

      The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        [Promise<Response>, Promise<void>]

        A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

    NetworkFirstOptions

    Properties

    • cacheName

      string optional

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • networkTimeoutSeconds

      number optional

    • plugins

      WorkboxPlugin[] optional

    NetworkOnly

    An implementation of a network-only request strategy.

    This class is useful if you want to take advantage of any Workbox plugins.

    If the network request fails, this will throw a WorkboxError exception.

    Properties

    • constructor

      void

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

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • _awaitComplete

      void

      The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • responseDone

        Promise<Response>

      • request

        Request

      • event

        ExtendableEvent

      • returns

        Promise<void>

    • _getResponse

      void

      The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • returns

        Promise<Response>

    • handle

      void

      Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.

      When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.

      Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().

      The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        Promise<Response>

    • handleAll

      void

      Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.

      You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.

      The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        [Promise<Response>, Promise<void>]

        A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

    NetworkOnlyOptions

    Properties

    • fetchOptions

      RequestInit optional

    • networkTimeoutSeconds

      number optional

    • plugins

      WorkboxPlugin[] optional

    StaleWhileRevalidate

    An implementation of a stale-while-revalidate request strategy.

    Resources are requested from both the cache and the network in parallel. The strategy will respond with the cached version if available, otherwise wait for the network response. The cache is updated with the network response with each successful request.

    By default, this strategy will cache responses with a 200 status code as well as opaque responses. Opaque responses are cross-origin requests where the response doesn't support CORS.

    If the network request fails, and there is no cache match, this will throw a WorkboxError exception.

    Properties

    • constructor

      void

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

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • _awaitComplete

      void

      The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • responseDone

        Promise<Response>

      • request

        Request

      • event

        ExtendableEvent

      • returns

        Promise<void>

    • _getResponse

      void

      The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • returns

        Promise<Response>

    • handle

      void

      Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.

      When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.

      Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().

      The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        Promise<Response>

    • handleAll

      void

      Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.

      You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.

      The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        [Promise<Response>, Promise<void>]

        A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

    Strategy

    An abstract base class that all other strategy classes must extend from:

    Properties

    • constructor

      void

      Creates a new instance of the strategy and sets all documented option properties as public instance properties.

      Note: if a custom strategy class extends the base Strategy class and does not need more than these properties, it does not need to define its own constructor.

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

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • _awaitComplete

      void

      The _awaitComplete function looks like: (responseDone: Promise<Response>, handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • responseDone

        Promise<Response>

      • request

        Request

      • event

        ExtendableEvent

      • returns

        Promise<void>

    • _getResponse

      void

      The _getResponse function looks like: (handler: StrategyHandler, request: Request, event: ExtendableEvent) => {...}

      • returns

        Promise<Response>

    • _handle

      void

      The _handle function looks like: (request: Request, handler: StrategyHandler) => {...}

      • returns

        Promise<Response>

    • handle

      void

      Perform a request strategy and returns a Promise that will resolve with a Response, invoking all relevant plugin callbacks.

      When a strategy instance is registered with a Workbox workbox-routing.Route, this method is automatically called when the route matches.

      Alternatively, this method can be used in a standalone FetchEvent listener by passing it to event.respondWith().

      The handle function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        Promise<Response>

    • handleAll

      void

      Similar to workbox-strategies.Strategy~handle, but instead of just returning a Promise that resolves to a Response it it will return an tuple of [response, done] promises, where the former (response) is equivalent to what handle() returns, and the latter is a Promise that will resolve once any promises that were added to event.waitUntil() as part of performing the strategy have completed.

      You can await the done promise to ensure any extra work performed by the strategy (usually caching responses) completes successfully.

      The handleAll function looks like: (options: FetchEvent | HandlerCallbackOptions) => {...}

      • returns

        [Promise<Response>, Promise<void>]

        A tuple of [response, done] promises that can be used to determine when the response resolves as well as when the handler has completed all its work.

    StrategyHandler

    A class created every time a Strategy instance instance calls workbox-strategies.Strategy~handle or workbox-strategies.Strategy~handleAll that wraps all fetch and cache actions around plugin callbacks and keeps track of when the strategy is "done" (i.e. all added event.waitUntil() promises have resolved).

    Properties

    • constructor

      void

      Creates a new instance associated with the passed strategy and event that's handling the request.

      The constructor also initializes the state that will be passed to each of the plugins handling this request.

      The constructor function looks like: (strategy: Strategy, options: HandlerCallbackOptions) => {...}

    • event

      ExtendableEvent

    • params

      any optional

    • request

      Request

    • url

      URL optional

    • cacheMatch

      void

      Matches a request from the cache (and invokes any applicable plugin callback methods) using the cacheName, matchOptions, and plugins defined on the strategy object.

      The following plugin lifecycle methods are invoked when using this method:

      • cacheKeyWillByUsed()
      • cachedResponseWillByUsed()

      The cacheMatch function looks like: (key: RequestInfo) => {...}

      • key

        RequestInfo

        The Request or URL to use as the cache key.

      • returns

        Promise<Response>

        A matching response, if found.

    • cachePut

      void

      Puts a request/response pair in the cache (and invokes any applicable plugin callback methods) using the cacheName and plugins defined on the strategy object.

      The following plugin lifecycle methods are invoked when using this method:

      • cacheKeyWillByUsed()
      • cacheWillUpdate()
      • cacheDidUpdate()

      The cachePut function looks like: (key: RequestInfo, response: Response) => {...}

      • key

        RequestInfo

        The request or URL to use as the cache key.

      • response

        Response

        The response to cache.

      • returns

        Promise<boolean>

        false if a cacheWillUpdate caused the response not be cached, and true otherwise.

    • destroy

      void

      Stops running the strategy and immediately resolves any pending waitUntil() promises.

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

    • doneWaiting

      void

      Returns a promise that resolves once all promises passed to workbox-strategies.StrategyHandler~waitUntil have settled.

      Note: any work done after doneWaiting() settles should be manually passed to an event's waitUntil() method (not this handler's waitUntil() method), otherwise the service worker thread my be killed prior to your work completing.

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

      • returns

        Promise<void>

    • fetch

      void

      Fetches a given request (and invokes any applicable plugin callback methods) using the fetchOptions (for non-navigation requests) and plugins defined on the Strategy object.

      The following plugin lifecycle methods are invoked when using this method:

      • requestWillFetch()
      • fetchDidSucceed()
      • fetchDidFail()

      The fetch function looks like: (input: RequestInfo) => {...}

      • input

        RequestInfo

        The URL or request to fetch.

      • returns

        Promise<Response>

    • fetchAndCachePut

      void

      Calls this.fetch() and (in the background) runs this.cachePut() on the response generated by this.fetch().

      The call to this.cachePut() automatically invokes this.waitUntil(), so you do not have to manually call waitUntil() on the event.

      The fetchAndCachePut function looks like: (input: RequestInfo) => {...}

      • input

        RequestInfo

        The request or URL to fetch and cache.

      • returns

        Promise<Response>

    • getCacheKey

      void

      Checks the list of plugins for the cacheKeyWillBeUsed callback, and executes any of those callbacks found in sequence. The final Request object returned by the last plugin is treated as the cache key for cache reads and/or writes. If no cacheKeyWillBeUsed plugin callbacks have been registered, the passed request is returned unmodified

      The getCacheKey function looks like: (request: Request, mode: "read"
      | "write"
      ) => {...}

      • request

        Request

      • mode

        "read"
        | "write"

      • returns

        Promise<Request>

    • hasCallback

      void

      Returns true if the strategy has at least one plugin with the given callback.

      The hasCallback function looks like: (name: C) => {...}

      • name

        C

        The name of the callback to check for.

      • returns

        boolean

    • iterateCallbacks

      void

      Accepts a callback and returns an iterable of matching plugin callbacks, where each callback is wrapped with the current handler state (i.e. when you call each callback, whatever object parameter you pass it will be merged with the plugin's current state).

      The iterateCallbacks function looks like: (name: C) => {...}

      • name

        C

        The name fo the callback to run

      • returns

        Generator<NonNullable<indexedAccess>anyunknown>

    • runCallbacks

      void

      Runs all plugin callbacks matching the given name, in order, passing the given param object (merged ith the current plugin state) as the only argument.

      Note: since this method runs all plugins, it's not suitable for cases where the return value of a callback needs to be applied prior to calling the next callback. See workbox-strategies.StrategyHandler#iterateCallbacks below for how to handle that case.

      The runCallbacks function looks like: (name: C, param: Omit<indexedAccess"state"
      >      ) => {...}

      • name

        C

        The name of the callback to run within each plugin.

      • param

        Omit<indexedAccess"state"
        >

        The object to pass as the first (and only) param when executing each callback. This object will be merged with the current plugin state prior to callback execution.

      • returns

        Promise<void>

    • waitUntil

      void

      Adds a promise to the [extend lifetime promises]https://w3c.github.io/ServiceWorker/#extendableevent-extend-lifetime-promises of the event event associated with the request being handled (usually a FetchEvent).

      Note: you can await workbox-strategies.StrategyHandler~doneWaiting to know when all added promises have settled.

      The waitUntil function looks like: (promise: Promise<T>) => {...}

      • promise

        Promise<T>

        A promise to add to the extend lifetime promises of the event that triggered the request.

      • returns

        Promise<T>

    StrategyOptions

    Properties

    • cacheName

      string optional

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[] optional

    This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.