This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The Cache interface provides a storage mechanism for Request / Response object pairs that are cached, for example as part of the ServiceWorker life cycle. Note that the Cache interface is exposed to windowed scopes as well as workers. You don't have to use it in conjunction with service workers, even though it is defined in the service worker spec.

An origin can have multiple, named Cache objects. You are responsible for implementing how your script (e.g. in a ServiceWorker)  handles Cache updates. Items in a Cache do not get updated unless explicitly requested; they don’t expire unless deleted. Use CacheStorage.open() to open a specific named Cache object and then call any of the Cache methods to maintain the Cache.

You are also responsible for periodically purging cache entries. Each browser has a hard limit on the amount of cache storage that a given origin can use. Cache quota usage estimates are available via the StorageEstimate API. The browser does its best to manage disk space, but it may delete the Cache storage for an origin.  The browser will generally delete all of the data for an origin or none of the data for an origin. Make sure to version caches by name and use the caches only from the version of the script that they can safely operate on. See Deleting old caches for more information.

Note: Initial Cache implementations (in both Blink and Gecko) resolve Cache.add(), Cache.addAll(), and Cache.put() promises when the response body is fully written to storage.  More recent versions of the specification state that the browser can resolve the promise as soon as the entry is recorded in the database even if the response body is still streaming in.

Note: The key matching algorithm depends on the VARY header in the value. So matching a new key requires looking at both key and value for entries in the Cache.

Note: The caching API doesn't honor HTTP caching headers.

Methods

Cache.match(request, options)
Returns a Promise that resolves to the response associated with the first matching request in the Cache object.
Cache.matchAll(request, options)
Returns a Promise that resolves to an array of all matching requests in the Cache object.
Cache.add(request)
Takes a URL, retrieves it and adds the resulting response object to the given cache. This is functionally equivalent to calling fetch(), then using put() to add the results to the cache.
Cache.addAll(requests)
Takes an array of URLs, retrieves them, and adds the resulting response objects to the given cache.
Cache.put(request, response)
Takes both a request and its response and adds it to the given cache.
Cache.delete(request, options)
Finds the Cache entry whose key is the request, returning a Promise that resolves to true if a matching Cache entry is found and deleted. If no Cache entry is found, the promise resolves to false.
Cache.keys(request, options)
Returns a Promise that resolves to an array of Cache keys.

Examples

This code snippet is from the service worker selective caching sample. (see selective caching live) The code uses CacheStorage.open() to open any Cache objects with a Content-Type header that starts with "font/".

The code then uses Cache.match() to see if there's already a matching font in the cache, and if so, returns it. If there isn't a matching font, the code fetches the font from the network and uses Cache.put() to cache the fetched resource.

The code handles exceptions thrown from the fetch() operation. Note that an HTTP error response (e.g., 404) will not trigger an exception. It will return a normal response object that has the appropriate error code.

The code snippet also shows a best practice for versioning caches used by the service worker. Though there's only one cache in this example, the same approach can be used for multiple caches. It maps a shorthand identifier for a cache to a specific, versioned cache name. The code also deletes all caches that aren't named in CURRENT_CACHES.

In the code example, "caches" is an attribute of the service worker's WorkerGlobalScope. It holds the CacheStorage object, by which by can access the CacheStorage interface.

Note: In Chrome, visit chrome://inspect/#service-workers and click on the "inspect" link below the registered service worker to view logging statements for the various actions the service-worker.js script is performing.
var CACHE_VERSION = 1;

// Shorthand identifier mapped to specific versioned cache.
var CURRENT_CACHES = {
  font: 'font-cache-v' + CACHE_VERSION
};

self.addEventListener('activate', function(event) {
  var expectedCacheNames = Object.values(CURRENT_CACHES);

  // Active worker won't be treated as activated until promise
  // resolves successfully.
  event.waitUntil(
    caches.keys().then(function(cacheNames) {
      return Promise.all(
        cacheNames.map(function(cacheName) {
          if (!expectedCacheNames.includes(cacheName)) {
            console.log('Deleting out of date cache:', cacheName);
            
            return caches.delete(cacheName);
          }
        })
      );
    })
  );
});

