Cache using fetch

Determine how to cache a resource by setting TTLs, custom cache keys, and cache headers in a fetch request.

Last updated Jul 6, 2026 If you want to get started quickly, click on the button below.

This creates a repository in your GitHub account and deploys the application to Cloudflare Workers.

export default {
    async fetch(request) {
        const url = new URL(request.url);
        // Only use the path for the cache key, removing query strings
        // and always store using HTTPS, for example, https://www.example.com/file-uri-here
        const someCustomKey = `https://${url.hostname}${url.pathname}`;
        let response = await fetch(request, {
            cf: {
                // Always cache this fetch regardless of content type
                // for a max of 5 seconds before revalidating the resource
                cacheTtl: 5,
                cacheEverything: true,
                //Enterprise only feature, see Cache API for other plans
                cacheKey: someCustomKey,
            },
        });
        // Reconstruct the Response object to make its headers mutable.
        response = new Response(response.body, response);
        // Set cache control headers to cache on browser for 25 minutes
        response.headers.set("Cache-Control", "max-age=1500");
        return response;
    },
};

export default {
    async fetch(request): Promise<Response> {
        const url = new URL(request.url);
        // Only use the path for the cache key, removing query strings
        // and always store using HTTPS, for example, https://www.example.com/file-uri-here
        const someCustomKey = `https://${url.hostname}${url.pathname}`;
        let response = await fetch(request, {
            cf: {
                // Always cache this fetch regardless of content type
                // for a max of 5 seconds before revalidating the resource
                cacheTtl: 5,
                cacheEverything: true,
                //Enterprise only feature, see Cache API for other plans
                cacheKey: someCustomKey,
            },
        });
        // Reconstruct the Response object to make its headers mutable.
        response = new Response(response.body, response);
        // Set cache control headers to cache on browser for 25 minutes
        response.headers.set("Cache-Control", "max-age=1500");
        return response;
    },
} satisfies ExportedHandler;

import { Hono } from 'hono';

type Bindings = {};

const app = new Hono<{ Bindings: Bindings }>();

app.all('*', async (c) => {
  const url = new URL(c.req.url);

// Only use the path for the cache key, removing query strings
  // and always store using HTTPS, for example, https://www.example.com/file-uri-here
  const someCustomKey = `https://${url.hostname}${url.pathname}`;

// Fetch the request with custom cache settings
  let response = await fetch(c.req.raw, {
    cf: {
      // Always cache this fetch regardless of content type
      // for a max of 5 seconds before revalidating the resource
      cacheTtl: 5,
      cacheEverything: true,
      // Enterprise only feature, see Cache API for other plans
      cacheKey: someCustomKey,
    },
  });

// Reconstruct the Response object to make its headers mutable
  response = new Response(response.body, response);

// Set cache control headers to cache on browser for 25 minutes
  response.headers.set("Cache-Control", "max-age=1500");

return response;
});

export default app;

from workers import WorkerEntrypoint, Response, fetch
from urllib.parse import urlparse

class Default(WorkerEntrypoint):
    async def fetch(self, request):
        url = urlparse(request.url)

# Only use the path for the cache key, removing query strings
        # and always store using HTTPS, for example, https://www.example.com/file-uri-here
        some_custom_key = f"https://{url.hostname}{url.path}"

response = await fetch(
            request,
            cf={
                # Always cache this fetch regardless of content type
                # for a max of 5 seconds before revalidating the resource
                "cacheTtl": 5,
                "cacheEverything": True,
                # Enterprise only feature, see Cache API for other plans
                "cacheKey": some_custom_key,
            },
        )

# Reconstruct the Response object to make its headers mutable
        new_response = Response(response.body, headers=dict(response.headers))

# Set cache control headers to cache on browser for 25 minutes
        new_response.headers["Cache-Control"] = "max-age=1500"

return new_response

use worker::*;

#[event(fetch)]
async fn fetch(req: Request, _env: Env, _ctx: Context) -> Result<Response> {
    let url = req.url()?;

// Only use the path for the cache key, removing query strings
    // and always store using HTTPS, for example, https://www.example.com/file-uri-here
    let custom_key = format!(
        "https://{host}{path}",
        host = url.host_str().unwrap(),
        path = url.path()
    );

let request = Request::new_with_init(
        url.as_str(),
        &RequestInit {
            headers: req.headers().clone(),
            method: req.method(),
            cf: CfProperties {
                // Always cache this fetch regardless of content type
                // for a max of 5 seconds before revalidating the resource
                cache_ttl: Some(5),
                cache_everything: Some(true),
                // Enterprise only feature, see Cache API for other plans
                cache_key: Some(custom_key),
                ..CfProperties::default()
            },
            ..RequestInit::default()
        },
    )?;

let mut response = Fetch::Request(request).send().await?;

// Set cache control headers to cache on browser for 25 minutes
    let _ = response.headers_mut().set("Cache-Control", "max-age=1500");
    Ok(response)
}

