System Design (HLD)Caching Strategies

Caching Layers

LevelIntermediate

Duration90 mins

TopicCaching Strategies

1 / 5

Client-Side Caching (Browser)

The First Line of Defense

In the multi-layered caching architecture of modern web applications, the browser cache represents the most impactful optimization opportunity. Every cache hit at the browser level eliminates network latency entirely—no DNS lookup, no TCP handshake, no TLS negotiation, no server processing, no data transfer. For static assets loaded on every page view, browser caching can reduce effective load times from seconds to milliseconds.

Yet browser caching is often misunderstood, misconfigured, or ignored entirely. Engineers frequently treat it as an afterthought, resulting in either aggressive caching that serves stale content or conservative settings that defeat the purpose. Mastering browser caching requires understanding both the underlying HTTP protocol mechanisms and the strategic considerations that guide their application.

What You Will Learn

This page covers the complete landscape of client-side caching: HTTP cache directives and their precise semantics, cache storage mechanisms including the Cache API and IndexedDB, Service Workers as programmable cache controllers, and strategic frameworks for deciding what to cache, for how long, and how to handle invalidation. By the end, you'll be able to design browser caching strategies that dramatically improve performance while maintaining content freshness.

Understanding the Browser Cache

The browser cache is a local storage mechanism that stores HTTP responses keyed by their request URL. When a browser needs a resource, it first checks the cache before making a network request. This simple concept masks considerable complexity in cache behavior, validation, and eviction.

The Cache Lookup Process:

When a browser encounters a resource request (whether from HTML parsing, JavaScript execution, or user navigation), it follows a well-defined process:

Construct the cache key — Typically the full URL including query parameters
Check for a cached response — Look up the key in the local cache store
Evaluate freshness — If found, determine whether the cached response is still valid
Serve or revalidate — Either serve directly from cache or validate with the origin server
Store new responses — If a network request is made, potentially cache the response

Browser Cache Behavior Based on Response Headers
Scenario	Cache Behavior	Network Request?	User Perception
Fresh cache hit	Serve from disk/memory cache	No	Instantaneous load (<10ms)
Stale with validation	Conditional request to server	Yes (small)	Fast if 304 Not Modified
Stale without etag/last-modified	Full request to server	Yes (full)	Normal load time
No-cache directive	Always validate before serving	Yes (small)	Slight delay for validation
No-store directive	Never cache this response	Yes (full)	Full load time every time

Memory Cache vs. Disk Cache:

Modern browsers maintain two-tier caching:

Memory cache — Extremely fast access (< 1ms), limited capacity, cleared on browser close. Used for resources likely to be needed again soon during the same session.
Disk cache — Slower access (5-20ms), much larger capacity, persists across sessions. Used for resources with longer lifetimes.

Browsers automatically manage allocation between these tiers based on resource size, access frequency, and available space. You cannot directly control this allocation, but you can influence it through cache headers.

Cache Key Considerations

The cache key is critically important. By default, it's the full URL including query parameters. This is why cache-busting techniques add version parameters (?v=1.2.3) or hash-based filenames (bundle.a7b3c9d.js). Vary headers can modify the cache key to account for different representations (e.g., Accept-Encoding, Accept-Language).

HTTP Cache-Control Directives

The Cache-Control HTTP header is the primary mechanism for controlling browser caching behavior. It supersedes the older Expires header and provides fine-grained control over how responses are cached, for how long, and under what conditions they can be used.

Understanding the Directive Categories:

Cache-Control directives fall into several functional categories:

Cacheability — Whether a response can be cached at all
Expiration — How long a cached response remains fresh
Revalidation — When and how stale responses must be revalidated
Other directives — Special behaviors for specific scenarios

Cache-Control Directive Reference
Directive	Category	Meaning	Common Use Case
public	Cacheability	Response can be cached by any cache (browser, CDN, proxy)	Static assets, public API responses
private	Cacheability	Response can only be cached by browser, not shared caches	Personalized content, authenticated responses
no-cache	Revalidation	Cache can store but must revalidate before each use	Always-fresh content (HTML pages)
no-store	Cacheability	Never store this response anywhere	Sensitive data, credit card forms
max-age=N	Expiration	Response is fresh for N seconds from request time	Static assets with known update frequency
s-maxage=N	Expiration	Override max-age for shared caches (CDN/proxy)	Different browser vs CDN expiration
must-revalidate	Revalidation	Once stale, must revalidate—cannot use stale copy	Critical data that must never be stale
stale-while-revalidate=N	Revalidation	Can serve stale for N seconds while revalidating in background	Non-critical content where freshness can lag
stale-if-error=N	Revalidation	Can serve stale for N seconds if revalidation fails	Graceful degradation during outages
immutable	Expiration	Response will never change—skip revalidation even on refresh	Versioned static assets (hash in filename)

Cache-Control Header Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Static asset with content-hash in filename - cache forever
Cache-Control: public, max-age=31536000, immutable
 
# HTML page that should always be fresh
Cache-Control: no-cache
 
# Authenticated API response - browser-only caching for 5 minutes
Cache-Control: private, max-age=300
 
# Public API that can lag slightly - serve stale while fetching fresh
Cache-Control: public, max-age=60, stale-while-revalidate=300
 
# Sensitive data that should never be stored
Cache-Control: no-store
 
# CDN caches for 1 hour, browsers cache for 5 minutes
Cache-Control: public, max-age=300, s-maxage=3600
 
# Critical data - must revalidate when stale, allow stale during errors
Cache-Control: max-age=300, must-revalidate, stale-if-error=86400

Common Misconception: no-cache vs no-store

Despite the name, 'no-cache' does NOT mean 'don't cache.' It means 'cache but revalidate before every use.' If you truly want to prevent caching entirely, use 'no-store.' This is one of the most common caching mistakes in production systems.

Validation and Conditional Requests

When a cached response becomes stale or the no-cache directive is present, browsers perform conditional requests to check whether the cached version is still valid. This validation mechanism is crucial for balancing freshness with efficiency—if the content hasn't changed, the server can respond with a lightweight 304 Not Modified instead of retransmitting the entire resource.

Two Validation Mechanisms:

HTTP provides two complementary approaches for cache validation:

ETag Validation

•Server provides ETag — An opaque identifier for the specific version of a resource
•Browser stores ETag — Cached alongside the response body
•Conditional request — Browser sends If-None-Match: <etag> header
•Server comparison — Compares provided ETag with current resource version
•Response — 304 if match (use cache), 200 with new content if changed

Last-Modified Validation

•Server provides Last-Modified — Timestamp of last resource change
•Browser stores timestamp — Cached alongside the response
•Conditional request — Browser sends If-Modified-Since: <date> header
•Server comparison — Checks if resource changed after provided date
•Response — 304 if unchanged, 200 with new content if modified

