Self-hosting behind Cloudflare: the caching gotchas nobody warns you about
Putting Cloudflare in front of a self-hosted site is one of the best free moves you can make: it hides your home IP, absorbs traffic spikes, and gives you HTTPS without exposing your origin. But it also introduces a class of bug that will make you doubt your own deploys — because Cloudflare caches aggressively, and its defaults will override what your own server says. Here’s the map of the traps, learned the way these things always are.
The trap: a fix that’s already live but invisible
You change some CSS, deploy, reload, and nothing changes. You deploy again. Still nothing. You start wondering if the deploy even worked — you check the server, and the new file is right there. It did deploy. Cloudflare is just serving the old one from its edge cache, and will keep doing so for hours.
This is the core gotcha: a caching problem and a failed deploy look identical from the browser. Once you’ve been burned by it, you stop trusting “I reloaded and nothing changed” as evidence of anything.
What Cloudflare caches by default
By default Cloudflare caches static assets by file extension — .css, .js,
images, fonts — at its edge, and it overrides your origin’s Cache-Control
for those. So even if your nginx says “don’t cache this,” Cloudflare’s own rules
can decide otherwise. HTML is not cached by default on the standard setup,
which matters for the fix below.
The result: your HTML updates promptly, but the stylesheet and scripts it points at can be hours stale. You get a page half-new and half-old, which is often worse than fully stale — it looks broken.
The fix: fingerprint your assets, don’t cache your HTML
The robust pattern has two halves, and both are required:
-
Fingerprint asset filenames by content. Instead of
theme.css, shiptheme.a3f9c1.css, where the hash changes whenever the file’s content changes. A new build produces a new filename, so there’s nothing stale to serve — the URL itself is new. Cache these forever (Cache-Control: public, max-age=31536000, immutable); they never need revalidating because a change is a new name. Most build tools (Vite, Astro, webpack, Next) do this automatically. -
Never cache the HTML that references them. The HTML is the index that points at the current asset filenames, so it must always be fresh. Send it
Cache-Control: no-cachefrom your origin. Because Cloudflare doesn’t cache HTML by default,no-cacheHTML plus fingerprinted assets means a deploy goes live immediately: fresh HTML points at the new asset names, and the new names have never been cached.
A stamped asset URL is useless if the page carrying it is itself cached — that combination is exactly how you get the “looks like it worked but didn’t” state. You need both halves.
The gotcha inside the gotcha: relative imports
If you version assets with a query string (app.js?v=2) rather than the
filename, watch out for JavaScript module imports. A relative import resolves
against the importing file’s URL without its query string — so ?v= on your
entry file leaves every module it imports pointing at the old, cached URL. It
looks like versioning worked, because the entry file updated; the rest of the
graph is stale. Version the filename or the directory, not the query string,
for anything with relative imports.
Give yourself a way to check
Because “reload and look” lies, add an endpoint that reports what’s actually
deployed — a tiny /api/build that returns a hash derived from the shipped
files. Read it, deploy, read it again: if the value didn’t move, your push
didn’t land, and no amount of hard-refreshing will change that. It turns “is it
cached or did the deploy fail?” from a guessing game into a two-second check.
Derive the value from the files themselves, never a constant you have to
remember to bump — a stamp you forget to update reports “nothing changed” for a
deploy that did.
The short version
Cloudflare will serve stale assets for hours and override your origin to do it.
Fingerprint asset filenames and cache them forever; send no-cache on the HTML
that points at them; version filenames, not query strings, when modules import
each other; and add a build-stamp endpoint so a cache miss can’t masquerade as a
broken deploy. Do that and Cloudflare goes from a source of mystery to the free
win it’s supposed to be.