[{"_1":2,"_30":-5,"_31":-5},"loaderData",{"_3":4},"routes/_main.posts.tags.$tag",{"_5":6,"_29":18},"posts",[7],{"_8":9,"_10":11,"_12":13,"_14":15,"_16":17,"_23":24,"_25":26,"_27":28},"slug","building-a-unified-caching-layer-for-cloudflare-workers","title","Building a Unified Caching Layer for Cloudflare Workers","description","How I built a flexible caching abstraction that works across Cloudflare's multiple storage options","date","2025-10-26","tags",[18,19,20,21,22],"caching","cloudflare-workers","performance","serverless","typescript","content","

Caching in Cloudflare Workers can be surprisingly complex. With multiple storage options available—Cache API, KV storage, and built-in fetch caching—each with different characteristics, pricing models, and limitations, I found myself writing repetitive caching logic across different projects.

The Problem: Caching Fragmentation

While working on my personal blog and other Cloudflare Workers projects, I encountered several caching challenges:

Multiple storage options: Cache API, KV, and fetch caching all serve different use cases
Inconsistent APIs: Each storage option has different interfaces and behaviors
Pricing considerations: KV has write limits and storage costs, Cache API is free but regional
Enterprise features: Some advanced caching features require expensive Enterprise plans

I needed a unified interface that could:

Switch between caching strategies easily
Handle the different APIs consistently
Provide clear logging for debugging
Work within the constraints of each storage option

The Solution: cf-cacher

I built cf-cacher, a flexible caching abstraction that simplifies switching between Cloudflare's caching options. Here's the core interface:

export type CfCacherProps = {\n    cacheKey: string\n    cacheName?: string\n    getRequest?: () => Request | Promise<Request>\n    getResponse?: () => Promise<Response>\n    cacheMode: 'fetch-cache' | 'cache-api' | 'kv' | 'none'\n    cacheTtl?: number\n    executionCtx?: {\n        waitUntil(promise: Promise<any>): void\n    }\n    kv?: KVNamespace\n}\n

The function supports four caching modes:

1. Cache API Mode (`cache-api`)

Uses the standard Cache API with caches.open():

const cache = await caches.open(cacheName ?? 'custom:cache')\nlet response = await cache.match(cacheKey)\n\n// getFreshResponse is a placeholder for your logic to generate or fetch the uncached response\nconst getFreshResponse = async () =>\n    (await getResponse?.()) || (await fetch(await getRequest?.()))\n\nif (!response) {\n    response = await getFreshResponse()\n    response.headers.set('CDN-Cache-Control', `public, s-maxage=${cacheTtl}`)\n    await cache.put(cacheKey, response.clone())\n}\n

Pros:

Free and unlimited
Fast response times
Works with any Workers plan

Cons:

Only caches in the specific data center where the Worker runs
No global replication

2. KV Storage Mode (`kv`)

Stores responses in Cloudflare KV with metadata:

const kvResponse = await kv.getWithMetadata<KvMetadata>(cacheKey, 'stream')\n\nif (kvResponse.value == null) {\n    // getFreshResponse is a placeholder for your logic to generate or fetch the uncached response\n    const getFreshResponse = async () =>\n        (await getResponse?.()) || (await fetch(await getRequest?.()))\n    response = await getFreshResponse()\n    await kv.put(cacheKey, response.clone().body, {\n        expirationTtl: cacheTtl,\n        metadata: { headers: Object.fromEntries(response.headers.entries()) },\n    })\n}\n

Pros:

Global replication across all edge locations
Works with workers.dev projects
Consistent responses worldwide

Cons:

1GB free storage limit, then $0.50/GB
Write limits on free tier (100,000 writes/day)
Higher latency than Cache API

3. Fetch Cache Mode (`fetch-cache`)

Uses Cloudflare's built-in caching with custom cache keys:

const response = await fetch(request, {\n    cf: { cacheKey, cacheEverything: true, cacheTtl },\n})\n

Pros:

Leverages Cloudflare's global CDN
Automatic request coalescing
Tiered caching support

Cons:

Custom cache keys require Enterprise plan
Only works within your own zone or non-Cloudflare sites

Real-World Usage: OG Image Generation

I use cf-cacher for my blog's OG image generation route. The images are expensive to generate (they involve font loading, SVG rendering, and PNG conversion), so caching is crucial:

export async function loader(args: Route.LoaderArgs) {\n  return cfCacher({\n    cacheKey: args.request.url,\n    getResponse: async () => {\n      const title = new URL(args.request.url).searchParams.get('title') || 'Hello'\n\n      return new ImageResponse(\n        <div style={{ /* styles */ }}>\n          <div>{title}</div>\n        </div>,\n        { width: 1200, height: 630 }\n      )\n    },\n    executionCtx: args.context.cloudflare.ctx,\n    cacheMode: 'cache-api', // Cache in the edge data center\n    cacheTtl: seconds('1 hour')\n  })\n}\n

The caching headers help with debugging:

response.headers.set('x-cache-method', cacheMode)\nresponse.headers.set('x-cache-key', cacheKey)\nresponse.headers.set('x-cache-status', 'HIT' | 'MISS')\n

Choosing the Right Cache Mode

Here's my decision matrix for selecting cache modes:

Use Cache API when:

Content is region-specific
You need unlimited free storage
Fast response times are critical
You're on a budget

Use KV when:

Global consistency is required
You have low traffic (to avoid write limits)
Content changes infrequently
You need workers.dev compatibility

Use Fetch Cache when:

You have an Enterprise plan
You're caching external API responses
You want automatic request coalescing
Content is cacheable by HTTP semantics

Performance Considerations

I've learned some important performance lessons:

Cache API Optimization

Use custom cache names to avoid conflicts with fetch() cache
Set appropriate CDN-Cache-Control headers
Use waitUntil() for non-blocking cache writes

KV Optimization

Stream responses to avoid loading large content into memory
Store headers as metadata to preserve response metadata
Monitor write usage to avoid hitting limits

Debugging

The logging built into cf-cacher has been invaluable:

console.log(\n    `Executing cfCacher for ${cacheKey} with ${cacheMode} ttl ${cacheTtl} seconds`\n)\nconsole.log(`Cache hit for: ${cacheKey}.`)\nconsole.log(\n    `Response for request url: ${cacheKey} not present in cache. Fetching and caching request.`\n)\n

Future Enhancements

I'm considering several improvements:

R2 Integration: For large files that exceed KV's 1GB limit
Cache Warming: Background jobs to pre-populate cache
Smart Mode Selection: Automatically choose based on content size and access patterns
Metrics Collection: Track hit rates and performance across modes

The Code

The complete implementation is available in my blog's repository under app/server/cf-cacher/. It's designed to be framework-agnostic and can be dropped into any Cloudflare Workers project.

Conclusion

Building cf-cacher has significantly simplified my caching strategy across multiple projects. By abstracting away the differences between Cloudflare's storage options, I can:

Easily switch between caching strategies as requirements change
Avoid vendor lock-in to specific storage mechanisms
Write cleaner, more maintainable caching code
Make informed decisions about which storage to use based on actual requirements

The key insight was that caching isn't one-size-fits-all—different use cases benefit from different storage mechanisms. Having a unified interface lets me optimize for each specific scenario without rewriting caching logic.

If you're working with Cloudflare Workers and struggling with caching complexity, I hope this approach gives you some ideas for simplifying your own caching layer.

","excerpt","Caching in Cloudflare Workers can be surprisingly complex. With multiple storage options available—Cache API, KV storage, and built-in fetch caching—each with different characteristics, pricing...","readingTime",5,"tag","actionData","errors"]

The Problem: Caching Fragmentation

The Solution: cf-cacher

1. Cache API Mode (cache-api)

2. KV Storage Mode (kv)

3. Fetch Cache Mode (fetch-cache)

Real-World Usage: OG Image Generation

Choosing the Right Cache Mode

Use Cache API when:

Use KV when:

Use Fetch Cache when:

Performance Considerations

Cache API Optimization

KV Optimization

Debugging

Future Enhancements

The Code

Conclusion

1. Cache API Mode (`cache-api`)

2. KV Storage Mode (`kv`)

3. Fetch Cache Mode (`fetch-cache`)

Posts tagged "caching"

Building a Unified Caching Layer for Cloudflare Workers