The cache read-only property of the Request interface contains the cache mode of the request. It controls how the request will interact with the browser's HTTP cache.

Syntax

var currentCacheMode = request.cache;

Value

A RequestCache value. The available values are:

  • default — The browser looks for a matching request in its HTTP cache.
    • If there is a match and it is fresh, it will be returned from the cache.
    • If there is a match but it is stale, the browser will make a conditional request to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated.
    • If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource.
  • no-store — The browser fetches the resource from the remote server without first looking in the cache, and will not update the cache with the downloaded resource.
  • reload — The browser fetches the resource from the remote server without first looking in the cache, but then will update the cache with the downloaded resource.
  • no-cache — The browser looks for a matching request in its HTTP cache.
    • If there is a match, fresh or stale, the browser will make a conditional request to the remote server. If the server indicates that the resource has not changed, it will be returned from the cache. Otherwise the resource will be downloaded from the server and the cache will be updated.
    • If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource.
  • force-cache — The browser looks for a matching request in its HTTP cache.
    • If there is a match, fresh or stale, it will be returned from the cache.
    • If there is no match, the browser will make a normal request, and will update the cache with the downloaded resource.
  • only-if-cached — The browser looks for a matching request in its HTTP cache.
    • If there is a match, fresh or stale, if will be returned from the cache.
    • If there is no match, the browser will respond with a 504 Gateway timeout status.
    The "only-if-cached" mode can only be used if the request's mode is "same-origin". Cached redirects will be followed if the request's redirect property is "follow" and the redirects do not violate the "same-origin" mode.

Example

// Download a resource with cache busting, to bypass the cache
// completely.
fetch("some.json", {cache: "no-store"})
  .then(function(response) { /* consume the response */ });

// Download a resource with cache busting, but update the HTTP
// cache with the downloaded resource.
fetch("some.json", {cache: "reload"})
  .then(function(response) { /* consume the response */ });

// Download a resource with cache busting when dealing with a
// properly configured server that will send the correct ETag
// and Date headers and properly handle If-Modified-Since and
// If-None-Match request headers, therefore we can rely on the
// validation to guarantee a fresh response.
fetch("some.json", {cache: "no-cache"})
  .then(function(response) { /* consume the response */ });

// Download a resource with economics in mind!  Prefer a cached
// albeit stale response to conserve as much bandwidth as possible.
fetch("some.json", {cache: "force-cache"})
  .then(function(response) { /* consume the response */ });

// Naive stale-while-revalidate client-level implementation.
// Prefer a cached albeit stale response; but update if it's too old.
// AbortController and signal to allow better memory cleaning.
// In reality; this would be a function that takes a path and a
// reference to the controller since it would need to change the value 
let controller = new AbortController();
fetch("some.json", {cache: "only-if-cached", mode: "same-origin", signal: controller.signal})
  .catch(e => e instanceof TypeError && e.message === "Failed to fetch" ?
    ({status: 504}) : // Workaround for chrome; which simply fails with a typeerror
    Promise.reject(e))
  .then(res => {
    if (res.status === 504) {
      controller.abort()
      controller = new AbortController();
      return fetch("some.json", {cache: "force-cache", mode: "same-origin", signal: controller.signal})
    }
    const date = res.headers.get("date"), dt = date ? new Date(date).getTime() : 0
    if (dt < (Date.now() - 86400000)) {
      // if older than 24 hours
      controller.abort()
      controller = new AbortController();
      return fetch("some.json", {cache: "reload", mode: "same-origin", signal: controller.signal})
    }

    // Other possible conditions
    if (dt < (Date.now() - 300000)) // If it's older than 5 minutes
      fetch("some.json", {cache: "no-cache", mode: "same-origin"}) // no cancellation or return value.
    return res
  })
  .then(function(response) { /* consume the (possibly stale) response */ })
  .catch(error => { /* Can be an AbortError/DOMError or a TypeError */ });

Specifications

Specification Status Comment
Fetch
The definition of 'cache' in that specification.
Living Standard Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidiOS SafariSamsung Internet
Basic support
Experimental
Chrome No support No
Notes
No support No
Notes
Notes Nightly build
Edge Full support YesFirefox Full support 48IE No support NoOpera No support NoSafari Full support 11WebView Android No support NoChrome Android No support NoEdge Mobile Full support YesFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No
only-if-cached
Experimental
Chrome No support NoEdge ? Firefox Full support 50IE No support NoOpera No support NoSafari No support NoWebView Android Full support YesChrome Android No support NoEdge Mobile ? Firefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

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

See also

Document Tags and Contributors

Last updated by: ZaneHannanAU,