By the end of this tutorial, you’ll be able to configure HTTP caching headers on your server so returning visitors load your pages from their local cache instead of re-downloading every asset. You’ll know which files deserve long cache lifetimes, how to verify the headers are working, and when caching can backfire.
This guide is written for someone who can edit a server config file and read an HTTP response, but who hasn’t yet set up a deliberate caching policy. We’ll cover the beginner path first, then show how advanced practitioners push the same primitives further.


The One-Minute Mental Model
Before touching any config, internalize this: browser caching is a negotiation between your server and the visitor’s browser, conducted through response headers. The server says “you may keep this file for X seconds.” The browser decides whether to comply and for how long.
The single most important header is Cache-Control. It replaces the older Expires header and gives you fine-grained control through directives like max-age, public, private, no-cache, and immutable.
A second mechanism, validation, uses ETag or Last-Modified. Even when a cached file expires, the browser can ask the server “has this changed?” via a conditional request. If nothing changed, the server replies with a tiny 304 Not Modified response instead of the full file. Validation saves bandwidth but still costs a round trip, which is why long max-age values matter for assets that rarely change.
Beginner Path: The Minimum Viable Caching Setup
The beginner goal is simple: cache static assets (CSS, JS, fonts, images) for a long time, and don’t cache HTML aggressively. That combination gives you fast repeat visits without the risk of users seeing stale pages.
Step 1: Understand Your Asset Fingerprinting
Before you set a one-year cache lifetime, confirm your build process adds a content hash to filenames, like app.a1b2c3.js instead of app.js. Fingerprinted filenames are the safety net that makes long caching safe: when the file content changes, the filename changes, so the browser fetches the new URL and never serves a stale file.
If your assets don’t have hashes, start with a shorter lifetime (e.g., max-age=3600) and fix your build pipeline before increasing it.
Step 2: Add Cache-Control Headers per File Type
Here is a practical starting policy, expressible in Nginx. The idea applies to any server.
# Static assets with content-hashed filenames: cache for one year
location ~* \.(?:css|js|woff2?|ttf|otf|eot|svg|png|jpe?g|gif|webp|avif|ico)$ {
add_header Cache-Control "public, max-age=31536000, immutable";
access_log off;
}
# HTML: always revalidate so users get fresh content
location ~* \.html$ {
add_header Cache-Control "public, max-age=0, must-revalidate";
}
# JSON/API responses: short cache, private by default
location ~* \.json$ {
add_header Cache-Control "private, max-age=60";
}
The equivalent for Apache, using mod_headers and mod_expires:
<IfModule mod_headers.c>
<FilesMatch "\.(css|js|woff2?|svg|png|jpe?g|webp|avif|ico)$">
Header set Cache-Control "public, max-age=31536000, immutable"
</FilesMatch>
<FilesMatch "\.html$">
Header set Cache-Control "public, max-age=0, must-revalidate"
</FilesMatch>
</IfModule>
A few directives deserve explanation:
public— the response may be stored by shared caches (CDNs, proxies).private— only the end-user browser may store it; shared caches must not. Use this for anything user-specific.immutable— the browser won’t revalidate even on a forced reload. Safe only for fingerprinted assets.must-revalidate— once stale, the browser must check with the server before using the cached copy.
Step 3: Verify With curl
After applying the config and reloading your server, confirm the headers are present. curl -I sends a HEAD request and prints the response headers.
curl -I https://your-site.com/assets/app.a1b2c3.js
Look for a line like:
cache-control: public, max-age=31536000, immutable
If you don’t see it, the server block likely didn’t match. Double-check the regex, that you reloaded the config, and that a CDN in front of your origin isn’t stripping the header.
Step 4: Verify in the Browser
Open DevTools, go to the Network tab, and reload. Then look at the Size column for a cached asset. You should see (memory cache) or (disk cache) rather than a byte count. Selecting the request and inspecting Response Headers shows the same Cache-Control value curl returned.
For a second confirmation, watch the Timing tab on a repeat load: a fully cached asset typically shows under a millisecond, with no DNS or connection cost.
Advanced Path: Taking Control of the Cache
Once the basic policy works, advanced practitioners tune the finer details. The gains here are smaller but compound across a large site.
Use Content Hashing in the Build Pipeline
Most modern bundlers (Vite, webpack, esbuild) support [contenthash] in output filenames. This is what makes the one-year immutable header safe. Without it, you’d be forced into shorter lifetimes or manual cache-busting query strings.
Split Caching by Asset Stability
Not all assets change at the same rate. Vendor bundles (node_modules output) change only when you update dependencies, while application code changes with every deploy. Give vendor bundles a longer lifetime and app code a moderate one. Add a stale-while-revalidate directive to let the browser serve a slightly stale asset while it fetches a fresh copy in the background:
Cache-Control: public, max-age=86400, stale-while-revalidate=604800
Handle the “Hard Reload” Trap
immutable is a small but real risk: if a filename is reused across deploys without a hash change, users on a forced refresh will still get the stale file. The mitigation is discipline — never reuse a hashed filename. If your deployment pipeline can’t guarantee that, drop immutable and keep max-age alone.
Service Workers and Cache Storage
For offline-first behavior, a service worker’s Cache Storage API gives you programmatic control beyond HTTP headers. This is a different layer from Cache-Control and out of scope for a basic tutorial, but worth knowing exists. Don’t layer a service worker cache on top of aggressive HTTP caching without a clear strategy; the two can conflict and leave users on stale content.
Comparison: Beginner vs Advanced Caching Decisions
| Decision | Beginner Choice | Advanced Choice | Trade-off |
|---|---|---|---|
| Static asset lifetime | max-age=31536000 (1 year) | Same, plus split vendor/app bundles | Longer needs reliable hashing |
| HTML caching | max-age=0, must-revalidate | Often no-cache at origin, cached at CDN edge | CDN caching HTML needs careful purge strategy |
| Fingerprinting | Yes, via build tool | Yes, plus asset manifest for server rendering | Extra build step to maintain |
immutable directive | Optional | Added once hashing is proven reliable | Risk if filenames are reused |
| Validation headers | ETag left on automatically | ETag plus Last-Modified for API responses | More conditional requests, better bandwidth savings |
| CDN layer | Not configured | s-maxage for shared cache, stale-while-revalidate at edge | More moving parts; needs purge automation |
Where Caching Goes Wrong
A few failure modes are worth calling out because they’re common.
- Caching HTML like a static asset. Users see an old page for hours after a deploy. Fix:
must-revalidateon HTML, or a CDN purge hook in your deploy pipeline. - Forgetting user-specific responses. Caching a
Set-Cookieresponse or a logged-in dashboard withpublicleaks one user’s data to another. Fix:privateon anything behind auth. - Stale CDN + fresh origin mismatch. A CDN caching an asset for a year while your origin returns the full file will keep the stale copy alive. Fix: ensure CDN caching honors origin
Cache-Control, and purge on deploy when filenames aren’t hashed. - Setting
max-agewithout content hashing. The most common beginner mistake. The browser cachesapp.jsfor a year; you deploy a newapp.js; users keep the old file. Fix: hash filenames first, then lengthen the cache.
Verifying Your Work, End to End
After the config is live, do a full verification pass:
- Run
curl -Iagainst one hashed asset, one HTML page, and one API endpoint. - Confirm the response headers match the policy you intended.
- Open DevTools, load the page twice, and confirm the second load shows cached assets with sub-millisecond timing.
- Use a third-party header checker or your CDN’s diagnostics to confirm headers aren’t being rewritten in transit.
Once those four checks pass, your site is serving cached assets correctly, and repeat visits benefit from what is usually a substantial reduction in transferred bytes — commonly the single biggest lever for repeat-visit performance after image optimization. Related guides: Mastering Script Loading: A Deep Dive into Async vs. Defer for Peak Performance, Caching Strategies for Beginners: A Step-by-Step Guide to Faster Page Loads, and HTTP/3 Isn’t Just Faster, It’s Smarter: Debunking Myths About the Web’s Next Evolution.
🔗 Recommended Reading
- Web Performance Monitoring Tools Compared: Lighthouse, PageSpeed Insights, and WebPageTest
- CDN vs. Origin Server: Which to Optimize First for Latency
- Common Mistakes That Break Web Font Performance and How to Fix Them
- Site Speed Optimization for Fintech Websites: Balancing Security, Compliance, and Performance
- Core Web Vitals for Beginners: A Step-by-Step Guide to Measuring Your First Audit