Static assets caching with versioningWhat it checks and how to fix it

What it checks

Checks whether the page's scripts and stylesheets carry a cache-busting version in their URL (a content hash, a ?v= parameter, a timestamp or a version number) and reads the Cache-Control of up to 10 of them. At least half the assets versioned, a max-age of 30 days or more and the immutable directive count in its favor; fewer than half versioned or a max-age under one day count against it. It passes when the good practices outweigh the issues and warns otherwise.

Why it matters

Long cache lifetimes are only safe when a file's URL changes with its content, otherwise visitors keep running a stale script after a deploy. Sites that cannot safely cache assets for long end up forcing returning visitors to re-download or revalidate their CSS and JavaScript on every visit.

How to fix it

Fingerprint asset filenames at build time, then cache them for a year as immutable.

<link rel="stylesheet" href="/assets/application-5b8e1f2a.css">
<script src="/assets/application-9c03d7e4.js" defer></script>

nginx

location /assets/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

Apache

<LocationMatch "^/assets/">
  Header set Cache-Control "public, max-age=31536000, immutable"
</LocationMatch>

Cloudflare: add a Cache Rule for your asset path with Edge TTL and Browser TTL set to one year.

Rails: Propshaft and Sprockets fingerprint everything under /assets; serve it with

config.public_file_server.headers = { "Cache-Control" => "public, max-age=31536000, immutable" }