Conditional Request Flow
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# Initial Response from Server
HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: max-age=300
ETag: "abc123def456"
Last-Modified: Wed, 15 Jan 2025 10:30:00 GMT
 
<script content>
 
# ----------------------------------------
 
# Conditional Request (after 300 seconds)
GET /bundle.js HTTP/1.1
Host: example.com
If-None-Match: "abc123def456"
If-Modified-Since: Wed, 15 Jan 2025 10:30:00 GMT
 
# ----------------------------------------
 
# Response if unchanged (bandwidth savings!)
HTTP/1.1 304 Not Modified
ETag: "abc123def456"
Cache-Control: max-age=300
 
# No body - browser uses cached version
 
# ----------------------------------------
 
# Response if changed
HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: max-age=300
ETag: "xyz789new123"
Last-Modified: Thu, 16 Jan 2025 14:20:00 GMT
 
<new script content>

Choosing Between ETag and Last-Modified:

Factor	ETag	Last-Modified
Precision	Byte-exact (if strong ETag)	1-second resolution
Computation	Requires hash calculation	Just file timestamp
Distributed systems	Must coordinate ETag generation	Timestamps can vary across servers
Best for	API responses, dynamically generated content	Static files served from disk

Strong vs. Weak ETags:

A strong ETag (e.g., "abc123") guarantees byte-for-byte identity. A weak ETag (e.g., W/"abc123") indicates semantic equivalence—the content might differ in insignificant ways (whitespace, metadata). Use weak ETags when minor variations don't affect usability.

Validation Best Practice

Provide both ETag and Last-Modified headers when possible. ETag offers precision for APIs and dynamic content, while Last-Modified works reliably for static files and is more efficient to compute. Browsers will use ETag preferentially but fall back to Last-Modified if needed.

Cache Storage API and Service Workers

Beyond the HTTP cache that browsers manage automatically, modern web applications can leverage the Cache Storage API for programmatic control over cached resources. Combined with Service Workers, this enables sophisticated caching strategies including offline support, background sync, and custom cache logic.

The Cache Storage API:

The Cache Storage API provides a programmatic interface for storing Request/Response pairs. Unlike the HTTP cache, you have complete control over what gets cached, when, and for how long.

cache-storage-basics.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Opening a named cache
const cache = await caches.open('my-app-v1');
 
// Adding resources to cache
await cache.add('/styles/main.css');  // Fetches and caches
await cache.addAll([                  // Batch add
  '/scripts/app.js',
  '/images/logo.png',
  '/fonts/inter.woff2'
]);
 
// Manually caching a Response
const response = await fetch('/api/config');
await cache.put('/api/config', response.clone());
 
// Retrieving from cache
const cachedResponse = await cache.match('/styles/main.css');
if (cachedResponse) {
  console.log('Cache hit!');
  return cachedResponse;
}
 
// Deleting cache entries
await cache.delete('/api/config');
 
// Listing all caches
const cacheNames = await caches.keys();
// ['my-app-v1', 'my-app-v2']
 
// Deleting old caches during update
const currentCaches = ['my-app-v2'];
for (const name of await caches.keys()) {
  if (!currentCaches.includes(name)) {
    await caches.delete(name);
  }
}

Service Workers as Cache Controllers:

Service Workers act as a programmable network proxy between your application and the network. They intercept all network requests, allowing you to implement custom caching strategies:

Cache-first — Check cache, fall back to network
Network-first — Try network, fall back to cache
Stale-while-revalidate — Serve from cache immediately, update in background
Cache-only — Never go to network (offline mode)
Network-only — Never use cache (always fresh)

service-worker-strategies.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
// service-worker.js
 
const CACHE_NAME = 'my-app-v2';
const STATIC_ASSETS = [
  '/',
  '/styles/main.css',
  '/scripts/app.js',
  '/images/logo.png'
];
 
// Install: Pre-cache static assets
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(STATIC_ASSETS))
      .then(() => self.skipWaiting())
  );
});
 
// Activate: Clean up old caches
self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(names => 
      Promise.all(
        names
          .filter(name => name !== CACHE_NAME)
          .map(name => caches.delete(name))
      )
    ).then(() => self.clients.claim())
  );
});
 
// Fetch: Implement caching strategies
self.addEventListener('fetch', event => {
  const { request } = event;
  const url = new URL(request.url);
  
  // Strategy 1: Cache-first for static assets
  if (request.destination === 'image' || 
      request.destination === 'font' ||
      url.pathname.match(/\.(css|js)$/)) {
    event.respondWith(cacheFirst(request));
    return;
  }
  
  // Strategy 2: Network-first for API calls
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(networkFirst(request));
    return;
  }
  
  // Strategy 3: Stale-while-revalidate for HTML pages
  event.respondWith(staleWhileRevalidate(request));
});
 
// Cache-first strategy
async function cacheFirst(request) {
  const cached = await caches.match(request);
  if (cached) return cached;
  
  const response = await fetch(request);
  if (response.ok) {
    const cache = await caches.open(CACHE_NAME);
    cache.put(request, response.clone());
  }
  return response;
}
 
// Network-first strategy
async function networkFirst(request) {
  try {
    const response = await fetch(request);
    if (response.ok) {
      const cache = await caches.open(CACHE_NAME);
      cache.put(request, response.clone());
    }
    return response;
  } catch (error) {
    const cached = await caches.match(request);
    if (cached) return cached;
    throw error;
  }
}
 
// Stale-while-revalidate strategy
async function staleWhileRevalidate(request) {
  const cached = await caches.match(request);
  
  const fetchPromise = fetch(request).then(response => {
    if (response.ok) {
      const cache = caches.open(CACHE_NAME);
      cache.then(c => c.put(request, response.clone()));
    }
    return response;
  });
  
  return cached || fetchPromise;
}

Service Worker Lifecycle Complexity

Service Workers have a complex lifecycle (install → waiting → activate) and update semantics. A new Service Worker won't take control until all tabs using the old version are closed, unless you call skipWaiting()/clients.claim(). Test thoroughly in development, and consider using libraries like Workbox that handle edge cases.

IndexedDB for Large Data Caching

While the Cache Storage API is optimized for Request/Response pairs, applications often need to cache structured data—user preferences, application state, offline-capable datasets. IndexedDB provides a low-level NoSQL database in the browser, suitable for storing significant amounts of structured data.

When to Use IndexedDB vs. Cache Storage:

