---
title: Cache
slug: Web/API/Cache
tags:
  - API
  - Cache
  - Draft
  - Experimental
  - Interface
  - NeedsTranslation
  - Offline
  - Reference
  - Service Workers
  - Storage
  - TopicStub
translation_of: Web/API/Cache
---
<p>{{APIRef("Service Workers API")}}{{SeeCompatTable}}</p>

<p>The <strong><code>Cache</code></strong> interface provides a storage mechanism for <code><a href="http://fetch.spec.whatwg.org/#request">Request</a></code> / <code><a href="http://fetch.spec.whatwg.org/#response">Response</a></code> object pairs that are cached, for example as part of the {{domxref("ServiceWorker")}} life cycle. Note that the <code>Cache</code> 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.</p>

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

<p>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. 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 <a href="/en-US/docs/Web/API/ServiceWorker_API/Using_Service_Workers#Deleting_old_caches">Deleting old caches</a> for more information.</p>

<div class="note">
<p><strong>Note</strong>: {{domxref("Cache.put")}}, {{domxref("Cache.add")}}, and {{domxref("Cache.addAll")}} only allow <code>GET</code> requests to be stored in the cache.</p>
</div>

<div class="note">
<p><strong>Note</strong>: Initial Cache implementations (in both Blink and Gecko) resolve {{domxref("Cache.add")}}, {{domxref("Cache.addAll")}}, and {{domxref("Cache.put")}} promises when the response body is fully written to storage.  More recent spec versions have newer language stating 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.</p>
</div>

<div class="note">
<p><strong>Note:</strong> As of Chrome 46, the Cache API will only store requests from secure origins, meaning those served over HTTPS.</p>
</div>

<div class="note">
<p><strong>Note</strong>: The key matching algorithm depends on the <a href="https://www.fastly.com/blog/best-practices-for-using-the-vary-header">VARY header</a> in the value. So matching a new key requires looking at both key and value for entries in the Cache.</p>
</div>

<div class="note">
<p><strong>Note:</strong> The caching API doesn't honor HTTP caching headers.</p>
</div>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{domxref("Cache.match", "Cache.match(request, options)")}}</dt>
 <dd>Returns a {{jsxref("Promise")}} that resolves to the response associated with the first matching request in the {{domxref("Cache")}} object.</dd>
 <dt>{{domxref("Cache.matchAll", "Cache.matchAll(request, options)")}}</dt>
 <dd>Returns a {{jsxref("Promise")}} that resolves to an array of all matching requests in the {{domxref("Cache")}} object.</dd>
 <dt>{{domxref("Cache.add", "Cache.add(request)")}}</dt>
 <dd>Takes a URL, retrieves it and adds the resulting response object to the given cache. This is fuctionally equivalent to calling fetch(), then using Cache.put() to add the results to the cache.</dd>
 <dt>{{domxref("Cache.addAll", "Cache.addAll(requests)")}}</dt>
 <dd>Takes an array of URLs, retrieves them, and adds the resulting response objects to the given cache.</dd>
 <dt>{{domxref("Cache.put", "Cache.put(request, response)")}}</dt>
 <dd>Takes both a request and its response and adds it to the given cache.</dd>
 <dt>{{domxref("Cache.delete", "Cache.delete(request, options)")}}</dt>
 <dd>Finds the {{domxref("Cache")}} entry whose key is the request, and if found, deletes the {{domxref("Cache")}} entry and returns a {{jsxref("Promise")}} that resolves to <code>true</code>. If no {{domxref("Cache")}} entry is found, it returns <code>false</code>.</dd>
 <dt>{{domxref("Cache.keys", "Cache.keys(request, options)")}}</dt>
 <dd>Returns a {{jsxref("Promise")}} that resolves to an array of {{domxref("Cache")}} keys.</dd>
</dl>

<h2 id="Examples">Examples</h2>

