DIL.DEV
LOADING0%
DIL.DEV
← ALL NOTES

Week-Long Caching Mixed New HTML With Last Week's CSS

A one-week Cache-Control on fixed asset URLs let returning phones load fresh HTML against stale styles. A content-hash query string fixes it without sacrificing cache lifetime.

cachingbuild toolingstatic sitesnetlify

A terminal showing a build script appending a short SHA-256 hash to a CSS filename as a query string parameter.

A small static business site had its CSS and JS cached for a week at fixed URLs. That is a perfectly reasonable setup until you deploy on a Tuesday and a visitor's phone, which cached the assets last Wednesday, loads your new HTML against last week's styles. The fix is a content hash in the query string, computed once per file at build time, so the URL changes exactly when the file does.

What the Cache Config Actually Said

The site's netlify.toml set Cache-Control: public, max-age=604800 on the CSS and JS asset paths. That is seven days. A separate path got public, max-age=31536000, immutable, which is a year, reserved for assets that genuinely never change at a given URL.

Seven days is not aggressive. It is a sensible default for a site that does not deploy every hour. The problem is not the duration. The problem is that the URL never changed, so the browser had no signal that the file had changed.

How the Stale Mix Happens

  • The browser caches by URL. If /css/main.css is in cache and max-age has not expired, the browser uses the cached copy without asking the server.
  • HTML is not cached the same way. The HTML document typically has a much shorter or no cache, so a returning visitor gets fresh HTML immediately.
  • The mismatch is silent. No error. The page just looks wrong, or a script fails quietly, or a layout shifts in a way that is hard to reproduce in dev because dev has no cache.

The code comment in build/build.mjs spells it out directly: without the hash, a returning phone mixes new HTML with last week's styles.

The Build-Step Fix

The build script imports createHash from Node's built-in node:crypto. At build time, a versioned() function walks every href and src attribute that matches /css/*.css or /js/*.js and rewrites the URL to append ?v= plus the first ten hex characters of the file's SHA-256.

The steps in plain terms:

  • Read the file contents from disk.
  • Hash them with SHA-256.
  • Take the first ten hex characters. That is 40 bits of collision resistance, which is more than enough for cache busting on a static site.
  • Append to the URL: /css/main.css becomes /css/main.css?v=e48681f3a2 (or whatever the actual hash is for that file's contents).
  • Memoise per file in an assetVersion map so the same file is only hashed once per build, even if it is referenced from multiple pages.

The rewriting happens inside the out() writer, the function that writes each finished HTML file to the output directory. Every HTML file gets versioned URLs before it lands on disk.

Why Ten Hex Characters

Ten hex characters is a pragmatic choice, not a magic number.

  • Forty bits of entropy makes an accidental collision essentially impossible for a set of static assets.
  • Short enough to read in DevTools without squinting.
  • Stable across deploys when the file has not changed, which is the whole point.

You could use eight or twelve. Ten is a common convention, the same length git uses for short commit hashes.

Why This Beats a Shorter Cache

The instinct when you hit a stale cache bug is to reduce max-age. Set it to an hour, problem solved. But now every visitor re-downloads every asset every hour, even when nothing has changed. On a site with a handful of CSS and JS files that only change on deploy, you are burning bandwidth and adding latency for no reason.

Content hashing gives you the best of both: a long cache for files that have not changed, and immediate invalidation for files that have. The cache lifetime stays at a week. The URL changes only when the content changes.

Why This Beats a Build Timestamp

A build timestamp is tempting because it is trivial to implement. Stick ?v= and Date.now() at the end of every asset URL in your template. Done.

The problem: the timestamp changes on every deploy, so every asset URL changes on every deploy. A visitor who cached your CSS yesterday re-downloads it today even if you only changed one line in one JS file. You have effectively set max-age to the gap between your deploys, which is probably not what you wanted.

A content hash is selective. Only the files that changed get new URLs. Everything else stays cached.

The Trade-Off Against Hashed Filenames

The alternative is to bake the hash into the filename itself: main.e48681f3a2.css. This is what most bundlers do by default.

Hashed filenames have a real advantage: they work even in environments that strip or ignore query strings. Some CDNs and proxies do this, though it is rare for a straightforward Netlify setup.

The cost is that your HTML templates cannot hardcode the filename. You need a manifest file or some build-time lookup that maps main.css to main.e48681f3a2.css. That is extra infrastructure.

The query-string approach is simpler to add to an existing build script. The base filename stays the same, so the rest of the build pipeline does not need to know about the hash. You add one function, one map, one rewrite pass. For a small static site without a bundler already managing this, it is the lower-friction choice.

What the Netlify Config Looks Like in Practice

The netlify.toml keeps the week-long Cache-Control on the asset paths unchanged. The content hash in the query string is the only new thing. Netlify serves the file at the versioned URL with the same long cache header, and the browser caches it correctly.

When you next deploy with a changed CSS file, the hash changes, the URL changes, and the browser fetches the new file. The old cached version sits unused until it expires naturally. No manual cache purge needed.

What I'd do differently

  • Start with content hashing from the first deploy. It is not much extra work in a build script and it avoids the class of bug entirely.
  • Log the versioned URLs during the build so you can spot a file that is unexpectedly changing hash on every run, which would indicate the file is being generated with a timestamp or random value baked in.
  • Consider hashed filenames if a bundler is already in the picture. If you are running esbuild or Rollup anyway, let it manage the hashing and the manifest. The query-string approach is the right call when you are working with a lightweight custom build script and do not want to add that dependency.
  • Test with DevTools offline mode before shipping. Load the page, go offline, deploy a change, come back online, and check whether the browser picks up the new assets. It is a quick sanity check that would have caught this before it reached a real phone.

NOTES BY EMAIL

Get the next note in your inbox.

One email per note. No spam. Reply “stop” any time and you are off the list.