Use Case	Best Storage	Reasoning
HTTP responses (HTML, CSS, JS, images)	Cache Storage	Native Request/Response pairing
JSON API responses for offline use	Cache Storage	Still HTTP responses
Transformed/processed data	IndexedDB	Not raw responses
User-generated content	IndexedDB	Not fetched resources
Large datasets (>50MB)	IndexedDB	Higher storage quota
Complex queries needed	IndexedDB	Indexed lookups
Simple key-value storage	localStorage/IndexedDB	Depends on size

indexeddb-caching.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
// IndexedDB wrapper for caching structured data
class CacheDB {
  constructor(dbName = 'app-cache', version = 1) {
    this.dbName = dbName;
    this.version = version;
    this.db = null;
  }
 
  async open() {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open(this.dbName, this.version);
      
      request.onerror = () => reject(request.error);
      request.onsuccess = () => {
        this.db = request.result;
        resolve(this.db);
      };
      
      request.onupgradeneeded = (event) => {
        const db = event.target.result;
        
        // Create object stores with indexes
        if (!db.objectStoreNames.contains('dataCache')) {
          const store = db.createObjectStore('dataCache', { keyPath: 'key' });
          store.createIndex('timestamp', 'timestamp');
          store.createIndex('category', 'category');
        }
      };
    });
  }
 
  async set(key, value, category = 'default', ttlSeconds = 3600) {
    const db = this.db || await this.open();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readwrite');
      const store = transaction.objectStore('dataCache');
      
      const entry = {
        key,
        value,
        category,
        timestamp: Date.now(),
        expires: Date.now() + (ttlSeconds * 1000)
      };
      
      const request = store.put(entry);
      request.onsuccess = () => resolve(true);
      request.onerror = () => reject(request.error);
    });
  }
 
  async get(key) {
    const db = this.db || await this.open();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readonly');
      const store = transaction.objectStore('dataCache');
      const request = store.get(key);
      
      request.onsuccess = () => {
        const entry = request.result;
        
        // Check expiration
        if (!entry) {
          resolve(null);
        } else if (entry.expires < Date.now()) {
          this.delete(key);  // Clean up expired entry
          resolve(null);
        } else {
          resolve(entry.value);
        }
      };
      request.onerror = () => reject(request.error);
    });
  }
 
  async delete(key) {
    const db = this.db || await this.open();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readwrite');
      const store = transaction.objectStore('dataCache');
      const request = store.delete(key);
      
      request.onsuccess = () => resolve(true);
      request.onerror = () => reject(request.error);
    });
  }
 
  async clearExpired() {
    const db = this.db || await this.open();
    const now = Date.now();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readwrite');
      const store = transaction.objectStore('dataCache');
      const index = store.index('timestamp');
      const request = index.openCursor();
      let deleted = 0;
      
      request.onsuccess = (event) => {
        const cursor = event.target.result;
        if (cursor) {
          if (cursor.value.expires < now) {
            cursor.delete();
            deleted++;
          }
          cursor.continue();
        } else {
          resolve(deleted);
        }
      };
      request.onerror = () => reject(request.error);
    });
  }
}
 
// Usage example
const cache = new CacheDB();
 
// Cache user profile for 1 hour
await cache.set('user:12345', { 
  name: 'John Doe', 
  preferences: { theme: 'dark' } 
}, 'users', 3600);
 
// Retrieve from cache
const profile = await cache.get('user:12345');
 
// Periodic cleanup of expired entries
setInterval(() => cache.clearExpired(), 60000);

Storage Quotas

Browser storage quotas vary but typically allow hundreds of megabytes to several gigabytes per origin. Use navigator.storage.estimate() to check available space. For persistent storage that survives browser cleanup, request permission via navigator.storage.persist(). Without persistence, browsers may evict data under storage pressure.

Caching Strategy by Resource Type

Different resource types have different caching requirements based on their volatility, size, and importance. A well-designed caching strategy applies different policies to different resource categories.

The Framework for Deciding Caching Policy:

How often does this change? — Ranging from 'never' (versioned assets) to 'every request' (user-specific data)
How bad is serving stale content? — From 'imperceptible' (old logo) to 'catastrophic' (stale financial data)
How expensive is a cache miss? — Size of resource, origin server load, user-perceived latency
Who can see this content? — Public (cacheable by CDNs) vs. private (browser-only)

Resource-Specific Caching Strategies
Resource Type	Typical Volatility	Recommended Headers	Rationale
Versioned JS/CSS (with hash)	Never changes	public, max-age=31536000, immutable	File hash changes with content, cache forever
Fonts	Rarely	public, max-age=31536000	Fonts rarely change, large files
Images with hash	Never changes	public, max-age=31536000, immutable	Same as versioned assets
Images without hash	Occasionally	public, max-age=86400, stale-while-revalidate=604800	Cache a day, serve stale while validating
HTML pages	Frequently	no-cache or max-age=0, must-revalidate	Always validate freshness
API responses (public)	Varies	public, max-age=60, stale-while-revalidate=300	Short freshness, acceptable staleness
API responses (private)	Varies	private, max-age=300	Browser-only cache, moderate freshness
User-specific data	Per request	private, no-cache or no-store	Validate or don't cache at all
Sensitive data	N/A	no-store	Never store anywhere

nginx-caching-config.conf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# Comprehensive browser caching configuration
 
server {
    listen 443 ssl http2;
    server_name example.com;
    
    # Versioned static assets - cache forever
    location ~* \.(?:css|js)$ {
        # Files like: styles.a7b3c9f.css, bundle.8d4e2a1.js
        if ($uri ~* "\.[a-f0-9]{8}\.(css|js)$") {
            add_header Cache-Control "public, max-age=31536000, immutable";
            break;
        }
        # Unversioned files - shorter cache with revalidation
        add_header Cache-Control "public, max-age=86400, stale-while-revalidate=604800";
    }
    
    # Images - long cache for versioned, medium for others
    location ~* \.(?:jpg|jpeg|png|gif|webp|avif|svg|ico)$ {
        if ($uri ~* "\.[a-f0-9]{8}\.") {
            add_header Cache-Control "public, max-age=31536000, immutable";
            break;
        }
        add_header Cache-Control "public, max-age=604800, stale-while-revalidate=2592000";
    }
    
    # Fonts - long cache
    location ~* \.(?:woff|woff2|ttf|otf|eot)$ {
        add_header Cache-Control "public, max-age=31536000";
        add_header Access-Control-Allow-Origin "*";
    }
    
    # HTML pages - always revalidate
    location ~* \.html$ {
        add_header Cache-Control "no-cache";
        add_header ETag $upstream_http_etag;
    }
    
    # Root document
    location = / {
        add_header Cache-Control "no-cache";
    }
    
    # API proxy - private caching for authenticated endpoints
    location /api/ {
        proxy_pass http://api_backend;
        
        # Let application set Cache-Control
        proxy_hide_header Cache-Control;
        add_header Cache-Control $sent_http_cache_control;
        
        # Add validation headers if not present
        add_header ETag $upstream_http_etag;
        add_header Last-Modified $upstream_http_last_modified;
    }
}

