![\"Diagram](\"/images/journal-inline-cloudflare-stale-cache.webp\")
\n There are few things as frustrating as deploying a fix or feature, only to see the old version stubbornly persist for users. I've wasted too much time debugging \"ghost\" issues that vanish on a hard refresh, making me question my own sanity and the integrity of my build process. This pervasive struggle with external caching layers is a significant source of developer frustration.
\n\nThe specific problem, where Cloudflare's caching holds onto stale assets after a deploy, has plagued me numerous times. It creates the illusion that your deploy failed or your build system isn't functioning, but often it's just a CDN doing its job too well, blocking critical updates from propagating by aggressively caching content.
\n\nUsers see outdated CSS, broken JavaScript, or old images that should have updated. Meanwhile, I'm verifying the latest code on the origin server, wondering why the world isn't seeing my changes. This disconnect between successful deployment and actual content delivery demands a precise, automated strategy for consistency and reliability.
\n\n# Purge hashed assets after deploy — not the whole zone\ncurl -X POST \"https://api.cloudflare.com/client/v4/zones/$ZONE/purge_cache\" \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -d '{\"prefixes\":[\"example.com/assets/\"]}'\n
CDNs like Cloudflare sit between your server and the user, caching static content at edge nodes closer to them. This speeds delivery and reduces server load. Cloudflare decides what to cache and for how long based on HTTP Cache-Control and Expires headers from your origin, dictating caching behavior for all intermediaries, including the CDN and the user's browser.
\n\nIf your server tells Cloudflare to cache a file for a week (e.g., max-age=604800), it typically honors that, serving it globally. While great for stable assets, this is awful for rapid updates. Deploying a new style.css means Cloudflare might serve the old, cached version for days, completely bypassing your intended update.
\n\nBrowsers also maintain their own local caches, adding another layer of complexity. Even if Cloudflare gets the new file, a user's browser might still display an even older, locally cached version. Understanding this multi-layered caching hierarchy – origin headers, CDN rules, and browser behavior – is fundamental to effective debugging and fixing.
\n\nFor briancrabtree.me, I run a static site generated by a custom build process, deployed to a simple web server. Cloudflare handles DNS, SSL, and crucially, caching. My CI/CD pipeline pushes new builds to the server on every successful commit to main, ensuring a rapid iteration cycle.
\n\nThe breaks typically occurred with CSS or JavaScript updates. I'd commit, the pipeline would finish, and files would be on the server. But checking the live site, visual changes weren't present. A direct curl to my origin showed the new file, but one through Cloudflare's network stubbornly returned the old.
\n\nI once shipped a critical UI fix that just wouldn't show up for an hour. It was frustrating, professionally embarrassing, and reflected poorly on site reliability. This experience taught me that simply pushing code isn't enough; we must actively manage the entire content distribution pipeline.
\n\nMy first reaction was often to \"Purge Everything\" in the Cloudflare dashboard. While this works by forcing all edge nodes to re-fetch, it's a blunt instrument with significant performance drawbacks. Temporarily, it kills the CDN's primary benefit, as all subsequent user requests become \"MISS\" hits, requiring a full origin round trip.
\n\nI also tried appending cache-busting query strings like ?v=123 to filenames, hoping to force a fresh fetch. This approach is notoriously inconsistent across different browsers and intermediate proxies. Furthermore, it's tedious to manage manually, and if not handled carefully, can lead to duplicate content issues and unnecessary server load.
\n\nThese initial methods felt less like robust solutions and more like desperate workarounds. They addressed the immediate symptom of stale content but failed to tackle the underlying cause: a mismatch between my rapid deployment strategy and Cloudflare's default caching behavior. I needed a more targeted, automated approach.
\n\nThe pivotal shift was precisely telling Cloudflare which files had changed. Cloudflare's API offers granular control over its cache, enabling purging specific URLs or entire directories. This programmatic control is infinitely more efficient and less disruptive than a blanket \"Purge Everything.\" My build process now identifies modified files, sending targeted purge requests to the Cloudflare API.
\n\nFor HTML files, which serve as the entry point, I implemented Cache-Control: max-age=0, must-revalidate at the origin. This crucial directive instructs both Cloudflare and browsers to always check with the origin server before serving cached HTML. This guarantees the main page and its references to other assets are always current.
\n\nConversely, for truly static assets like images or fonts, I continue to leverage longer cache times. My site's custom build process, detailed in How This Site Is Built (Reference Stack), automatically applies these tailored HTTP headers based on asset type, striking a critical balance between optimal performance and immediate content freshness.
\n\nThe most robust and elegant solution I adopted for CSS and JavaScript files is asset versioning, or fingerprinting filenames. Instead of style.css, my build tools now output a unique filename like style.a1b2c3d4.css. The critical principle here is immutability: if the content changes, its cryptographic hash also changes, creating a new and unique filename.
\n\nThis allows Cloudflare, and any caching layer, to cache these fingerprinted files indefinitely, often with Cache-Control: public, max-age=31536000, immutable headers for a year or more. Indefinite caching is safe because the content under that specific filename will never change. When I deploy an update, the HTML simply references the new filename.
\n\nThis sophisticated strategy completely solves the problem of CDN serving old files after an update without requiring aggressive purging. It ensures users consistently receive the correct, latest version of assets every time they visit the site, with zero manual intervention. My build tooling automatically handles the fingerprinting, making it a \"set it and forget it\" part of the automated deployment workflow.
\n\nMy current strategy is an integrated system that combines aggressive Cache-Control for HTML, targeted Cloudflare API purging for critical updates, and comprehensive asset fingerprinting for static assets. This multi-faceted approach ensures immediate visibility of updates while maintaining strong caching performance, resulting in a highly reliable and performant content delivery workflow.
\n\nMy CI/CD pipeline now includes an explicit step to invoke the Cloudflare API for cache purging. If any HTML pages are directly modified, the pipeline automatically sends targeted requests to cloudflare purge cache deploy for those specific URLs. This small, yet incredibly powerful, automated step has virtually eliminated all instances of stale content persisting unexpectedly.
\n\nBuilding robust and resilient deployment pipelines is crucial for consistent performance, maintaining a positive user experience, and safeguarding the credibility of your online presence. For those interested in delving deeper into the technical specifics of this site's deployment, caching strategies, and custom tooling, I highly recommend exploring How This Site Is Built (Reference Stack).
","tags":["cloudflare","cdn","caching"],"views":87}