Browser Caching

Master HTTP browser caching — Cache-Control directives, ETag and Last-Modified validation, immutable assets with content-hashed filenames, stale-while-revalidate patterns, and cache partitioning in modern browsers for optimal repeat-visit performance.

When to Use

• Repeat visitors experience slow page loads despite no content changes
• Lighthouse flags "Serve static assets with an efficient cache policy"
• DevTools Network panel shows 200 responses instead of 304 or (disk cache) for static assets
• You need to decide between no-cache, no-store, and max-age for different content types
• A deploy invalidates all cached assets unnecessarily (cache busting is too aggressive)
• Content-hashed filenames are not implemented and versioned assets are served with short TTLs
• Stale content is being served after deploys because cache invalidation is not working
• You need to understand cache partitioning impact on shared CDN-hosted resources
• API responses could benefit from conditional caching with ETags
• Cache hit rates on repeat visits are below 90%

Instructions

1. Audit current caching behavior. In Chrome DevTools Network panel, check the "Size" column. Values like "(disk cache)" or "(memory cache)" indicate cached resources. Look at response headers for Cache-Control directives. Resources without caching headers or with

   no-store

   are fetched fresh every time.

2. Design a caching strategy by content type. Different content types need different caching policies:

   Static assets (JS, CSS, images) with content hash:
     Cache-Control: public, max-age=31536000, immutable
   
   HTML documents:
     Cache-Control: no-cache
     (or: Cache-Control: public, max-age=0, must-revalidate)
   
   API responses (cacheable):
     Cache-Control: private, max-age=60, stale-while-revalidate=300
   
   User-specific data:
     Cache-Control: private, no-cache
   
   Sensitive data (banking, health):
     Cache-Control: no-store
   

3. Implement content-hashed filenames. Content hashing ensures cached files are automatically invalidated when content changes:

   # Build output with content hash
   app.a1b2c3d4.js     ← hash changes when code changes
   style.e5f6g7h8.css  ← hash changes when styles change
   vendor.i9j0k1l2.js  ← hash rarely changes (stable dependencies)
   
   # Cache-Control for hashed files
   Cache-Control: public, max-age=31536000, immutable
   # 1 year TTL + immutable = browser never revalidates
   

   The HTML document (not content-hashed) references specific hashed filenames. When you deploy, the HTML changes to reference new hashes, and the browser fetches the new files.

4. Configure ETag validation for dynamic content. ETags allow the browser to check if content has changed without re-downloading:

   # First request
   GET /api/products
   → 200 OK
   → ETag: "abc123"
   → Cache-Control: no-cache
   
   # Subsequent request (browser sends conditional request)
   GET /api/products
   If-None-Match: "abc123"
   → 304 Not Modified  (no body, saves bandwidth)
   

5. Use stale-while-revalidate for balanced freshness. This directive serves the cached version immediately while fetching a fresh copy in the background:

   Cache-Control: public, max-age=3600, stale-while-revalidate=86400
   
   Timeline:
   0-1h:    Serve from cache (fresh)
   1h-25h:  Serve from cache (stale) + revalidate in background
   >25h:    Must revalidate before serving (cache expired)
   

6. Understand browser cache layers. Browsers maintain multiple cache tiers:

   • Memory cache — fastest, cleared on tab close, used for preloaded resources and recently accessed items
   • Disk cache — persists across sessions, used for most HTTP-cached resources
   • Service Worker cache — application-controlled via Cache API
   • Push cache — HTTP/2 push cache, cleared after connection closes

7. Account for cache partitioning. Modern browsers (Chrome 86+, Firefox 85+) partition the HTTP cache by top-level site. A resource cached when visiting

   site-a.com

   is NOT reused when visiting

   site-b.com

   , even if the URL is identical. This impacts shared CDN-hosted resources (Google Fonts, cdnjs, unpkg) — self-hosting eliminates the cross-site cache miss.

Details

Cache-Control Directive Reference

public

private

max-age=N

s-maxage=N

no-cache

no-store

must-revalidate

immutable

stale-while-revalidate=N

stale-if-error=N

Worked Example: Twitter Static Asset Caching

Twitter serves static assets with

Cache-Control: public, max-age=31536000, immutable

main.a1b2c3d4.js

no-cache

Worked Example: Financial Times Stale-While-Revalidate

The Financial Times implemented

stale-while-revalidate

no-cache

Anti-Patterns

Using no-cache when you mean no-store.

no-cache

no-store

no-store

no-cache

Setting short max-age on versioned assets. If filenames contain content hashes, the content at that URL will never change. Setting

max-age=3600

app.a1b2c3.js

max-age=31536000, immutable

Forgetting Vary header with content negotiation. If your server returns different content based on

Accept-Encoding

Accept-Language

Vary

Accept-Encoding: br

Query string cache busting instead of filename hashing. URLs like

/app.js?v=123

/app.abc123.js

Source

• MDN Web Docs: HTTP Caching — https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching
• RFC 9111: HTTP Caching — https://www.rfc-editor.org/rfc/rfc9111
• web.dev: HTTP Cache — https://web.dev/articles/http-cache
• Chrome Cache Partitioning — https://developer.chrome.com/blog/http-cache-partitioning/
• Jake Archibald: "Caching best practices" — https://jakearchibald.com/2016/caching-best-practices/

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.
• Static assets with content hashes use

  max-age=31536000, immutable

  caching.
• HTML documents use

  no-cache

  or equivalent to ensure fresh content on navigation.
• Repeat visit network activity shows (disk cache) for static assets instead of 200 responses.