The Immutable Directive

The 'immutable' directive tells browsers to skip revalidation even on explicit refresh (F5). It's perfect for content-hashed assets where the URL changes when content changes. Without it, browsers may revalidate on refresh despite long max-age, wasting bandwidth.

Cache Busting Techniques

Long-lived caches for static assets create a challenge: how do you ensure users get updated content when you deploy changes? Cache busting refers to techniques that force browsers to download new versions of cached resources.

The Core Challenge:

If you cache styles.css for one year and then deploy an update, users will continue seeing the old version until their cache expires. You need a mechanism to signal "this is a new version, fetch it fresh."

Cache Busting Strategies:

Cache Busting Approaches

•Content Hash in Filename — bundle.a7b3c9d.js — Hash changes when content changes. Best approach for most scenarios.
•Query Parameter Version — bundle.js?v=1.2.3 — Simple but some proxies/CDNs ignore query strings for caching.
•Directory Versioning — /v1.2.3/bundle.js — Clean URLs but requires path changes throughout application.
•Build Timestamp — bundle.js?t=1704067200 — Changes every build, even without content changes (wasteful).
•Manifest File — Map logical names to hashed versions — Enables long-term caching with reliable updates.

webpack-content-hash.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// webpack.config.js - Content hash configuration
module.exports = {
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
    assetModuleFilename: 'assets/[hash][ext]',
    clean: true,  // Clean output directory on each build
  },
  
  optimization: {
    moduleIds: 'deterministic',  // Stable module IDs across builds
    runtimeChunk: 'single',      // Separate runtime for better caching
    splitChunks: {
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all',
          // Vendor bundle only changes when dependencies update
        },
      },
    },
  },
  
  plugins: [
    // Generate manifest mapping logical names to hashed filenames
    new WebpackManifestPlugin({
      fileName: 'asset-manifest.json',
      publicPath: '/',
      generate: (seed, files, entrypoints) => {
        const manifest = {};
        for (const file of files) {
          manifest[file.name] = file.path;
        }
        return manifest;
      },
    }),
  ],
};
 
/*
Generated asset-manifest.json:
{
  "main.js": "/main.a7b3c9d.js",
  "main.css": "/main.8f2e1b4.css",
  "vendors.js": "/vendors.c3d4e5f.js",
  "runtime.js": "/runtime.1a2b3c4.js"
}
 
HTML template uses manifest to reference correct files:
<script src="{{ manifest['runtime.js'] }}"></script>
<script src="{{ manifest['vendors.js'] }}"></script>
<script src="{{ manifest['main.js'] }}"></script>
*/

Why Content Hashing is Superior:

Approach	Hash Changes	Cache Efficiency	Implementation	Proxy Compatible
Content hash in filename	Only when content changes	Optimal	Build tool required	Yes
Query parameter	When manually updated	Good	Simple	Sometimes
Timestamp	Every build	Poor (invalidates unchanged files)	Simple	Sometimes

Content hashing ensures that:

Unchanged files keep the same URL, preserving cache
Changed files get new URLs, forcing re-download
Users always get consistent versions (no partial updates)

The HTML Exception

You cannot content-hash your root HTML document—browsers request it by a fixed URL. This is why HTML should use no-cache: to always fetch the latest HTML, which then references the correct hashed assets. The HTML acts as the 'entry point manifest' for your cached assets.

Debugging Browser Cache Issues

Cache-related bugs are notoriously difficult to diagnose because they often manifest inconsistently—working for some users, failing for others, or appearing to fix themselves after repeated refreshes. Systematic debugging requires understanding both the tools available and the common failure modes.

Browser DevTools for Cache Debugging:

DevTools Cache Investigation

•Network Panel — Check the 'Size' column for '(disk cache)' or '(memory cache)' indicating cache hits. The '(from ServiceWorker)' indicates Service Worker intervention.
•Disable cache checkbox — In Network panel, enable 'Disable cache' to force fresh fetches during debugging. Remember to disable when testing actual caching behavior.
•Response Headers tab — Inspect actual Cache-Control, ETag, Last-Modified headers received from server.
•Application Panel → Cache Storage — View contents of Cache API caches, including all cached Request/Response pairs.
•Application Panel → Storage — View and clear IndexedDB, localStorage, cookies, and other storage.
•Clear Storage — Application → Storage → Clear storage to wipe all cached data for the origin.
•Preserve log — Enable in Network panel to see requests across page navigations.

cache-debugging-console.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// Console commands for cache debugging
 
// Check what's in Cache Storage
async function inspectCacheStorage() {
  const cacheNames = await caches.keys();
  console.log('Available caches:', cacheNames);
  
  for (const name of cacheNames) {
    const cache = await caches.open(name);
    const keys = await cache.keys();
    console.log(`\n📦 Cache "${name}" (${keys.length} entries):`);
    
    for (const request of keys.slice(0, 10)) {  // First 10
      const response = await cache.match(request);
      console.log(`  ${request.url} → ${response.status}`);
    }
    if (keys.length > 10) {
      console.log(`  ... and ${keys.length - 10} more`);
    }
  }
}
 
// Check storage quota
async function checkStorageQuota() {
  if ('storage' in navigator && 'estimate' in navigator.storage) {
    const estimate = await navigator.storage.estimate();
    console.log(`Storage quota: ${(estimate.quota / 1024 / 1024).toFixed(2)} MB`);
    console.log(`Storage used: ${(estimate.usage / 1024 / 1024).toFixed(2)} MB`);
    console.log(`Available: ${((estimate.quota - estimate.usage) / 1024 / 1024).toFixed(2)} MB`);
  }
}
 
// Force clear all caches
async function clearAllCaches() {
  const cacheNames = await caches.keys();
  await Promise.all(cacheNames.map(name => caches.delete(name)));
  console.log(`Cleared ${cacheNames.length} caches`);
}
 
// Check Service Worker status
function checkServiceWorker() {
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.getRegistrations().then(registrations => {
      console.log('Service Worker registrations:', registrations.length);
      registrations.forEach(reg => {
        console.log(`  Scope: ${reg.scope}`);
        console.log(`  Active: ${reg.active?.state}`);
        console.log(`  Waiting: ${reg.waiting?.state}`);
      });
    });
  }
}
 
// Run all diagnostics
async function cacheDiagnostics() {
  console.log('=== Cache Diagnostics ===');
  await checkStorageQuota();
  await inspectCacheStorage();
  checkServiceWorker();
}

