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: 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 theCache
object. Cache.matchAll(request, options)
- Returns a
Promise
that resolves to an array of all matching requests in theCache
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 usingput()
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 aPromise
that resolves totrue
if a matchingCache
entry is found and deleted. If noCache
entry is found, the promise resolves tofalse
. Cache.keys(request, options)
- Returns a
Promise
that resolves to an array ofCache
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 a property of the ServiceWorkerGlobalScope
. It holds the CacheStorage
object, by which it can access the CacheStorage
interface. This is an implementation of the WindowOrWorkerGlobalScope
mixin.
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;
var CURRENT_CACHES = {
font: 'font-cache-v' + CACHE_VERSION
};
self.addEventListener('activate', function(event) {
// Delete all caches that aren't named in CURRENT_CACHES.
// While there is only one cache in this example, the same logic will handle the case where
// there are multiple versioned caches.
var expectedCacheNamesSet = new Set(Object.values(CURRENT_CACHES));
event.waitUntil(
caches.keys().then(function(cacheNames) {
return Promise.all(
cacheNames.map(function(cacheName) {
if (!expectedCacheNamesSet.has(cacheName)) {
// If this cache name isn't present in the set of "expected" cache names, then delete it.
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(
caches.open(CURRENT_CACHES.font).then(function(cache) {
return cache.match(event.request).then(function(response) {
if (response) {
// If there is an entry in the cache for event.request, then response will be defined
// and we can just return it. Note that in this example, only font resources are cached.
console.log(' Found response in cache:', response);
return response;
}
// Otherwise, if there is no entry in the cache for event.request, response will be
// undefined, and we need to fetch() the resource.
console.log(' No response for %s found in cache. About to fetch ' +
'from network...', event.request.url);
// We call .clone() on the request since we might use it in a call to cache.put() later on.
// Both fetch() and cache.put() "consume" the request, so we need to make a copy.
// (see https://developer.mozilla.org/en-US/docs/Web/API/Request/clone)
return fetch(event.request.clone()).then(function(response) {
console.log(' Response for %s from network is: %O',
event.request.url, response);
if (response.status < 400 &&
response.headers.has('content-type') &&
response.headers.get('content-type').match(/^font\//i)) {
// This avoids caching responses that we know are errors (i.e. HTTP status code of 4xx or 5xx).
// We also only want to cache responses that correspond to fonts,
// i.e. have a Content-Type response header that starts with "font/".
// Note that for opaque filtered responses (https://fetch.spec.whatwg.org/#concept-filtered-response-opaque)
// we can't access to the response headers, so this check will always fail and the font won't be cached.
// All of the Google Web Fonts are served off of a domain that supports CORS, so that isn't an issue here.
// It is something to keep in mind if you're attempting to cache other resources from a cross-origin
// domain that doesn't support CORS, though!
// We call .clone() on the response to save a copy of it to the cache. By doing so, we get to keep
// the original response object which we will return back to the controlled page.
// (see https://developer.mozilla.org/en-US/docs/Web/API/Request/clone)
console.log(' Caching the response to', event.request.url);
cache.put(event.request, response.clone());
} else {
console.log(' Not caching the response to', event.request.url);
}
// Return the original response object, which will be used to fulfill the resource request.
return response;
});
}).catch(function(error) {
// This catch() will handle exceptions that arise from the match() or fetch() operations.
// Note that a HTTP error response (e.g. 404) will NOT trigger an exception.
// It will return a normal response object that has the appropriate error code set.
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 WorkersThe definition of 'Cache' in that specification. | Working Draft | Initial definition. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Chrome Full support 43 Full support 43 Notes' From 40 to 42, this was only available on service workers. |
Edge
Full support ≤18 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera Full support 30 Full support 30 Notes' From 27 to 29, this was only available on service workers. |
Safari
Full support 11 |
WebView Android Full support 43 Full support 43 Notes' From 40 to 42, this was only available on service workers. |
Chrome Android Full support 43 Full support 43 Notes' From 40 to 42, this was only available on service workers. |
Firefox Android
Full support 39 |
Opera Android Full support 30 Full support 30 Notes' From 27 to 29, this was only available on service workers. |
Safari iOS
Full support 11 |
Samsung Internet Android Full support 4.0 Full support 4.0 Notes' From 40 to 42, this was only available on service workers. |
Chrome Full support 44 Full support 44 Notes' Requires HTTPS from version 46. |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera Full support 31 Full support 31 Notes' Requires HTTPS from version 33. |
Safari
Full support 11 |
WebView Android Full support 44 Full support 44 Notes' Requires HTTPS from version 46. |
Chrome Android Full support 44 Full support 44 Notes' Requires HTTPS from version 46. |
Firefox Android
Full support 39 |
Opera Android Full support 32 Full support 32 Notes' Requires HTTPS from version 33. |
Safari iOS
Full support 11 |
Samsung Internet Android Full support 4.0 Full support 4.0 Notes' Requires HTTPS from Samsung Internet 5.0. | |
Chrome Full support 46 Full support 46 Notes' Requires HTTPS. |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera Full support 33 Full support 33 Notes' Requires HTTPS. |
Safari
Full support 11 |
WebView Android Full support 46 Full support 46 Notes' Requires HTTPS. |
Chrome Android Full support 46 Full support 46 Notes' Requires HTTPS. |
Firefox Android
Full support 39 |
Opera Android Full support 33 Full support 33 Notes' Requires HTTPS. |
Safari iOS
Full support 11 |
Samsung Internet Android Full support 5.0 Full support 5.0 Notes' Requires HTTPS. | |
Chrome
Full support 43 |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera
Full support 30 |
Safari
Full support 11 |
WebView Android
Full support 43 |
Chrome Android
Full support 43 |
Firefox Android
Full support 39 |
Opera Android
Full support 30 |
Safari iOS
Full support 11 |
Samsung Internet Android
Full support 4.0 | |
Chrome
Full support 43 |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera
Full support 30 |
Safari
Full support 11 |
WebView Android
Full support 43 |
Chrome Android
Full support 43 |
Firefox Android
Full support 39 |
Opera Android
Full support 30 |
Safari iOS
Full support 11 |
Samsung Internet Android
Full support 4.0 | |
Chrome
Full support 43 |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera
Full support 30 |
Safari
Full support 11 |
WebView Android
Full support 43 |
Chrome Android
Full support 43 |
Firefox Android
Full support 39 |
Opera Android
Full support 30 |
Safari iOS
Full support 11 |
Samsung Internet Android
Full support 4.0 | |
Chrome
Full support 47 |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera Full support 34 Full support 34 Notes' Requires HTTPS. |
Safari
Full support 11 |
WebView Android
Full support 47 |
Chrome Android
Full support 47 |
Firefox Android
Full support 39 |
Opera Android
Full support 34 |
Safari iOS
Full support 11 |
Samsung Internet Android
Full support 5.0 | |
Chrome Full support 43 Full support 43 Notes' Requires HTTPS from version 46. |
Edge
Full support 16 |
Firefox Full support 39 Full support 39 Notes' Extended Support Releases (ESR) before Firefox 78 ESR do not support service workers and the Push API. |
IE
No support No |
Opera Full support 30 Full support 30 Notes' Requires HTTPS from version 33. |
Safari
Full support 11 |
WebView Android Full support 43 Full support 43 Notes' Requires HTTPS from version 46. |
Chrome Android Full support 43 Full support 43 Notes' Requires HTTPS from version 46. |
Firefox Android
Full support 39 |
Opera Android Full support 30 Full support 30 Notes' Requires HTTPS from version 33. |
Safari iOS
Full support 11 |
Samsung Internet Android Full support 4.0 Full support 4.0 Notes' Requires HTTPS from Samsung Internet 5.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
- Using Service Workers
- Service workers basic code example
- Is ServiceWorker ready?
Promise
- Using web workers
Cache by Mozilla Contributors is licensed under CC-BY-SA 2.5.