Dashboard

What Is the Cache-Control Header? Settings That Matter

Cache-Control decides how long browsers and CDNs may reuse a response. Here is what each directive means, the no-cache trap, and three safe settings for a small app.

Carlo Zuercher
Carlo Zuercher
Staff Engineer, Platform
30 October 20261 min read

The Cache-Control header is a line your server adds to a response that tells browsers and CDNs how long they may keep a copy and reuse it without asking again. Set it well and repeat visits are instant and your server does less work. Set it badly and visitors see stale pages, or worse, see someone else's.

You do not need to memorize the full list. Three response types cover almost every small app, and a handful of directives cover those three.

The directives that matter

These definitions follow MDN's Cache-Control reference.

  • `max-age=N`: the response stays fresh for N seconds after the origin generated it. max-age=604800 is seven days.

  • `no-cache`: the response can be stored, but must be revalidated with the server before each reuse. MDN is explicit that this does not mean "do not cache".

  • `no-store`: no cache of any kind may store the response. This is the one that really means do not keep it.

  • `public`: shared caches such as a CDN or proxy may store it.

  • `private`: only the user's own browser may store it, never a shared cache.

  • `immutable`: the response will not change while it is fresh, so caches need not revalidate it, even on reload.

  • `stale-while-revalidate=N`: after the response goes stale, a cache may still serve it for N more seconds while it fetches a fresh copy in the background.

The most common misunderstanding is no-cache versus no-store. If you want a page never kept, use no-store. If you want it kept but always checked, use no-cache.

Pick by response type

  • Hashed static files such as app.3f9a1c.js: Cache-Control: public, max-age=31536000, immutable

  • HTML pages: Cache-Control: no-cache

  • Logged-in or personal data: Cache-Control: private, no-store

That list is the whole practical answer. The reasoning behind each line:

Hashed assets. If the filename changes whenever the content changes, a year of caching is safe, because a new version is a new URL. MDN lists this "cache busting" pattern as the use case for immutable. Most frameworks emit these hashed names by default, so this row is usually one line of config.

HTML pages. The page is the entry point that points at your asset URLs, so it must stay fresh. MDN's common pattern is no-cache for the HTML entry point. Browsers can still keep a copy and revalidate cheaply, which returns a quick "not modified" if nothing changed.

Personal data. Anything that depends on who is logged in must never sit in a shared cache. MDN notes that omitting private on personalized content, such as responses tied to cookie sessions, risks leaking data through shared caches. If one visitor's dashboard is cached at the CDN and served to the next visitor, you have a data breach caused by one missing word.

The bug AI-generated code ships

Assistants often set caching in the wrong direction. Two patterns show up:

  1. A blanket `max-age` on API routes copied from a static-file example. Users then see yesterday's data after they edit something, and bug reports say "it does not save".

  2. No header on authenticated pages while a CDN sits in front. Some CDNs cache responses by default under certain conditions, and an authenticated page with no private is a candidate. Test it rather than trust it.

A quick check from a terminal:

bash
curl -sI https://your-site.example/dashboard | grep -i -E 'cache-control|age|vary'

Look at the response headers for the three types above. If a logged-in page shows public or a long max-age, fix it before anything else. Repeating the request and seeing an Age header that grows tells you a shared cache served it.

Stale-while-revalidate for the middle ground

For content that changes occasionally and does not need to be perfectly fresh, such as a public blog index or a pricing page, stale-while-revalidate is a good compromise. MDN's example sets max-age=604800, stale-while-revalidate=86400: fresh for a week, and for one more day it may be served immediately while a new copy is fetched in the background. Visitors never wait.

What a cache key adds

Caches treat the URL as the identity. If a page changes depending on a header, say the language, a Vary header tells caches which request headers to include. Without it, a French visitor can be handed the English copy. Mention this to your assistant whenever responses differ by cookie or language.

Header caching is one layer. A CDN sits in front and obeys these headers, app-level caching handles data on the server, and a reverse proxy is often where you set the headers in one place. If pages feel slow, start with why your AI-built app is slow. Do not confuse any of this with prompt caching, which is a model API feature that reuses a prompt prefix and has nothing to do with HTTP headers.

FAQ

What does Cache-Control: no-cache actually do?

It lets the browser store the response but forces it to check with the server before reusing it. It does not stop caching. For that, use no-store.

What is a good max-age for static files?

If the filenames contain a content hash, one year (31536000 seconds) with immutable is standard. If filenames never change, use a short value instead.

What is the difference between public and private?

public lets shared caches like a CDN store the response. private limits storage to the user's own browser, and is right for anything personalized.

Why do users see old content after I deploy?

Usually HTML or asset URLs were cached with a long max-age and no content hash. Serve HTML with no-cache and hash your asset filenames.

Does Cache-Control affect SEO?

Indirectly. Fast repeat loads help the experience, and stale or broken caching can show crawlers outdated pages. Keep HTML revalidated and assets long-lived.

How did this land?

About the author

Carlo Zuercher
Carlo Zuercher

Staff Engineer, Platform

Carlo works on the platform that turns prompts into running apps. He writes the engineering deep dives and the changelog notes worth reading.

Share

Get the next post in your inbox

One email a month. Product updates, engineering posts, and the best of Built with Swarmz.

I agree to receive emails about AI building tips and Swarmz product news. Unsubscribe any time.