Skip to content

Cache-Control for a static site

Which Cache-Control values a static site needs: revalidate the HTML, cache hashed files for a year, and how a Cloudflare Pages _headers file sets them.

· Updated · 4 min read

A card showing the Cache-Control values for HTML and for fingerprinted assets

A static site needs two caching rules. HTML should be revalidated every time, so visitors see new content at once. Files whose names contain a content hash, such as the scripts and styles a bundler produces, can be cached for a year and marked immutable, because their URL changes whenever their content does.

I checked the response headers of this site on 18 October 2026, the date this post was last updated, and the hashed files were not getting the long rule. Below are the directives, the Cloudflare Pages way to set them, what I measured and the change I made.

The directives that matter#

These definitions are from MDN's Cache-Control reference:

DirectiveMeaning
max-age=NThe response stays fresh until N seconds after it was generated.
immutableThe response will not be updated while it is fresh, so caches should not send a conditional request, even when the visitor reloads.
no-cacheThe response can be stored, but must be validated with the origin before each reuse. It does not mean "don't cache".
no-storeNo cache of any kind should store the response.
public / privateWhether a shared cache may store it, or only the visitor's browser.
must-revalidateOnce the response is stale, it must be validated with the origin before reuse.

MDN also warns about heuristic caching. If you send no Cache-Control header, a cache is allowed to store the response anyway and guess for how long, so if you have requirements you should state them.

The two-rule pattern#

MDN recommends this pattern for assets with versioned URLs, which it calls cache busting:

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

# /index.html
Cache-Control: no-cache

The reasoning is in one sentence from the page: when you update a file, the new content should have a new URL, so caches are not reused. The HTML references the new URL, so the HTML must not be cached for long.

A static export from a framework like Next.js fits this well. The files under /_next/static/ have a hash in their name. The pages themselves do not.

MDN adds a caveat for history navigations: no-cache does not guarantee revalidation when someone uses the back button, because a restored page can be served from the back and forward cache.

Setting headers on Cloudflare Pages#

Cloudflare Pages reads a plain text file called _headers from your build output, and in a framework project you usually put it in public/. The documentation describes the rules:

  • A rule starts with a URL pattern on its own line, followed by indented name: value lines.
  • A * splat matches greedily, and you can use one per URL.
  • You can define up to 100 rules, and a line can be at most 2,000 characters.
  • If a header is applied twice, the values are joined with a comma.
  • Redirects are applied before headers.
  • Custom headers are not applied to responses generated by Pages Functions.

What I measured#

On 18 October 2026 I requested a few URLs of this site and read the Cache-Control header:

URLCache-Control
The home page (HTML)public, max-age=0, must-revalidate
The blog list (HTML)public, max-age=0, must-revalidate
A hashed stylesheet under /_next/static/chunks/public, max-age=14400, must-revalidate
The default social card, og.pngpublic, max-age=14400, must-revalidate

The HTML rule is the right one: MDN notes that max-age=0, must-revalidate is equivalent to no-cache. The hashed stylesheet is not: it was cached for four hours and then revalidated, although its name changes whenever its content does. A returning visitor therefore sends a conditional request for each such file after four hours. That should be cheap: the file has an ETag, so the server can answer with a short "not modified" reply, but it is a round trip that a year-long immutable rule would remove. Cloudflare reported cf-cache-status: REVALIDATED for the stylesheet, meaning its edge copy was stale and it checked with the origin.

My _headers file had only two rules, one that marks the preview domain as noindex and one that sets a content type for the Markdown copies of the tool pages. I had not set a cache rule, so whatever Cloudflare sends by default applied.

The change#

I added a rule for the hashed build files:

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

I did not touch the HTML, and I did not apply the long rule to files such as images and example assets in other folders, because their names have no hash. A long cache on a file that keeps its name means visitors would see an old version until the cache expires.

Check it yourself#

  • Open the Network panel and look at the Cache-Control and ETag headers for your HTML and for one hashed file.
  • Or ask for the headers from a terminal with curl -I.
  • After a deploy, run curl -I on a hashed file and confirm it returns public, max-age=31536000, immutable.

Limits of this post#

I added the rule to the repository, but I have not deployed it or measured the result at the time of writing, so I cannot yet show the new headers. The measurements are one request each from one network. I did not check what Cloudflare does by default for other file types, and its documentation page I read does not describe the default Cache-Control behaviour.