How the Cache works
Workers was designed and built on top of Cloudflare’s edge network to allow developers to interact directly with the Cloudflare cache. The cache can provide ephemeral, data center-local storage, as a convenient way to frequently access static or dynamic content.
By allowing developers to write to the cache, Workers provide a way to customize cache behavior on Cloudflare’s CDN. To learn about the benefits of caching, refer to the Learning Center’s article on .
Since Cloudflare Workers can run before, and after the cache, a Worker can also be utilized to modify assets once they are returned from the cache, to sign or personalize responses, while reducing load on an origin, or latency to the end user by serving assets from a nearby location.
Interacting with the Cloudflare Cache
Conceptually, there are two ways to interact with Cloudflare’s Cache using a Worker:
Call to in a Workers script. Requests proxied through Cloudflare are cached even without Workers according to a zone’s default or configured behavior (for example, static assets like files ending in
.jpgare cached by default). Workers can further customize this behavior by:
Customizing cache behavior of any asset by setting headers such as
Cache-Controlon the response passed to
Caching responses generated by the Worker itself through
Single file purge assets cached by a worker
When using single-file purge to purge assets cached by a Worker, make sure not to purge the end user URL. Instead, purge the URL that is in the
fetch request. For example, you have a Worker that runs on
https://example.com/hello and this Worker makes a
fetch request to
As far as cache is concerned, the asset in the
fetch request (
https://notexample.com/hello) is the asset that is cached (
https://notexample.com/hello). To purge it, you need to purge
Purging the end user URL,
https://example.com/hello, will not work because that is not the URL that cache sees. You need to confirm in your Worker which URL you are actually fetching, so you can purge the correct asset.
In the previous example,
https://notexample.com/hello is not proxied through Cloudflare. If
https://notexample.com/hello was proxied () through Cloudflare, then you must own
notexample.com and purge
https://notexample.com/hello from the
To better understand the example, take a look at the following diagram:
Purging assets stored with the Cache API
cache.deletewithin a Worker to invalidate the cache for the asset with a matching request variable.
- Assets purged in this way are only purged locally to the data center the Worker runtime was executed.
To purge an asset globally, you must use the standard cache purge options. Based on cache API implementation, not all cache purge endpoints function for purging assets stored by the Cache API.
Available to Enterprise Customers, can be added to requests dynamically in a Worker by calling
Cache-Tagvalues dynamically to that request. Once set, those tags can be used to selectively purge assets from cache without invalidating all cached assets on a zone.
Currently, it is not possible to purge a URL stored through Cache API that uses a custom cache key set by a Worker. Instead, use a . Alternatively, purge your assets using purge everything, purge by tag, purge by host or purge by prefix.
Edge versus browser caching
The browser cache is controlled through the
Cache-Control header sent in the response to the client (the response passed or promised to
event.respondWith()). Workers can customize browser cache behavior by setting this header on the response.
In the context of Workers, a 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.
There are two types of cache namespaces available to the Cloudflare Cache:
caches.default– You can access the default cache (the same cache shared with
fetchrequests) by accessing
caches.default. This is useful when needing to override content that is already cached, after receiving the response.
caches.open()– You can access a namespaced cache (separate from the cache shared with
let cache = await caches.open(CACHE_NAME). Note that is an async function, unlike
When to use the Cache API:
When you want to programmatically save and/or delete responses from a cache. For example, say an origin is responding with a
Cache-Control: max-age:0header and cannot be changed. Instead, you can clone the
Response, adjust the header to the
max-age=3600value, and then use the Cache API to save the modified
Responsefor an hour.
When you want to programmatically access a Response from a cache without relying on a
fetchrequest. For example, you can check to see if you have already cached a
https://example.com/slow-responseendpoint. If so, you can avoid the slow request.