Push Cache Architectures for Headless CMS
If you run a large headless CMS website, a push cache stores published content at the edge ahead of time, so visitors never wait on a cache miss. Most headless websites I see still use pull caching: a CDN with a TTL, st
If you run a large headless CMS website, a push cache stores published content at the edge ahead of time, so visitors never wait on a cache miss.
Most headless websites I see still use pull caching: a CDN with a TTL, stale-while-revalidate or ISR. They all work the same way. Content sits in the CMS until a visitor requests a URL, and if the timer has expired the origin rebuilds the page. A push cache flips that around. When an editor hits Publish, the CMS pushes the updated content to edge storage, and every public request reads from there.
Problems With Pull Caching
- Cache misses land on real visitors. When a TTL expires, or a CDN location hasn't seen a URL yet, somebody waits while the request goes back to the origin, queries the CMS API and renders the page.
- Freshness costs money. A long TTL means typo fixes take hours to show up. A short TTL means your origin and CMS API rebuild pages thousands of times a day, including archive articles that haven't changed in five years.
- "Is it broken or just cached?" Editors publish, still see the old version and file a bug. QA adds cache-busting query strings and purges staging caches just to find out if a bug is real.
- Deploys purge everything. Templates and content are baked into the same cached HTML, so a small CSS fix needs a full cache purge. On a website with 100,000+ URLs the hit ratio drops to zero, and crawlers and readers re-request the whole archive from the origin even though no content changed.
- The bills add up. Serverless execution time, ISR reads and writes, bandwidth and CMS API usage all grow with short TTLs and full purges.
How a Push Cache Works
Writes are separated from reads. Visitors never talk to the CMS API or trigger an origin build.
- An editor publishes or updates content in the CMS.
- The CMS fires a webhook with the entity ID to a queue (Cloudflare Queues or AWS SQS).
- A background worker fetches the content and any related data, then builds a clean JSON payload.
- The worker writes that payload to edge storage (Cloudflare KV or R2), replacing the previous version.
- A Cloudflare Worker reads the payload at the edge and renders the response for every visitor.
Deploys Without Cache Purges
This is the biggest win for me. Instead of caching full HTML pages that have to be thrown away when the code changes, you store normalized content in KV or R2 and run the templates inside the Worker.
- When an editor publishes: only that article's payload, and anything directly related to it, is pushed to the edge. No deploy needed.
- When an engineer deploys: the Worker updates globally in seconds and the content store isn't touched. The next request renders the existing data with the new templates, with no origin hits and no CMS API calls.
If you also cache full HTML in front of the Worker, version the cache keys by deploy ID. The HTML gets rebuilt from edge storage, not from the CMS.
Editors and QA get the same benefit. Updates show up within seconds of saving, every time, and preview environments read from a separate draft namespace on the same setup.
Why Cloudflare Workers
You can build this on AWS or Fastly, but Cloudflare fits the pattern well for content-heavy websites:
- No cold starts. Workers run on V8 isolates that start in a few milliseconds, in 300+ locations.
- Storage built for it. KV is made for high-read workloads, R2 has no egress fees, and the Cache API sits in front of both.
- The CMS can go down. The edge holds a persistent copy of every published page, so a CMS outage or maintenance window doesn't take the website with it.
Pull Cache vs. Push Cache
| Pull Cache (TTL, ISR) | Push Cache | |
|---|---|---|
| What triggers an update | A visitor hits an expired URL | An editor clicks Publish |
| Code deploys | Full cache purge, content re-requested from the CMS | Worker updates in place, content stays warm |
| Editors & QA | Stale content and manual cache busting | Updates show up within seconds |
| Cache hit ratio | 75% to 95%, zero after a full purge | Close to 100%, including right after a deploy |
| Time to first byte | Fast on a hit, 300ms to 2.5s on a miss | 10ms to 40ms on every request |
| CMS API & origin load | Spikes with traffic, TTL expirations and deploys | Scales with how often editors publish |
The Hard Part: Dependency Graphs
With TTLs you don't have to think about how content is related. If an editor changes an author's bio, the timers expire and the website fixes itself. In a push cache nothing expires, so you have to handle those relationships yourself. There are two patterns I'd use:
- Dependency index: keep a small map of relationships in D1 or KV (an author, their articles, the homepage) so one webhook queues updates for only the affected items.
-
Fragment stitching: store each entity separately (
post:123,author:456,global-nav) and let the Worker assemble the page at request time. Updateauthor:456once and every article by that author shows the new bio, without rebuilding 400 article payloads.
When a Push Cache Is Worth Building
It adds real complexity, so it's overkill for a 20 page brochure website.
Skip It
- Under 500 pages, infrequent deploys and modest traffic.
- Re-fetching everything after a deploy is a few megabytes and costs pennies.
- Waiting a couple of minutes for a TTL doesn't bother your editors or QA team.
Build It
- Tens of thousands of URLs or more, with frontend deploys multiple times a week.
- Editors publish around the clock and can't wait on stale caches.
- You're paying overages for ISR revalidations, serverless compute or CMS API usage.
- You want the public website fully separated from the CMS, and online even when the CMS is down.
If you're still deciding whether headless is right for you at all, start with Headless CMS Systems for Enterprise Organizations.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.