Caching HTML resources

// Force Cloudflare to cache an asset
fetch(event.request, { cf: { cacheEverything: true } });

Setting the cache level to Cache Everything will override the default cacheability of the asset. For time-to-live (TTL), Cloudflare will still rely on headers set by the origin.

Custom cache keys

Note

This feature is available only to Enterprise customers.

A request's cache key is what determines if two requests are the same for caching purposes. If a request has the same cache key as some previous request, then Cloudflare can serve the same cached response for both. For more about cache keys, refer to the Create custom cache keys documentation.

// Set cache key for this request to "some-string".
fetch(event.request, { cf: { cacheKey: "some-string" } });

Normally, Cloudflare computes the cache key for a request based on the request's URL. Sometimes, though, you may like different URLs to be treated as if they were the same for caching purposes. For example, if your website content is hosted from both Amazon S3 and Google Cloud Storage - you have the same content in both places, and you can use a Worker to randomly balance between the two. However, you do not want to end up caching two copies of your content. You could utilize custom cache keys to cache based on the original request URL rather than the subrequest URL:

export default {
    async fetch(request) {
        let url = new URL(request.url);

if (Math.random() < 0.5) {
            url.hostname = "example.s3.amazonaws.com";
        } else {
            url.hostname = "example.storage.googleapis.com";
        }

let newRequest = new Request(url, request);
        return fetch(newRequest, {
            cf: { cacheKey: request.url },
        });
    },
};

export default {
    async fetch(request): Promise<Response> {
        let url = new URL(request.url);

if (Math.random() < 0.5) {
            url.hostname = "example.s3.amazonaws.com";
        } else {
            url.hostname = "example.storage.googleapis.com";
        }

let newRequest = new Request(url, request);
        return fetch(newRequest, {
            cf: { cacheKey: request.url },
        });
    },
} satisfies ExportedHandler;

import { Hono } from 'hono';

type Bindings = {};

const app = new Hono<{ Bindings: Bindings }>();

app.all('*', async (c) => {
  const originalUrl = c.req.url;
  const url = new URL(originalUrl);

// Randomly select a storage backend
  if (Math.random() < 0.5) {
    url.hostname = "example.s3.amazonaws.com";
  } else {
    url.hostname = "example.storage.googleapis.com";
  }

// Create a new request to the selected backend
  const newRequest = new Request(url, c.req.raw);

// Fetch using the original URL as the cache key
  return fetch(newRequest, {
    cf: { cacheKey: originalUrl },
  });
});

export default app;

Workers operating on behalf of different zones cannot affect each other's cache. You can only override cache keys when making requests within your own zone (in the above example event.request.url was the key stored), or requests to hosts that are not on Cloudflare. When making a request to another Cloudflare zone (for example, belonging to a different Cloudflare customer), that zone fully controls how its own content is cached within Cloudflare; you cannot override it.

Cache expected Vary responses

Use cf.vary when an origin returns a Vary header and you want a Worker subrequest to cache expected variants. This setting applies only to the fetch() request where you set it.

For Vary behavior details, refer to Vary. For the full request init object, refer to cf.vary.

src/index.jsjs

export default {
    async fetch(request) {
        return fetch(request, {
            cf: {
                vary: {
                    default: { action: "bypass" },
                    headers: {
                        accept: {
                            action: "normalize",
                            media_types: ["text/html", "application/json"],
                        },
                        "accept-language": {
                            action: "normalize",
                            languages: ["en", "fr", "de"],
                        },
                    },
                },
            },
        });
    },
};

src/index.tsts

export default {
    async fetch(request): Promise<Response> {
        return fetch(request, {
            cf: {
                vary: {
                    default: { action: "bypass" },
                    headers: {
                        accept: {
                            action: "normalize",
                            media_types: ["text/html", "application/json"],
                        },
                        "accept-language": {
                            action: "normalize",
                            languages: ["en", "fr", "de"],
                        },
                    },
                },
            },
        });
    },
} satisfies ExportedHandler;