How do I set up cache rules without breaking deployments?

To set up cache rules safely, the key is to avoid caching anything that changes during deployments unless you also version it.

Safe approach

1) Cache only immutable assets

Cache files that get unique names when they change, like:

• app.4f3c2.js
• styles.a91b7.css
• logo.9d1e.png

If a file’s content changes, its filename should change too. Then you can cache it aggressively.

2) Do not long-cache HTML

Your HTML page shell should usually be:

• Cache-Control: no-cache or
• Cache-Control: max-age=0, must-revalidate

Why: HTML references your assets. If HTML is cached too long, users may keep seeing old asset links after a deploy.

3) Use different cache rules by file type

A common setup:

• HTML: short-lived or revalidated every time
• JS/CSS/images/fonts with hashed names: long cache, e.g. 1 year
• API responses: cache carefully, usually short or conditional
• Admin/auth pages: no cache

Example:

HTML:
Cache-Control: no-cache

Hashed static assets:
Cache-Control: public, max-age=31536000, immutable

4) Version your assets

If you can’t hash filenames, use versioned paths:

• /v123/app.js
• /release-2026-10-12/app.js

Then each deployment points to a new versioned path, preventing stale assets.

5) Purge or invalidate on deploy if needed

If you use a CDN or reverse proxy cache:

• purge changed HTML and non-versioned assets on deploy
• avoid purging hashed assets; they can just expire naturally

6) Test the deployment flow

Before rolling out:

• deploy to staging
• hard refresh and normal refresh
• test from a browser with old cached assets
• verify old HTML doesn’t reference missing files
• verify new HTML references new hashed assets

Common failure mode

A deployment breaks when:

• HTML is cached
• JS/CSS filenames are not versioned
• a new deploy deletes old assets before all cached HTML has expired

To prevent that, either:

• keep old assets around for a while, or
• make filenames immutable and versioned

Recommended rule of thumb

If users may request the same URL before and after a deploy:

• cache it only if its content never changes
• otherwise revalidate or version it

If you want, I can give you a cache policy specifically for:

• Nginx
• Cloudflare
• AWS CloudFront
• a React/Vite/Webpack app
• an API + static site setup