Performance Required

Cache files for a year and pages briefly

Cache files with a content hash in their name for a year as immutable, and give HTML a short lifetime with a fresh check.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

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 the last deploy's assets, so cached pages still load.

Example

# 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";
}

How to check

curl -sI on each file type shows the intended policy.

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.