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?
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:
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:
cfobject of a request).
Cache-Controlon the response passed to
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.
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.
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.
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:
slow.com/resourceif and only if it’s already a HIT on cache using
caches.default.put(..)and explicitly delete
caches.default.delete(..). For example, say your origin is returning
max-age:0and 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=1000on the response passed into