Common Cache Problems and Solutions
Symptom	Likely Cause	Solution
Users see old content after deploy	Long max-age without cache busting	Implement content hashing; use no-cache for HTML
Inconsistent behavior across users	Different cached versions	Ensure consistent cache headers; clear CDN
Changes not appearing after hard refresh	Service Worker serving cached version	Update SW version trigger; skipWaiting()
Private content cached publicly	Missing private directive	Add private directive; audit CDN config
304 responses when expecting 200	Conditional request matching stale ETag	Clear cache; verify ETag generation
Always fetching despite cache config	no-store from proxy or misconfigured CDN	Audit headers at each layer

The curl Verification Technique

Use curl -I <url> to inspect response headers without browser interference. Compare these headers with what DevTools shows to identify if any proxy, CDN, or browser extension is modifying headers in transit.

Summary and Best Practices

Browser caching is the most impactful layer in the caching hierarchy—every cache hit eliminates all network overhead. Mastering browser caching requires understanding HTTP cache semantics, leveraging the Cache Storage API for programmatic control, and applying appropriate strategies for different resource types.

Browser Caching Best Practices

•Use content hashing for static assets — Enables year-long caching with reliable invalidation when content changes.
•Apply immutable to hashed assets — Prevents unnecessary revalidation on refresh for content that, by definition, never changes.
•Use no-cache for HTML documents — Always validates freshness, ensuring users get the latest asset references.
•Never use no-store unless truly necessary — Reserve for sensitive data; it completely defeats caching.
•Provide both ETag and Last-Modified — Enables efficient conditional requests with fallback options.
•Use stale-while-revalidate for acceptable staleness — Improves perceived performance by serving immediately.
•Leverage Service Workers for complex caching — Enables offline support and fine-grained cache control.
•Test cache behavior explicitly — Use DevTools, curl, and multiple browsers to verify caching works as intended.
•Consider the full caching chain — Browser → CDN → Origin each layer affects effective caching.
•Document your caching strategy — Future developers (including yourself) will need to understand the design decisions.

What's Next:

Browser caching is just the first layer in the caching hierarchy. The next page explores CDN caching (edge caching), where we'll examine how geographically distributed edge servers cache content closer to users, dramatically reducing latency for global audiences and offloading traffic from origin servers.

Page Complete

You now understand client-side browser caching—from HTTP Cache-Control semantics to Service Worker strategies. You can design caching policies that maximize performance while maintaining content freshness, debug cache-related issues systematically, and implement cache busting for reliable deployments.

1 / 5

Loading learning content...

System Design (HLD)Caching Strategies

Caching Layers

LevelIntermediate

Duration90 mins

TopicCaching Strategies

1 / 5

Client-Side Caching (Browser)

The First Line of Defense

What You Will Learn

Understanding the Browser Cache

The Cache Lookup Process:

When a browser encounters a resource request (whether from HTML parsing, JavaScript execution, or user navigation), it follows a well-defined process:

Construct the cache key — Typically the full URL including query parameters
Check for a cached response — Look up the key in the local cache store
Evaluate freshness — If found, determine whether the cached response is still valid
Serve or revalidate — Either serve directly from cache or validate with the origin server
Store new responses — If a network request is made, potentially cache the response

Browser Cache Behavior Based on Response Headers
Scenario	Cache Behavior	Network Request?	User Perception
Fresh cache hit	Serve from disk/memory cache	No	Instantaneous load (<10ms)
Stale with validation	Conditional request to server	Yes (small)	Fast if 304 Not Modified
Stale without etag/last-modified	Full request to server	Yes (full)	Normal load time
No-cache directive	Always validate before serving	Yes (small)	Slight delay for validation
No-store directive	Never cache this response	Yes (full)	Full load time every time

Memory Cache vs. Disk Cache:

Modern browsers maintain two-tier caching:

Memory cache — Extremely fast access (< 1ms), limited capacity, cleared on browser close. Used for resources likely to be needed again soon during the same session.
Disk cache — Slower access (5-20ms), much larger capacity, persists across sessions. Used for resources with longer lifetimes.

Cache Key Considerations

HTTP Cache-Control Directives

Understanding the Directive Categories:

Cache-Control directives fall into several functional categories:

Cacheability — Whether a response can be cached at all
Expiration — How long a cached response remains fresh
Revalidation — When and how stale responses must be revalidated
Other directives — Special behaviors for specific scenarios

Cache-Control Directive Reference
Directive	Category	Meaning	Common Use Case
public	Cacheability	Response can be cached by any cache (browser, CDN, proxy)	Static assets, public API responses
private	Cacheability	Response can only be cached by browser, not shared caches	Personalized content, authenticated responses
no-cache	Revalidation	Cache can store but must revalidate before each use	Always-fresh content (HTML pages)
no-store	Cacheability	Never store this response anywhere	Sensitive data, credit card forms
max-age=N	Expiration	Response is fresh for N seconds from request time	Static assets with known update frequency
s-maxage=N	Expiration	Override max-age for shared caches (CDN/proxy)	Different browser vs CDN expiration
must-revalidate	Revalidation	Once stale, must revalidate—cannot use stale copy	Critical data that must never be stale
stale-while-revalidate=N	Revalidation	Can serve stale for N seconds while revalidating in background	Non-critical content where freshness can lag
stale-if-error=N	Revalidation	Can serve stale for N seconds if revalidation fails	Graceful degradation during outages
immutable	Expiration	Response will never change—skip revalidation even on refresh	Versioned static assets (hash in filename)

Cache-Control Header Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Static asset with content-hash in filename - cache forever
Cache-Control: public, max-age=31536000, immutable
 
# HTML page that should always be fresh
Cache-Control: no-cache
 
# Authenticated API response - browser-only caching for 5 minutes
Cache-Control: private, max-age=300
 
# Public API that can lag slightly - serve stale while fetching fresh
Cache-Control: public, max-age=60, stale-while-revalidate=300
 
# Sensitive data that should never be stored
Cache-Control: no-store
 
# CDN caches for 1 hour, browsers cache for 5 minutes
Cache-Control: public, max-age=300, s-maxage=3600
 
# Critical data - must revalidate when stale, allow stale during errors
Cache-Control: max-age=300, must-revalidate, stale-if-error=86400

Common Misconception: no-cache vs no-store

Validation and Conditional Requests

Two Validation Mechanisms:

HTTP provides two complementary approaches for cache validation:

ETag Validation

•Server provides ETag — An opaque identifier for the specific version of a resource
•Browser stores ETag — Cached alongside the response body
•Conditional request — Browser sends If-None-Match: <etag> header
•Server comparison — Compares provided ETag with current resource version
•Response — 304 if match (use cache), 200 with new content if changed

