Yastatic

Cache-Control for static assets: the short version

Fingerprinted files get a year, HTML gets revalidation, and everything else is a judgement call.

Most caching bugs I get asked to look at come from one decision made too early: a single Cache-Control header for the whole site. It is convenient, and it is wrong for at least half of the files.

The split that works is boring. Anything whose file name contains a content hash (app.3f9c1e.js, main.a81b22.css) can be cached for a year and marked immutable. The name changes whenever the content does, so there is nothing to revalidate.

location ~* \.[0-9a-f]{6,}\.(css|js|woff2|svg|png|webp)$ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}
location / {
    add_header Cache-Control "no-cache";
}

HTML is the opposite case. It is the entry point that references the hashed files, so it has to be fresh. no-cache does not mean "do not store"; it means "store, but ask before using". With an ETag the answer is usually a 304 of a few hundred bytes.

The grey zone is files with stable names that you do not control: favicons, robots.txt, a web manifest. An hour to a day is a reasonable range. If you would be embarrassed by a stale copy living for a week, do not allow a week.

One more thing worth checking: whatever sits in front of the origin. A reverse proxy that strips or rewrites the header silently undoes all of the above, and you will only notice when a deploy "does not show up" for some visitors.