GitHub iconEdit on GitHub

Using the Cache

Workers provide a way to customize cache behavior using Cloudflare's CDN for a zone’s private cache space. To learn about the benefits of caching see our Learning Center's article on What is Caching?

Interacting with the Cloudflare Cache

Cache is globally distributed and namespaced by zone of the incoming request, meaning a Worker script can not access or set a cache resource on an orange clouded zone’s namespace that differs from the zone of the incoming request.

Conceptually, there are two ways to interact with Cloudflare's Cache using a Worker:

  • Call to fetch() in a Workers script. Requests proxied through Cloudflare are cached even without Workers according to a zone's default or configured behavior (e.g. static assets like files ending in .jpg are cached by default). Workers can further customize this behavior by:
    • Setting Cloudflare cache rules (i.e. operating on the cf object of a request).
  • Store responses using the Cache API from a Workers script. This allows caching responses that did not come from an origin and also provides finer control by:
    • Customizing cache behavior of any asset by setting headers such as Cache-Control on the response passed to cache.put()
    • Caching responses generated by the Worker itself through cache.put()

The browser cache is controlled through the Cache-Control header sent in the response to the eyeball (the response passed or promised to event.respondWith()). Workers can customize browser cache behavior by setting this header on the response.

We won't discuss in this article, but other means to control Cloudflare's cache include: Page rules and Cloudflare cache settings. I highly recommend the article How to Control Cloudflare's cache if you wish to avoid writing JavaScript with still some granularity of control.

What should I use: the Cache API or fetch for caching objects on Cloudflare? For requests where Workers are behaving as middleware (i.e. they are sending a subrequest via fetch) it is recommended to use fetch. This is because pre existing settings are in place that optimize caching while preventing unintended dynamic caching. For projects where there is no backend (i.e. the entire project is on Workers as in Workers Sites) the Cache API is the only option to customize caching.

fetch

In the context of Workers a fetch provided by the runtime communicates with the Cloudflare cache. First, fetch checks to see if the URL matches a different zone. If it does, it reads through that zone's cache (or Worker!). Otherwise, it reads through its own zone's cache, even if the URL is for a non-Cloudflare site. Cache settings on fetch automatically apply caching rules based on your Cloudflare settings. fetch does not allow you to modify or inspect objects before they reach the cache, but does allow you to modify how it will cache.

When a response fills the cache, the response header contains CF-Cache-Status: HIT. You can tell an object is attempting to cache if one sees the CF-Cache-Status at all.

This template shows ways to customize Cloudflare cache behavior on a given request using fetch.

Cache API

The Cache API uses a cache key namespace on Cloudflare's CDN that is private to the Worker's zone. Cache objects are stored in the local datacenter handling the request and are not replicated to other datacenters.

When to use the Cache API:

  • When you need to read from cache without calling fetch. (i.e. send me the response from slow.com/resource if and only if it’s already a HIT on cache using caches.default.match(..).
  • Explicitly store a response in the cache using caches.default.put(..) and explicitly delete caches.default.delete(..). For example, say your origin is returning max-age:0 and you can't figure out how to change that header at your origin. You can explicitly tell Cloudflare to cache this response by setting cache-control: max-age=1000 on the response passed into cache.put().

This template shows ways to use the cache API. For limits of the cache API see limits.