Last-Modified Validation

•Server provides Last-Modified — Timestamp of last resource change
•Browser stores timestamp — Cached alongside the response
•Conditional request — Browser sends If-Modified-Since: <date> header
•Server comparison — Checks if resource changed after provided date
•Response — 304 if unchanged, 200 with new content if modified

Conditional Request Flow
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
# Initial Response from Server
HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: max-age=300
ETag: "abc123def456"
Last-Modified: Wed, 15 Jan 2025 10:30:00 GMT
 
<script content>
 
# ----------------------------------------
 
# Conditional Request (after 300 seconds)
GET /bundle.js HTTP/1.1
Host: example.com
If-None-Match: "abc123def456"
If-Modified-Since: Wed, 15 Jan 2025 10:30:00 GMT
 
# ----------------------------------------
 
# Response if unchanged (bandwidth savings!)
HTTP/1.1 304 Not Modified
ETag: "abc123def456"
Cache-Control: max-age=300
 
# No body - browser uses cached version
 
# ----------------------------------------
 
# Response if changed
HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: max-age=300
ETag: "xyz789new123"
Last-Modified: Thu, 16 Jan 2025 14:20:00 GMT
 
<new script content>

Choosing Between ETag and Last-Modified:

Factor	ETag	Last-Modified
Precision	Byte-exact (if strong ETag)	1-second resolution
Computation	Requires hash calculation	Just file timestamp
Distributed systems	Must coordinate ETag generation	Timestamps can vary across servers
Best for	API responses, dynamically generated content	Static files served from disk

Strong vs. Weak ETags:

Validation Best Practice

Cache Storage API and Service Workers

The Cache Storage API:

The Cache Storage API provides a programmatic interface for storing Request/Response pairs. Unlike the HTTP cache, you have complete control over what gets cached, when, and for how long.

cache-storage-basics.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Opening a named cache
const cache = await caches.open('my-app-v1');
 
// Adding resources to cache
await cache.add('/styles/main.css');  // Fetches and caches
await cache.addAll([                  // Batch add
  '/scripts/app.js',
  '/images/logo.png',
  '/fonts/inter.woff2'
]);
 
// Manually caching a Response
const response = await fetch('/api/config');
await cache.put('/api/config', response.clone());
 
// Retrieving from cache
const cachedResponse = await cache.match('/styles/main.css');
if (cachedResponse) {
  console.log('Cache hit!');
  return cachedResponse;
}
 
// Deleting cache entries
await cache.delete('/api/config');
 
// Listing all caches
const cacheNames = await caches.keys();
// ['my-app-v1', 'my-app-v2']
 
// Deleting old caches during update
const currentCaches = ['my-app-v2'];
for (const name of await caches.keys()) {
  if (!currentCaches.includes(name)) {
    await caches.delete(name);
  }
}

Service Workers as Cache Controllers:

Service Workers act as a programmable network proxy between your application and the network. They intercept all network requests, allowing you to implement custom caching strategies:

Cache-first — Check cache, fall back to network
Network-first — Try network, fall back to cache
Stale-while-revalidate — Serve from cache immediately, update in background
Cache-only — Never go to network (offline mode)
Network-only — Never use cache (always fresh)

service-worker-strategies.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
// service-worker.js
 
const CACHE_NAME = 'my-app-v2';
const STATIC_ASSETS = [
  '/',
  '/styles/main.css',
  '/scripts/app.js',
  '/images/logo.png'
];
 
// Install: Pre-cache static assets
self.addEventListener('install', event => {
  event.waitUntil(
    caches.open(CACHE_NAME)
      .then(cache => cache.addAll(STATIC_ASSETS))
      .then(() => self.skipWaiting())
  );
});
 
// Activate: Clean up old caches
self.addEventListener('activate', event => {
  event.waitUntil(
    caches.keys().then(names => 
      Promise.all(
        names
          .filter(name => name !== CACHE_NAME)
          .map(name => caches.delete(name))
      )
    ).then(() => self.clients.claim())
  );
});
 
// Fetch: Implement caching strategies
self.addEventListener('fetch', event => {
  const { request } = event;
  const url = new URL(request.url);
  
  // Strategy 1: Cache-first for static assets
  if (request.destination === 'image' || 
      request.destination === 'font' ||
      url.pathname.match(/\.(css|js)$/)) {
    event.respondWith(cacheFirst(request));
    return;
  }
  
  // Strategy 2: Network-first for API calls
  if (url.pathname.startsWith('/api/')) {
    event.respondWith(networkFirst(request));
    return;
  }
  
  // Strategy 3: Stale-while-revalidate for HTML pages
  event.respondWith(staleWhileRevalidate(request));
});
 
// Cache-first strategy
async function cacheFirst(request) {
  const cached = await caches.match(request);
  if (cached) return cached;
  
  const response = await fetch(request);
  if (response.ok) {
    const cache = await caches.open(CACHE_NAME);
    cache.put(request, response.clone());
  }
  return response;
}
 
// Network-first strategy
async function networkFirst(request) {
  try {
    const response = await fetch(request);
    if (response.ok) {
      const cache = await caches.open(CACHE_NAME);
      cache.put(request, response.clone());
    }
    return response;
  } catch (error) {
    const cached = await caches.match(request);
    if (cached) return cached;
    throw error;
  }
}
 
// Stale-while-revalidate strategy
async function staleWhileRevalidate(request) {
  const cached = await caches.match(request);
  
  const fetchPromise = fetch(request).then(response => {
    if (response.ok) {
      const cache = caches.open(CACHE_NAME);
      cache.then(c => c.put(request, response.clone()));
    }
    return response;
  });
  
  return cached || fetchPromise;
}

Service Worker Lifecycle Complexity

IndexedDB for Large Data Caching

When to Use IndexedDB vs. Cache Storage:

Use Case	Best Storage	Reasoning
HTTP responses (HTML, CSS, JS, images)	Cache Storage	Native Request/Response pairing
JSON API responses for offline use	Cache Storage	Still HTTP responses
Transformed/processed data	IndexedDB	Not raw responses
User-generated content	IndexedDB	Not fetched resources
Large datasets (>50MB)	IndexedDB	Higher storage quota
Complex queries needed	IndexedDB	Indexed lookups
Simple key-value storage	localStorage/IndexedDB	Depends on size

indexeddb-caching.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
// IndexedDB wrapper for caching structured data
class CacheDB {
  constructor(dbName = 'app-cache', version = 1) {
    this.dbName = dbName;
    this.version = version;
    this.db = null;
  }
 
