What the Browser Cache Policy Builder does
This builder designs a Cache-Control policy for each kind of resource on a site - HTML, fingerprinted scripts and styles, images, API responses, account pages - shows what a browser and a CDN will actually do with each one over time, and writes the matching configuration for Nginx, Apache, IIS and Express.
Caching mistakes are costly in both directions. Too little and every visit re-downloads files that never change; too much and visitors keep an old page pointing at scripts that no longer exist, or a shared cache hands one user's account data to another. The behaviour follows fixed rules in RFC 9111, and the timeline here applies them so you can see the consequence before you deploy.
How to use it
- Load an example or add rules. Each rule has a resource type, the file extensions or path prefix it applies to, and a Cache-Control value. Picking a type fills in a sensible starting policy.
- Edit the Cache-Control value directly if your case differs. Unknown or malformed directives are reported under the rules.
- Choose a rule to simulate and a time span. Two bars show what the browser cache and a CDN or other shared cache do with a request arriving at any moment after the response was stored: serve it fresh, serve it stale while refreshing, use it only if the origin fails, or go back to the origin.
- Read the findings. They catch contradictions such as
publicwithprivate,immutableon a URL that does not change, long browser caching on HTML, and personal API responses a CDN could store. - Pick your server and copy or download the configuration.
Reading the results
Fresh means the cache answers without contacting the server at all. Revalidate means it asks the server whether its copy is still current; with an ETag or Last-Modified the answer is usually a small 304 response, which saves the download but not the round trip.
The browser uses max-age; shared caches such as CDNs use s-maxage when it is present, falling back to max-age. private keeps a response out of shared caches, no-store keeps it out of every cache, and no-cache allows storing but insists on revalidation before every use - despite its name, it does not mean "do not cache".
stale-while-revalidate lets a cache answer immediately with the stale copy and fetch a fresh one in the background; stale-if-error lets it use the stale copy when the origin is failing. must-revalidate forbids both, and under RFC 9111 s-maxage implies the same for shared caches. The simulation follows the RFC; some CDNs choose to honour the stale directives anyway, which their documentation will say.
Worked example: a content site behind a CDN
The "Site with a CDN" example has four rules. Fingerprinted files such as app.3f9a1c.js get public, max-age=31536000, immutable: fresh for a year in both caches, never revalidated, because a change produces a new file name. Images get public, max-age=604800, stale-while-revalidate=86400: fresh for 7 days, then served stale for up to one more day while a background request refreshes them.
Ordinary HTML gets no-cache, so every page view checks with the origin but can reuse the copy on a 304. Blog HTML gets public, max-age=0, s-maxage=300, stale-while-revalidate=60, stale-if-error=86400. On the timeline, the browser treats it as stale from the first second, but can serve it stale for 60 seconds while it refreshes. The CDN keeps it fresh for 5 minutes (300 s) and then, following RFC 9111, must revalidate - the stale directives do not apply there because s-maxage implies proxy-revalidate, and the findings point this out.
Publishing an article therefore reaches CDN visitors within 5 minutes without any purge, while the origin sees at most one request per page per 5 minutes per CDN location.
The pattern most sites need
Give every static asset a content hash in its file name and cache it for a year with immutable. Keep HTML short-lived or no-cache, because the HTML is what points at the current asset names. Put per-user API responses behind private (or no-store for anything sensitive), and let the CDN's lifetime for shared pages be controlled separately with s-maxage.
Changing a policy later is slow: a browser that stored a file for a year will not ask again until the year is up. Start conservatively for anything without a fingerprint.
Limitations: what the result does not prove
- It designs and explains headers; it does not read what your server sends today. Use the Cache-Control Checker for that, and check again after deploying - frameworks, CDNs and hosting panels often add or override headers.
- CDNs have their own rules on top of HTTP: some ignore
privatewithout extra settings, some cap lifetimes, some honourstale-while-revalidatewiths-maxage. The simulation follows the RFCs, not any one vendor. - Heuristic freshness - what caches do when no lifetime is given - differs between browsers, so the tool shows it as unpredictable rather than guessing.
- Browser behaviour on reload, back/forward navigation and bfcache is outside
Cache-Controland is not simulated.
Privacy: where your data goes
Everything you paste, type or drop is processed in this browser tab. It is not uploaded, logged, stored or sent to analytics. Session recording and tag-manager scripts are switched off on this page.
Standards and sources
- RFC 9111 HTTP Caching - checked 19 Sep 2026
- RFC 5861 - HTTP Cache-Control Extensions for Stale Content
- RFC 8246 - HTTP Immutable Responses
- MDN - Cache-Control
- Nginx - ngx_http_headers_module (add_header)
- Apache HTTP Server - mod_headers
Frequently asked questions
What is the difference between no-cache and no-store?
no-cache lets a browser or CDN keep a copy but requires it to check with the server before every use, which usually costs only a 304 response. no-store forbids keeping a copy at all, so every request downloads the full response. Use no-store for sensitive pages such as account and payment screens.
What Cache-Control header should HTML pages use?
Usually no-cache, or a short max-age of a minute or two, because the HTML names the current script and style files and must not outlive them. If a CDN serves your HTML, give it a separate lifetime with s-maxage so shared caches can hold it longer than browsers do.
When is immutable safe to use?
Only when the URL changes whenever the content changes - files with a content hash in the name, such as app.3f9a1c.js. immutable tells browsers not to revalidate even when the user reloads, so on an unversioned file an update would not be seen until the lifetime ran out.
What does stale-while-revalidate do?
After the response expires, a cache may keep serving the stale copy for the given number of seconds while it fetches a fresh one in the background. Users get an instant response and the next request gets the update. It is defined in RFC 5861 and cancelled by must-revalidate.
What is the difference between max-age and s-maxage?
max-age applies to every cache, including the browser. s-maxage applies only to shared caches such as CDNs and proxies, and overrides max-age there. It also implies proxy-revalidate, so a shared cache must not serve the response stale once s-maxage expires.
How do I set Cache-Control for static files in IIS?
IIS applies headers by folder through location elements in web.config, so keep assets with the same policy in one folder. Use a customHeaders entry for Cache-Control, and remove the default so the value is not duplicated; the generated snippet does both.
Is it safe to cache API responses at a CDN?
Only if the response is identical for every user who can request that URL. Anything personalised needs private or no-store, otherwise a shared cache may give one user's data to the next. Public, non-personal endpoints can use s-maxage and stale-if-error to absorb load and outages.
Last reviewed by the A2Z.Tools team against the sources listed above.
