HTTP caching is one of the cheapest performance wins a small site can get. It is also a common source of strange bugs: a fixed stylesheet that some visitors never receive, a landing page that still shows last week's pricing section, or a logged-in page that a CDN serves to the wrong person. Nearly all of these come from a few headers that were misunderstood or never set.

This post sets out a small, defensible caching policy for a typical indie setup: a static or mostly static site, maybe a small API, maybe a CDN in front. It covers what the headers mean, how to configure them, and how to check the result yourself.

The questions every response answers

Every HTTP response tells caches three things, whether you set them on purpose or not:

  • Who may store it? Only the visitor's browser, or shared caches like CDNs and proxies as well?
  • For how long is it fresh? During that window, a cache can reuse it without contacting your server.
  • What happens after that? Can the cache ask your server "has this changed?" and get a cheap answer?

If you send no caching headers, browsers fall back to heuristics, often based on the Last-Modified date. That is how you end up with behavior nobody chose. Being explicit is the main goal.

The headers that matter

Cache-Control

This is the main header. The directives you will use most:

  • max-age=N: the response is fresh for N seconds.
  • s-maxage=N: like max-age, but only for shared caches (CDNs). Lets you cache longer at the edge than in browsers.
  • public / private: private means only the end user's browser may store it. Use it for anything personalized.
  • no-cache: the response may be stored, but it must be revalidated with the server before every reuse. This does not mean "don't cache".
  • no-store: never write it to any cache. Use it for sensitive responses.
  • immutable: a hint that the content will never change during its freshness window, so the browser should not revalidate even when the user reloads.
  • stale-while-revalidate=N: after the response goes stale, a cache may serve the stale copy for up to N more seconds while it fetches a fresh one in the background. Support varies between browsers and CDNs, so check the documentation for yours.

ETag and Last-Modified

These are validators. When a cached response goes stale, the browser sends If-None-Match (with the ETag) or If-Modified-Since (with the date). If nothing has changed, the server answers 304 Not Modified with no body. The browser still makes a round trip, but it skips the download. Most static file servers send one or both validators by default.

Vary

Vary tells caches which request headers change the response. Vary: Accept-Encoding is normal and expected, because the gzip and brotli versions are different bodies. Be careful with Vary: User-Agent or Vary: Cookie on public content. Both split the cache into many variants, and some CDNs will not cache those responses at all.

A three-bucket policy

Most small sites can sort every response into one of three buckets.

1. Fingerprinted static assets: cache for a long time

If your build tool puts a content hash in the filename, like app.3f9a1c.js, the URL changes whenever the content changes. A given URL then never needs revalidation:

Cache-Control: public, max-age=31536000, immutable

This is the most valuable rule in the whole policy, and it is only safe for hashed filenames. If you put it on /style.css, returning visitors may keep the old file until it expires.

2. HTML and other stable URLs: always revalidate

Your HTML references the hashed assets, so it has to stay current. The safe default is:

Cache-Control: no-cache

The browser keeps a copy, but checks with the server each time. Thanks to ETags, an unchanged page costs a small 304 response. If you have a CDN and a way to purge it on deploy, you can let the edge hold HTML longer while browsers still revalidate:

Cache-Control: public, max-age=0, s-maxage=300, must-revalidate

Unhashed files like favicon.ico, robots.txt and Open Graph images belong in this bucket too, or get a short max-age if a slightly stale copy is acceptable.

3. API responses: decide per endpoint

  • Anything user-specific or authenticated: private, no-store, or private, no-cache if you want revalidation.
  • Public data that changes slowly, such as a changelog feed or a config file for your app: a short max-age plus an ETag, for example public, max-age=60.
  • Writes (POST, PUT, DELETE): shared caches don't store these by default, but setting no-store on the response costs nothing and states your intent.

Configuring it

nginx

Assuming your build writes hashed files to /assets/:

server {
    root /var/www/site;

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

    location / {
        add_header Cache-Control "no-cache";
        try_files $uri $uri/ /index.html;
    }
}

One nginx gotcha: if a location block contains any add_header, it does not inherit add_header directives from the enclosing server block. If you set security headers at the server level, they can quietly disappear from the asset responses. Repeat them, or put them in a shared include file.

Static hosts with a _headers file

Several static hosts, including Netlify and Cloudflare Pages, read a _headers file from the build output:

/assets/*
  Cache-Control: public, max-age=31536000, immutable

/*
  Cache-Control: no-cache

Check your host's documentation for how overlapping rules are combined. Some hosts merge the headers from every matching rule instead of applying only the most specific one, and that can produce two conflicting Cache-Control values.

Verifying with curl

Don't rely on the configuration alone. Look at what is actually served, through the same domain your visitors use:

curl -sI https://example.com/ | grep -iE 'cache-control|etag|last-modified|age|vary'
curl -sI https://example.com/assets/app.3f9a1c.js | grep -i cache-control

Then test revalidation. Copy the ETag value from the first response and send it back:

curl -sI -H 'If-None-Match: "PASTE-ETAG-HERE"' https://example.com/

You should get HTTP/2 304. If you get a 200 with the full body, the validator isn't working. Compression or a proxy may be rewriting the ETag. Behind a CDN, also look for its cache status header (the name differs by provider) and the Age header, which shows how long the edge has been holding the object.

In browser DevTools, keep in mind that "Disable cache" in the Network panel bypasses everything you are trying to test. Turn it off, load the page twice, and check whether the assets show as served from memory or disk cache.

Common mistakes

  • Long caching on unhashed URLs. The usual cause of "I deployed the fix but users still see the bug".
  • Caching HTML at the CDN with no purge step. If the edge holds HTML, add a purge to your deploy script, or keep s-maxage short enough that a stale page doesn't matter.
  • Set-Cookie on cacheable responses. Depending on configuration, a shared cache may store one visitor's cookie and send it to others, or may refuse to cache the response at all. Keep session cookies off public pages.
  • Treating no-cache as no-store. They do opposite things for storage. Choose based on whether the content is sensitive.
  • Forgetting the service worker. If your site has one, it adds its own cache layer above HTTP caching. Check its strategy before debugging headers.
  • Deleting old hashed assets on deploy. A visitor with an older HTML page still open will request the old filenames. Keep the previous release's assets around for a while.

A short checklist

  1. Make sure your build fingerprints JS, CSS, fonts and images, and outputs them to a predictable directory.
  2. Serve that directory with public, max-age=31536000, immutable.
  3. Serve HTML with no-cache, or with a short s-maxage plus a purge on deploy.
  4. Mark personalized and authenticated responses private or no-store.
  5. Confirm ETags work end to end by getting a 304 from curl.
  6. Recheck headers after any change to your host, CDN or proxy.

Conclusion

A clear caching policy is short. Hashed assets are cached essentially forever, HTML is always revalidated, and private data is never shared. Most of the work goes into making sure filenames change when content changes, and into checking the real headers instead of assuming them. Set it up once, add the curl checks to your deploy notes, and caching becomes one less thing to wonder about when something looks stale.