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.
Component Purpose Workers docs-proxy handles requests; revalidation-worker consumes the queue KV Store deployment configs, version IDs, connected domains Durable Objects Global singleton coordination for revalidation locks Queues Async message processing for cache warming CDN Cache Edge caching with custom cache keys via fetch with cf options Zones/DNS Route 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)
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.
... continue reading