Caching static assets without breaking deploys

Long cache lifetimes are the cheapest performance win on a static site, and the easiest to get wrong. The failure mode is familiar: you ship a fix, but visitors keep seeing the old stylesheet for a month.

The reliable pattern is to put a content hash or a version in the file name of anything that is cached for a long time, for example app.3f9c1a.css. A changed file gets a new name, so it can safely be served with a one-year lifetime.

Documents are the opposite case

HTML documents reference the hashed assets, so they must be revalidated. Serve them with no-cache and rely on ETag or Last-Modified, so that a repeat visit costs a small 304 response instead of a full download.

In nginx this comes down to two location blocks: one for asset extensions with a long lifetime, and the default one for documents. Remember that add_header inside a location replaces the inherited headers, so repeat any security headers there.

Verify the result with curl -I. Look at Cache-Control, ETag and Age, then send a second request with If-None-Match to confirm that you receive a 304.