  async open() {
    return new Promise((resolve, reject) => {
      const request = indexedDB.open(this.dbName, this.version);
      
      request.onerror = () => reject(request.error);
      request.onsuccess = () => {
        this.db = request.result;
        resolve(this.db);
      };
      
      request.onupgradeneeded = (event) => {
        const db = event.target.result;
        
        // Create object stores with indexes
        if (!db.objectStoreNames.contains('dataCache')) {
          const store = db.createObjectStore('dataCache', { keyPath: 'key' });
          store.createIndex('timestamp', 'timestamp');
          store.createIndex('category', 'category');
        }
      };
    });
  }
 
  async set(key, value, category = 'default', ttlSeconds = 3600) {
    const db = this.db || await this.open();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readwrite');
      const store = transaction.objectStore('dataCache');
      
      const entry = {
        key,
        value,
        category,
        timestamp: Date.now(),
        expires: Date.now() + (ttlSeconds * 1000)
      };
      
      const request = store.put(entry);
      request.onsuccess = () => resolve(true);
      request.onerror = () => reject(request.error);
    });
  }
 
  async get(key) {
    const db = this.db || await this.open();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readonly');
      const store = transaction.objectStore('dataCache');
      const request = store.get(key);
      
      request.onsuccess = () => {
        const entry = request.result;
        
        // Check expiration
        if (!entry) {
          resolve(null);
        } else if (entry.expires < Date.now()) {
          this.delete(key);  // Clean up expired entry
          resolve(null);
        } else {
          resolve(entry.value);
        }
      };
      request.onerror = () => reject(request.error);
    });
  }
 
  async delete(key) {
    const db = this.db || await this.open();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readwrite');
      const store = transaction.objectStore('dataCache');
      const request = store.delete(key);
      
      request.onsuccess = () => resolve(true);
      request.onerror = () => reject(request.error);
    });
  }
 
  async clearExpired() {
    const db = this.db || await this.open();
    const now = Date.now();
    
    return new Promise((resolve, reject) => {
      const transaction = db.transaction(['dataCache'], 'readwrite');
      const store = transaction.objectStore('dataCache');
      const index = store.index('timestamp');
      const request = index.openCursor();
      let deleted = 0;
      
      request.onsuccess = (event) => {
        const cursor = event.target.result;
        if (cursor) {
          if (cursor.value.expires < now) {
            cursor.delete();
            deleted++;
          }
          cursor.continue();
        } else {
          resolve(deleted);
        }
      };
      request.onerror = () => reject(request.error);
    });
  }
}
 
// Usage example
const cache = new CacheDB();
 
// Cache user profile for 1 hour
await cache.set('user:12345', { 
  name: 'John Doe', 
  preferences: { theme: 'dark' } 
}, 'users', 3600);
 
// Retrieve from cache
const profile = await cache.get('user:12345');
 
// Periodic cleanup of expired entries
setInterval(() => cache.clearExpired(), 60000);

Storage Quotas

Caching Strategy by Resource Type

The Framework for Deciding Caching Policy:

How often does this change? — Ranging from 'never' (versioned assets) to 'every request' (user-specific data)
How bad is serving stale content? — From 'imperceptible' (old logo) to 'catastrophic' (stale financial data)
How expensive is a cache miss? — Size of resource, origin server load, user-perceived latency
Who can see this content? — Public (cacheable by CDNs) vs. private (browser-only)

Resource-Specific Caching Strategies
Resource Type	Typical Volatility	Recommended Headers	Rationale
Versioned JS/CSS (with hash)	Never changes	public, max-age=31536000, immutable	File hash changes with content, cache forever
Fonts	Rarely	public, max-age=31536000	Fonts rarely change, large files
Images with hash	Never changes	public, max-age=31536000, immutable	Same as versioned assets
Images without hash	Occasionally	public, max-age=86400, stale-while-revalidate=604800	Cache a day, serve stale while validating
HTML pages	Frequently	no-cache or max-age=0, must-revalidate	Always validate freshness
API responses (public)	Varies	public, max-age=60, stale-while-revalidate=300	Short freshness, acceptable staleness
API responses (private)	Varies	private, max-age=300	Browser-only cache, moderate freshness
User-specific data	Per request	private, no-cache or no-store	Validate or don't cache at all
Sensitive data	N/A	no-store	Never store anywhere

nginx-caching-config.conf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
# Comprehensive browser caching configuration
 
server {
    listen 443 ssl http2;
    server_name example.com;
    
    # Versioned static assets - cache forever
    location ~* \.(?:css|js)$ {
        # Files like: styles.a7b3c9f.css, bundle.8d4e2a1.js
        if ($uri ~* "\.[a-f0-9]{8}\.(css|js)$") {
            add_header Cache-Control "public, max-age=31536000, immutable";
            break;
        }
        # Unversioned files - shorter cache with revalidation
        add_header Cache-Control "public, max-age=86400, stale-while-revalidate=604800";
    }
    
    # Images - long cache for versioned, medium for others
    location ~* \.(?:jpg|jpeg|png|gif|webp|avif|svg|ico)$ {
        if ($uri ~* "\.[a-f0-9]{8}\.") {
            add_header Cache-Control "public, max-age=31536000, immutable";
            break;
        }
        add_header Cache-Control "public, max-age=604800, stale-while-revalidate=2592000";
    }
    
    # Fonts - long cache
    location ~* \.(?:woff|woff2|ttf|otf|eot)$ {
        add_header Cache-Control "public, max-age=31536000";
        add_header Access-Control-Allow-Origin "*";
    }
    
    # HTML pages - always revalidate
    location ~* \.html$ {
        add_header Cache-Control "no-cache";
        add_header ETag $upstream_http_etag;
    }
    
    # Root document
    location = / {
        add_header Cache-Control "no-cache";
    }
    
    # API proxy - private caching for authenticated endpoints
    location /api/ {
        proxy_pass http://api_backend;
        
        # Let application set Cache-Control
        proxy_hide_header Cache-Control;
        add_header Cache-Control $sent_http_cache_control;
        
        # Add validation headers if not present
        add_header ETag $upstream_http_etag;
        add_header Last-Modified $upstream_http_last_modified;
    }
}

The Immutable Directive

Cache Busting Techniques

The Core Challenge:

Cache Busting Strategies:

Cache Busting Approaches

•Content Hash in Filename — bundle.a7b3c9d.js — Hash changes when content changes. Best approach for most scenarios.
•Query Parameter Version — bundle.js?v=1.2.3 — Simple but some proxies/CDNs ignore query strings for caching.
•Directory Versioning — /v1.2.3/bundle.js — Clean URLs but requires path changes throughout application.
•Build Timestamp — bundle.js?t=1704067200 — Changes every build, even without content changes (wasteful).
•Manifest File — Map logical names to hashed versions — Enables long-term caching with reliable updates.

