Home
Docs
Blog
Articles
Home
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-precaching

    Summary

    Types

    CleanupResult

    Properties

    • deletedCacheRequests

      string[]

    InstallResult

    Properties

    • notUpdatedURLs

      string[]

    • updatedURLs

      string[]

    PrecacheController

    Performs efficient precaching of assets.

    Properties

    • constructor

      function

      Create a new PrecacheController.

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

      • options

        PrecacheControllerOptions optional

    • strategy

      Strategy

    • activate

      function

      Deletes assets that are no longer present in the current precache manifest. Call this method from the service worker activate event.

      Note: this method calls event.waitUntil() for you, so you do not need to call it yourself in your event handlers.

      The activate function looks like: (event: ExtendableEvent) => {...}

      • event

        ExtendableEvent

    • addToCacheList

      function

      This method will add items to the precache list, removing duplicates and ensuring the information is valid.

      The addToCacheList function looks like: (entries: (string | PrecacheEntry)[]) => {...}

    • createHandlerBoundToURL

      function

      Returns a function that looks up url in the precache (taking into account revision information), and returns the corresponding Response.

      The createHandlerBoundToURL function looks like: (url: string) => {...}

      • url

        string

        The precached URL which will be used to lookup the Response.

    • getCacheKeyForURL

      function

      Returns the cache key used for storing a given URL. If that URL is unversioned, like `/index.html', then the cache key will be the original URL with a search parameter appended to it.

      The getCacheKeyForURL function looks like: (url: string) => {...}

      • url

        string

        A URL whose cache key you want to look up.

      • returns

        string

        The versioned URL that corresponds to a cache key for the original URL, or undefined if that URL isn't precached.

    • getCachedURLs

      function

      Returns a list of all the URLs that have been precached by the current service worker.

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

      • returns

        string[]

        The precached URLs.

    • getIntegrityForCacheKey

      function

      The getIntegrityForCacheKey function looks like: (cacheKey: string) => {...}

      • cacheKey

        string

      • returns

        string

        The subresource integrity associated with the cache key, or undefined if it's not set.

    • getURLsToCacheKeys

      function

      Returns a mapping of a precached URL to the corresponding cache key, taking into account the revision information for the URL.

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

      • returns

        Map<stringstring>

        A URL to cache key mapping.

    • install

      function

      Precaches new and updated assets. Call this method from the service worker install event.

      Note: this method calls event.waitUntil() for you, so you do not need to call it yourself in your event handlers.

      The install function looks like: (event: ExtendableEvent) => {...}

      • event

        ExtendableEvent

    • matchPrecache

      function

      This acts as a drop-in replacement for cache.match() with the following differences:

      • It knows what the name of the precache is, and only checks in that cache.
      • It allows you to pass in an "original" URL without versioning parameters, and it will automatically look up the correct cache key for the currently active revision of that URL.

      E.g., matchPrecache('index.html') will find the correct precached response for the currently active service worker, even if the actual cache key is '/index.html?__WB_REVISION__=1234abcd'.

      The matchPrecache function looks like: (request: string | Request) => {...}

      • request

        string | Request

        The key (without revisioning parameters) to look up in the precache.

      • returns

        Promise<Response>

    • precache

      function

      Adds items to the precache list, removing any duplicates and stores the files in the cache" when the service worker installs.

      This method can be called multiple times.

      The precache function looks like: (entries: (string | PrecacheEntry)[]) => {...}

    PrecacheEntry

    Properties

    • integrity

      string optional

    • revision

      string optional

    • url

      string

    PrecacheFallbackPlugin

    PrecacheFallbackPlugin allows you to specify an "offline fallback" response to be used when a given strategy is unable to generate a response.

    It does this by intercepting the handlerDidError plugin callback and returning a precached response, taking the expected revision parameter into account automatically.

    Unless you explicitly pass in a PrecacheController instance to the constructor, the default instance will be used. Generally speaking, most developers will end up using the default.

    Properties

    • constructor

      function

      Constructs a new PrecacheFallbackPlugin with the associated fallbackURL.

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

      • config

        object

        • fallbackURL

          string

          A precached URL to use as the fallback if the associated strategy can't generate a response.

        • precacheController

          PrecacheController optional

    PrecacheRoute

    A subclass of workbox-routing.Route that takes a workbox-precaching.PrecacheController instance and uses it to match incoming requests and handle fetching responses from the precache.

    Properties

    PrecacheRouteOptions

    Properties

    • cleanURLs

      boolean optional

    • directoryIndex

      string optional

    • ignoreURLParametersMatching

      RegExp[] optional

    • urlManipulation

      urlManipulation optional

    PrecacheStrategy

    A workbox-strategies.Strategy implementation specifically designed to work with workbox-precaching.PrecacheController to both cache and fetch precached assets.

    Note: an instance of this class is created automatically when creating a PrecacheController; it's generally not necessary to create this yourself.

    Properties

    • constructor

      function

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

      • options

        PrecacheStrategyOptions optional

    • cacheName

      string

    • fetchOptions

      RequestInit optional

    • matchOptions

      CacheQueryOptions optional

    • plugins

      WorkboxPlugin[]

    • copyRedirectedCacheableResponsesPlugin

      WorkboxPlugin

    • defaultPrecacheCacheabilityPlugin

      WorkboxPlugin

    • _awaitComplete

      function

      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

      function

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

      • returns

        Promise<Response>

    • _handleFetch

      function

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

      • returns

        Promise<Response>

    • _handleInstall

      function

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

      • returns

        Promise<Response>

    • handle

      function

      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

      function

      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.

    urlManipulation

    workbox-precaching.urlManipulation(
      { url }: object,
    )

    Type

    function

    Parameters

    • { url }

      object

      • url

        URL

    Returns

    • URL[]

    Methods

    addPlugins

    workbox-precaching.addPlugins(
      plugins: WorkboxPlugin[],
    )

    Adds plugins to the precaching strategy.

    Parameters

    addRoute

    workbox-precaching.addRoute(
      options?: PrecacheRouteOptions,
    )

    Add a fetch listener to the service worker that will respond to [network requests]https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API/Using_Service_Workers#Custom_responses_to_requests with precached assets.

    Requests for assets that aren't precached, the FetchEvent will not be responded to, allowing the event to fall through to other fetch event listeners.

    Parameters

    cleanupOutdatedCaches

    workbox-precaching.cleanupOutdatedCaches()

    Adds an activate event listener which will clean up incompatible precaches that were created by older versions of Workbox.

    createHandlerBoundToURL

    workbox-precaching.createHandlerBoundToURL(
      url: string,
    )

    Helper function that calls PrecacheController#createHandlerBoundToURL on the default PrecacheController instance.

    If you are creating your own PrecacheController, then call the PrecacheController#createHandlerBoundToURL on that instance, instead of using this function.

    Parameters

    • url

      string

      The precached URL which will be used to lookup the Response.

    Returns

    getCacheKeyForURL

    workbox-precaching.getCacheKeyForURL(
      url: string,
    )

    Takes in a URL, and returns the corresponding URL that could be used to lookup the entry in the precache.

    If a relative URL is provided, the location of the service worker file will be used as the base.

    For precached entries without revision information, the cache key will be the same as the original URL.

    For precached entries with revision information, the cache key will be the original URL with the addition of a query parameter used for keeping track of the revision info.

    Parameters

    • url

      string

      The URL whose cache key to look up.

    Returns

    • string | undefined

      The cache key that corresponds to that URL.

    matchPrecache

    workbox-precaching.matchPrecache(
      request: string | Request,
    )

    Helper function that calls PrecacheController#matchPrecache on the default PrecacheController instance.

    If you are creating your own PrecacheController, then call PrecacheController#matchPrecache on that instance, instead of using this function.

    Parameters

    • request

      string | Request

      The key (without revisioning parameters) to look up in the precache.

    Returns

    • Promise<Response | undefined>

    precache

    workbox-precaching.precache(
      entries: (string | PrecacheEntry)[],
    )

    Adds items to the precache list, removing any duplicates and stores the files in the cache" when the service worker installs.

    This method can be called multiple times.

    Please note: This method will not serve any of the cached files for you. It only precaches files. To respond to a network request you call workbox-precaching.addRoute.

    If you have a single array of files to precache, you can just call workbox-precaching.precacheAndRoute.

    Parameters

    precacheAndRoute

    workbox-precaching.precacheAndRoute(
      entries: (string | PrecacheEntry)[],
      options?: PrecacheRouteOptions,
    )

    This method will add entries to the precache list and add a route to respond to fetch events.

    This is a convenience method that will call workbox-precaching.precache and workbox-precaching.addRoute in a single call.

    Parameters

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