Join us for web.dev LIVE, a digital event from June 30th to July 2nd to learn modern web techniques. More at web.dev/live

Class: PrecacheController

Constructor

PrecacheController

new PrecacheController(cacheName)

Create a new PrecacheController.

Parameter

cacheName

Optional

string

An optional name for the cache, to override the default precache name.

Methods

activate

async

activate() returns Promise containing module:workbox-precaching.CleanupResult

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

Returns

Promise containing module:workbox-precaching.CleanupResult 

addToCacheList

addToCacheList(entries)

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

Parameter

entries

Array of (module:workbox-precaching.PrecacheController.PrecacheEntry or string)

Array of entries to precache.

createHandler

createHandler(fallbackToNetwork) returns module:workbox-routing~handlerCallback

Returns a function that can be used within a module:workbox-routing.Route that will find a response for the incoming request against the precache.

If for an unexpected reason there is a cache miss for the request, this will fall back to retrieving the Response via fetch() when fallbackToNetwork is true.

Parameter

fallbackToNetwork

Optional

boolean

Whether to attempt to get the response from the network if there's a precache miss.

Returns

module:workbox-routing~handlerCallback 

createHandlerBoundToURL

createHandlerBoundToURL(url, fallbackToNetwork) returns module:workbox-routing~handlerCallback

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

If for an unexpected reason there is a cache miss when looking up url, this will fall back to retrieving the Response via fetch() when fallbackToNetwork is true.

Parameter

url

string

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

fallbackToNetwork

Optional

boolean

Whether to attempt to get the response from the network if there's a precache miss.

Returns

module:workbox-routing~handlerCallback 

getCachedURLs

getCachedURLs() returns Array of string

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

Returns

Array of string The precached URLs.

getCacheKeyForURL

getCacheKeyForURL(url) returns string

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.

Parameter

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.

getURLsToCacheKeys

getURLsToCacheKeys() returns Object with string properties

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

Returns

Object with string properties A URL to cache key mapping.

install

async

install(options) returns Promise containing module:workbox-precaching.InstallResult

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

Parameter

options

Object

Values in options have the following properties:

Parameter

event

Optional

Event

The install event (if needed).

plugins

Optional

Array of Object

Plugins to be used for fetching and caching during install.

Returns

Promise containing module:workbox-precaching.InstallResult 

matchPrecache

async

matchPrecache(request) returns Promise containing (Response or undefined)

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'.

Parameter

request

(string or Request)

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

Returns

Promise containing (Response or undefined)