HTTP Caching Explained: max-age, ETag and Why Your Users Still See Last Week's CSS

When you fix a CSS issue and deploy it, opening the site yourself confirms everything is working. However, a customer sends a screenshot of an outdated layout. The browser is following the established caching contract, delivering last week's CSS despite the update. This demonstrates caching's role in web performance, often overlooked as merely a setting rather than a contract with consequences.

The example uses PlantPal, a small plant shop website featuring one stylesheet (app.css), one logo (logo.png), and one API endpoint (/api/products). A page load involves approximately 40 separate requests, transferring about 1.2 MB of data and taking roughly 2.1 seconds to provide a usable page. The key takeaway is that the fastest request is the one the browser never sends.

Cache-Control: max-age=31536000 instructs browsers to store and reuse a file for a year without further requests. This is the blunt instrument of caching, intending to minimize unnecessary trips to the server. When a user revisits the site, the browser reads the cached app.css file from their disk, resulting in a 0 ms response time. However, this is not a fast request; it's a no request situation, with no server interaction, bandwidth usage, or potential network issues.

Cache-Control is a directive to all caches along the path from the server to the user, including CDNs, proxies, ISPs, and the browser. This powerful control can lead to unintended consequences, such as serving outdated content to multiple users simultaneously. The private directive can mitigate this risk by preventing shared caches from storing user-specific content.

Once you've implemented the fix, you must realize that the fixed version will be served to any subsequent requests for one year. This creates an asymmetry, as the cached version remains in users' browsers for an extended period, regardless of their location or subsequent visits. The cache's promise cannot be revoked once set, leading to potential performance issues if not managed carefully.