The Cache
interface provides a persistent storage mechanism for Request
/ Response
object pairs that are cached in long lived memory. How long a Cache
object lives is browser dependent, but a single origin's scripts can typically rely on the presence of a previously populated Cache
object. 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 StorageManager.estimate()
method. 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
object.
Note: The caching API doesn't honor HTTP caching headers.
Instance 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 responses 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 a property of the ServiceWorkerGlobalScope
. It holds the CacheStorage
object, by which it 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.
const CACHE_VERSION = 1;
const CURRENT_CACHES = {
font: `font-cache-v${CACHE_VERSION}`,
};
self.addEventListener("activate", (event) => {
const expectedCacheNamesSet = new Set(Object.values(CURRENT_CACHES));
event.waitUntil(
caches.keys().then((cacheNames) =>
Promise.all(
cacheNames.map((cacheName) => {
if (!expectedCacheNamesSet.has(cacheName)) {
console.log("Deleting out of date cache:", cacheName);
return caches.delete(cacheName);
}
}),
),
),
);
});
self.addEventListener("fetch", (event) => {
console.log("Handling fetch event for", event.request.url);
event.respondWith(
caches.open(CURRENT_CACHES.font).then((cache) => {
return cache
.match(event.request)
.then((response) => {
if (response) {
console.log(" Found response in cache:", response);
return response;
}
console.log(
" No response for %s found in cache. About to fetch " +
"from network…",
event.request.url,
);
return fetch(event.request.clone()).then((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)
) {
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 response;
});
})
.catch((error) => {
console.error(" Error in fetch handler:", error);
throw error;
});
}),
);
});
Cookies and Cache objects
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 Set-Cookie
headers, and therefore won't cause any cookies to be stored.
Specifications
Browser compatibility
|
Desktop |
Mobile |
|
Chrome |
Edge |
Firefox |
Internet Explorer |
Opera |
Safari |
WebView Android |
Chrome Android |
Firefox for Android |
Opera Android |
Safari on IOS |
Samsung Internet |
Cache |
40Before version 43, only service workers are supported. From version 43, all worker types and the main thread are supported.
|
16 |
41 |
No |
27Before version 30, only service workers are supported. From version 30, all worker types and the main thread are supported.
|
11.1 |
40Before version 43, only service workers are supported. From version 43, all worker types and the main thread are supported.
|
40Before version 43, only service workers are supported. From version 43, all worker types and the main thread are supported.
|
41 |
27Before version 30, only service workers are supported. From version 30, all worker types and the main thread are supported.
|
11.3 |
4.0 |
add |
44Requires HTTPS from version 46.
|
16 |
41 |
No |
31Requires HTTPS from version 33.
|
11.1 |
44Requires HTTPS from version 46.
|
44Requires HTTPS from version 46.
|
41 |
32Requires HTTPS from version 33.
|
11.3 |
4.0Requires HTTPS from Samsung Internet 5.0.
|
addAll |
46Requires HTTPS.
|
16 |
41 |
No |
33Requires HTTPS.
|
11.1 |
46Requires HTTPS.
|
46Requires HTTPS.
|
41 |
33Requires HTTPS.
|
11.3 |
5.0Requires HTTPS.
|
delete |
43 |
16 |
41 |
No |
30 |
11.1 |
43 |
43 |
41 |
30 |
11.3 |
4.0 |
keys |
43 |
16 |
41 |
No |
30 |
11.1 |
43 |
43 |
41 |
30 |
11.3 |
4.0 |
match |
43 |
16 |
41 |
No |
30 |
11.1 |
43 |
43 |
41 |
30 |
11.3 |
4.0 |
matchAll |
47 |
16 |
41 |
No |
34Requires HTTPS.
|
11.1 |
47 |
47 |
41 |
34 |
11.3 |
5.0 |
put |
43Requires HTTPS from version 46.
|
16 |
41 |
No |
30Requires HTTPS from version 33.
|
11.1 |
43Requires HTTPS from version 46.
|
43Requires HTTPS from version 46.
|
41 |
30Requires HTTPS from version 33.
|
11.3 |
4.0Requires HTTPS from Samsung Internet 5.0.
|
worker_support |
40Before version 43, only service workers are supported. From version 43, all worker types and the main thread are supported.
|
16 |
44 |
No |
27Before version 30, only service workers are supported. From version 30, all worker types and the main thread are supported.
|
11.1 |
40Before version 43, only service workers are supported. From version 43, all worker types and the main thread are supported.
|
40Before version 43, only service workers are supported. From version 43, all worker types and the main thread are supported.
|
44 |
27Before version 30, only service workers are supported. From version 30, all worker types and the main thread are supported.
|
11.3 |
4.0 |
See also