---
title: "Cache files for a year and pages briefly · Agent Wranglers"
url: https://agentwranglers.se/playbook/website/performance/cache-control
updated: 2026-10-20
licence: "All rights reserved"
---

# Cache files for a year and pages briefly

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Required
- Chapter: [Performance](https://agentwranglers.se/playbook/website/performance)
- Rule: Cache files with a content hash in their name for a year as `immutable`. Give HTML a `max-age` of at most 600 seconds, or `no-cache`.
- How: Add a content hash to asset file names at build time and serve them with `public, max-age=31536000, immutable`. Serve HTML with a short `max-age` plus `stale-while-revalidate`, or `no-cache` if pages must always be fresh. Keep older assets as [keep the previous build's assets](https://agentwranglers.se/playbook/website/site-architecture/keep-the-previous-build-s-assets) sets, so cached pages still load.
- Check: `curl -sI` on a hashed asset shows `max-age=31536000` and `immutable`. On an HTML page it shows `no-cache` or a `max-age` of 600 or less, and never `immutable`.

Example:

```nginx
# only hashed build output lives in /assets/
# add_header in a location drops the server-level add_header lines, so repeat them
location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}
location / {
    add_header Cache-Control "public, max-age=300, stale-while-revalidate=86400";
}
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers website playbook: https://agentwranglers.se/playbook/website/performance/cache-control`.

- Previous: [Send early hints only when they help](https://agentwranglers.se/playbook/website/performance/early-hints)
- Next: [Say which request headers change a response](https://agentwranglers.se/playbook/website/performance/vary)
- [Performance](https://agentwranglers.se/playbook/website/performance)