webpack-content-hash.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// webpack.config.js - Content hash configuration
module.exports = {
  output: {
    filename: '[name].[contenthash].js',
    chunkFilename: '[name].[contenthash].chunk.js',
    assetModuleFilename: 'assets/[hash][ext]',
    clean: true,  // Clean output directory on each build
  },
  
  optimization: {
    moduleIds: 'deterministic',  // Stable module IDs across builds
    runtimeChunk: 'single',      // Separate runtime for better caching
    splitChunks: {
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendors',
          chunks: 'all',
          // Vendor bundle only changes when dependencies update
        },
      },
    },
  },
  
  plugins: [
    // Generate manifest mapping logical names to hashed filenames
    new WebpackManifestPlugin({
      fileName: 'asset-manifest.json',
      publicPath: '/',
      generate: (seed, files, entrypoints) => {
        const manifest = {};
        for (const file of files) {
          manifest[file.name] = file.path;
        }
        return manifest;
      },
    }),
  ],
};
 
/*
Generated asset-manifest.json:
{
  "main.js": "/main.a7b3c9d.js",
  "main.css": "/main.8f2e1b4.css",
  "vendors.js": "/vendors.c3d4e5f.js",
  "runtime.js": "/runtime.1a2b3c4.js"
}
 
HTML template uses manifest to reference correct files:
<script src="{{ manifest['runtime.js'] }}"></script>
<script src="{{ manifest['vendors.js'] }}"></script>
<script src="{{ manifest['main.js'] }}"></script>
*/

Why Content Hashing is Superior:

Approach	Hash Changes	Cache Efficiency	Implementation	Proxy Compatible
Content hash in filename	Only when content changes	Optimal	Build tool required	Yes
Query parameter	When manually updated	Good	Simple	Sometimes
Timestamp	Every build	Poor (invalidates unchanged files)	Simple	Sometimes

Content hashing ensures that:

Unchanged files keep the same URL, preserving cache
Changed files get new URLs, forcing re-download
Users always get consistent versions (no partial updates)

The HTML Exception

Debugging Browser Cache Issues

Browser DevTools for Cache Debugging:

DevTools Cache Investigation

•Network Panel — Check the 'Size' column for '(disk cache)' or '(memory cache)' indicating cache hits. The '(from ServiceWorker)' indicates Service Worker intervention.
•Disable cache checkbox — In Network panel, enable 'Disable cache' to force fresh fetches during debugging. Remember to disable when testing actual caching behavior.
•Response Headers tab — Inspect actual Cache-Control, ETag, Last-Modified headers received from server.
•Application Panel → Cache Storage — View contents of Cache API caches, including all cached Request/Response pairs.
•Application Panel → Storage — View and clear IndexedDB, localStorage, cookies, and other storage.
•Clear Storage — Application → Storage → Clear storage to wipe all cached data for the origin.
•Preserve log — Enable in Network panel to see requests across page navigations.

cache-debugging-console.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// Console commands for cache debugging
 
// Check what's in Cache Storage
async function inspectCacheStorage() {
  const cacheNames = await caches.keys();
  console.log('Available caches:', cacheNames);
  
  for (const name of cacheNames) {
    const cache = await caches.open(name);
    const keys = await cache.keys();
    console.log(`\n📦 Cache "${name}" (${keys.length} entries):`);
    
    for (const request of keys.slice(0, 10)) {  // First 10
      const response = await cache.match(request);
      console.log(`  ${request.url} → ${response.status}`);
    }
    if (keys.length > 10) {
      console.log(`  ... and ${keys.length - 10} more`);
    }
  }
}
 
// Check storage quota
async function checkStorageQuota() {
  if ('storage' in navigator && 'estimate' in navigator.storage) {
    const estimate = await navigator.storage.estimate();
    console.log(`Storage quota: ${(estimate.quota / 1024 / 1024).toFixed(2)} MB`);
    console.log(`Storage used: ${(estimate.usage / 1024 / 1024).toFixed(2)} MB`);
    console.log(`Available: ${((estimate.quota - estimate.usage) / 1024 / 1024).toFixed(2)} MB`);
  }
}
 
// Force clear all caches
async function clearAllCaches() {
  const cacheNames = await caches.keys();
  await Promise.all(cacheNames.map(name => caches.delete(name)));
  console.log(`Cleared ${cacheNames.length} caches`);
}
 
// Check Service Worker status
function checkServiceWorker() {
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.getRegistrations().then(registrations => {
      console.log('Service Worker registrations:', registrations.length);
      registrations.forEach(reg => {
        console.log(`  Scope: ${reg.scope}`);
        console.log(`  Active: ${reg.active?.state}`);
        console.log(`  Waiting: ${reg.waiting?.state}`);
      });
    });
  }
}
 
// Run all diagnostics
async function cacheDiagnostics() {
  console.log('=== Cache Diagnostics ===');
  await checkStorageQuota();
  await inspectCacheStorage();
  checkServiceWorker();
}

Common Cache Problems and Solutions
Symptom	Likely Cause	Solution
Users see old content after deploy	Long max-age without cache busting	Implement content hashing; use no-cache for HTML
Inconsistent behavior across users	Different cached versions	Ensure consistent cache headers; clear CDN
Changes not appearing after hard refresh	Service Worker serving cached version	Update SW version trigger; skipWaiting()
Private content cached publicly	Missing private directive	Add private directive; audit CDN config
304 responses when expecting 200	Conditional request matching stale ETag	Clear cache; verify ETag generation
Always fetching despite cache config	no-store from proxy or misconfigured CDN	Audit headers at each layer

The curl Verification Technique

Summary and Best Practices

Browser Caching Best Practices

•Use content hashing for static assets — Enables year-long caching with reliable invalidation when content changes.
•Apply immutable to hashed assets — Prevents unnecessary revalidation on refresh for content that, by definition, never changes.
•Use no-cache for HTML documents — Always validates freshness, ensuring users get the latest asset references.
•Never use no-store unless truly necessary — Reserve for sensitive data; it completely defeats caching.
•Provide both ETag and Last-Modified — Enables efficient conditional requests with fallback options.
•Use stale-while-revalidate for acceptable staleness — Improves perceived performance by serving immediately.
•Leverage Service Workers for complex caching — Enables offline support and fine-grained cache control.
•Test cache behavior explicitly — Use DevTools, curl, and multiple browsers to verify caching works as intended.
•Consider the full caching chain — Browser → CDN → Origin each layer affects effective caching.
•Document your caching strategy — Future developers (including yourself) will need to understand the design decisions.

What's Next:

Page Complete

1 / 5