We architected an edge caching layer to eliminate cold starts

Summary

Mintlify powers documentation for tens of thousands of developer sites, serving 72 million monthly page views. Every pageload matters when millions of developers and AI agents depend on your platform for technical information. We had a problem. Nearly one in four visitors experienced slow cold starts when accessing documentation pages. Our existing Next.js ISR caching solution could not keep up with deployment velocity that kept climbing as our engineering team grew. We ship code updates multiple times per day and each deployment invalidated the entire cache across all customer sites. This post walks through how we architected a custom edge caching layer to decouple deployments from cache invalidation, bringing our cache hit rate from 76% to effectively 100%. We achieved our goal of fully eliminating cold starts and used a veritable smorgasbord of Cloudflare products to get there. ComponentPurposeWorkersdocs-proxy handles requests; revalidation-worker consumes the queueKVStore deployment configs, version IDs, connected domainsDurable ObjectsGlobal singleton coordination for revalidation locksQueuesAsync message processing for cache warmingCDN CacheEdge caching with custom cache keys via fetch with cf optionsZones/DNSRoute traffic to workers We could have built a similar system on any hyperscaler, but leaning on Cloudflare's CDN expertise, especially for configuring tiered cache, was a huge help. It is important that you understand the difference between two key terms which I use throughout the following solution explanation. Revalidations are a reactive process triggered when we detect a version mismatch at request time (e.g., after we deploy new code) Prewarming is a proactive process triggered when customers update their documentation content, before any user requests it Both ultimately warm the cache by fetching pages, but they differ in when and why they're triggered. More on this in sections 2 through 4 below. We placed a Cloudflare Worker in front of all traff...