self.addEventListener('fetch', function(event) {
  console.log('Handling fetch event for', event.request.url);

  event.respondWith(
    
    // Opens Cache objects that start with 'font'.
    caches.open(CURRENT_CACHES['font']).then(function(cache) {
      return cache.match(event.request).then(function(response) {
        if (response) {
          console.log('Found response in cache:', response);

          return response;
        }

        console.log('Fetching request from the network');

        return fetch(event.request).then(function(networkResponse) {
          cache.put(event.request, networkResponse.clone());

          return networkResponse;
        });
      }).catch(function(error) {
        
        // Handles exceptions that arise from match() or fetch().
        console.error('Error in fetch handler:', error);

        throw error;
      });
    })
  );
});

Storing cookies in Caches

The Fetch API requires Set-Cookie headers to be stripped before returning a Response object from fetch().  So a Response stored in a Cache won't contain headers.

Specifications

Specification Status Comment
Service Workers
The definition of 'Cache' in that specification.
Working Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
Basic support
Experimental
Chrome Full support 43
Notes
Full support 43
Notes
Notes From 40 to 42, this was only available on service workers.
Edge Full support YesFirefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 30
Notes
Full support 30
Notes
Notes From 27 to 29, this was only available on service workers.
Safari No support NoWebView Android Full support 43
Notes
Full support 43
Notes
Notes From 40 to 42, this was only available on service workers.
Chrome Android Full support 43
Notes
Full support 43
Notes
Notes From 40 to 42, this was only available on service workers.
Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 30
Notes
Full support 30
Notes
Notes From 27 to 29, this was only available on service workers.
Safari iOS No support NoSamsung Internet Android Full support 4.0
add
Experimental
Chrome Full support 44
Notes
Full support 44
Notes
Notes Requires HTTPS from version 46.
Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 31
Notes
Full support 31
Notes
Notes Requires HTTPS from version 33.
Safari No support NoWebView Android Full support 44
Notes
Full support 44
Notes
Notes Requires HTTPS from version 46.
Chrome Android Full support 44
Notes
Full support 44
Notes
Notes Requires HTTPS from version 46.
Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 31
Notes
Full support 31
Notes
Notes Requires HTTPS from version 33.
Safari iOS No support NoSamsung Internet Android Full support 4.0
addAll
Experimental
Chrome Full support 46
Notes
Full support 46
Notes
Notes Requires HTTPS.
Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 33
Notes
Full support 33
Notes
Notes Requires HTTPS.
Safari No support NoWebView Android Full support 46
Notes
Full support 46
Notes
Notes Requires HTTPS.
Chrome Android Full support 46
Notes
Full support 46
Notes
Notes Requires HTTPS.
Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 33
Notes
Full support 33
Notes
Notes Requires HTTPS.
Safari iOS No support NoSamsung Internet Android Full support 5.0
delete
Experimental
Chrome Full support 43Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 30Safari No support NoWebView Android Full support 43Chrome Android Full support 43Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 30Safari iOS No support NoSamsung Internet Android Full support 4.0
keys
Experimental
Chrome Full support 43Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 30Safari No support NoWebView Android Full support 43Chrome Android Full support 43Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 30Safari iOS No support NoSamsung Internet Android Full support 4.0
match
Experimental
Chrome Full support 43Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 30Safari No support NoWebView Android Full support 43Chrome Android Full support 43Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 30Safari iOS No support NoSamsung Internet Android Full support 4.0
matchAll
Experimental
Chrome Full support 47Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 34
Notes
Full support 34
Notes
Notes Requires HTTPS.
Safari No support NoWebView Android Full support 47Chrome Android Full support 47Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 34Safari iOS No support NoSamsung Internet Android Full support 5.0
put
Experimental
Chrome Full support 43
Notes
Full support 43
Notes
Notes Requires HTTPS from version 46.
Edge Full support 16Firefox Full support 39
Notes
Full support 39
Notes
Notes Service workers (and Push) have been disabled in the Firefox 45 & 52 Extended Support Releases (ESR).
IE No support NoOpera Full support 30
Notes
Full support 30
Notes
Notes Requires HTTPS from version 33.
Safari No support NoWebView Android Full support 43
Notes
Full support 43
Notes
Notes Requires HTTPS from version 46.
Chrome Android Full support 43
Notes
Full support 43
Notes
Notes Requires HTTPS from version 46.
Edge Mobile No support NoFirefox Android Full support 39Opera Android Full support 30
Notes
Full support 30
Notes
Notes Requires HTTPS from version 33.
Safari iOS No support NoSamsung Internet Android Full support 4.0

Legend

Full support  
Full support
No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
See implementation notes.
See implementation notes.

See also