<p>This code snippet is from the <a href="https://github.com/GoogleChrome/samples/blob/gh-pages/service-worker/selective-caching/service-worker.js">service worker selective caching sample</a>. (see <a href="https://googlechrome.github.io/samples/service-worker/selective-caching/">selective caching live</a>) The code uses {{domxref("CacheStorage.open", "CacheStorage.open(cacheName)")}} to open any {{domxref("Cache")}} objects with a Content-Type header that starts with <code>font/</code>.</p>

<p>The code then uses {{domxref("Cache.match", "Cache.match(request, options)")}} 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 {{domxref("Cache.put","Cache.put(request, response)")}} to cache the fetched resource.</p>

<p>The code handles exceptions thrown from the {{domxref("Globalfetch.fetch","fetch()")}} operation. 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.</p>

<p>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 <code>CURRENT_CACHES</code>.</p>

<div class="note"><strong>Note:</strong> 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 <a href="https://github.com/GoogleChrome/samples/blob/gh-pages/service-worker/selective-caching/service-worker.js">service-worker.js</a> script is performing.</div>

<pre class="brush: js">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.keys(CURRENT_CACHES).map(function(key) {
    return CURRENT_CACHES[key];
  });

  // 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.indexOf(cacheName) == -1) {
            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;
        }
      }).catch(function(error) {

        // Handles exceptions that arise from match() or fetch().
        console.error('  Error in fetch handler:', error);

        throw error;
      });
    })
  );
});</pre>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('Service Workers', '#cache', 'Cache')}}</td>
   <td>{{Spec2('Service Workers')}}</td>
   <td>Initial definition.</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari (WebKit)</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatChrome(40.0)}}</td>
   <td>{{CompatGeckoDesktop(39)}}<sup>[1]</sup></td>
   <td>{{CompatNo}}</td>
   <td>24</td>
   <td>{{CompatNo}}</td>
  </tr>
  <tr>
   <td>add()</td>
   <td>{{CompatChrome(44.0)}}</td>
   <td>{{CompatVersionUnknown}}<sup>[1]</sup></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>addAll()</td>
   <td>{{CompatChrome(46.0)}}</td>
   <td>{{CompatVersionUnknown}}<sup>[1]</sup></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>matchAll()</td>
   <td>{{CompatChrome(47.0)}}</td>
   <td>{{CompatVersionUnknown}}<sup>[1]</sup></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Require HTTPS for <code>add()</code>, <code>addAll()</code>, and <code>put()</code></td>
   <td>{{CompatChrome(46.0)}}</td>
   <td>{{CompatVersionUnknown}}<sup>[1]</sup></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatGeckoMobile(39)}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(40.0)}}</td>
  </tr>
  <tr>
   <td>add()</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(44.0)}}</td>
  </tr>
  <tr>
   <td>addAll()</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(46.0)}}</td>
  </tr>
  <tr>
   <td>matchAll()</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(46.0)}}</td>
  </tr>
  <tr>
   <td>Require HTTPS for <code>add()</code>, <code>addAll()</code>, and <code>put()</code></td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(46.0)}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Service workers (and <a href="/en-US/docs/Web/API/Push_API">Push</a>) have been disabled in the <a href="https://www.mozilla.org/en-US/firefox/organizations/">Firefox 45 Extended Support Release</a> (ESR.)</p>

<h2 id="See_also">See also</h2>

<ul>
 <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker_API/Using_Service_Workers">Using Service Workers</a></li>
 <li><a class="external external-icon" href="https://github.com/mdn/sw-test">Service workers basic code example</a></li>
 <li><a class="external external-icon" href="https://jakearchibald.github.io/isserviceworkerready/">Is ServiceWorker ready?</a></li>
 <li>{{jsxref("Promise")}}</li>
 <li><a href="https://developer.mozilla.org/en-US/docs/Web/Guide/Performance/Using_web_workers">Using web workers</a></li>
</ul>