Browser Storage & Offline-First State Persistence

When to use Cache API over IndexedDB

Frontend engineers and PWA developers frequently misapply storage architecture by persisting raw network responses (HTML, CSS, JS, images) directly into IndexedDB. This architectural mismatch triggers severe structured-cloning overhead, forces complex key management, and exhausts Browser Storage Fundamentals & Quotas limits prematurely. IndexedDB requires synchronous data serialization, adding unnecessary CPU cycles for binary and text assets. Conversely, the Cache API for Static Assets is purpose-built to intercept HTTP streams, store Request/Response pairs natively, and bypass transformation entirely.

Follow this production-ready migration path to isolate concerns and optimize offline-first performance.

Step 1: Audit & Segregate Payloads

  1. Inventory existing storage: Query indexedDB.databases() and caches.keys() to map current persistence layers.
  2. Migrate fetchable resources: Move all HTML, CSS, JS, fonts, and images to the Cache API.
  3. Isolate state data: Reserve IndexedDB exclusively for structured JSON, user preferences, relational state, and offline transaction logs.

Step 2: Implement Cache API Storage Pattern

Store HTTP streams directly using caches.open() and cache.put(). Handle QuotaExceededError explicitly, as browser cache limits are dynamic and tied to available disk space.

async function cacheNetworkResponse(url) {
 try {
 const cache = await caches.open('app-static-v1');
 const response = await fetch(url);
 
 if (!response.ok) {
 throw new Error(`Fetch failed with HTTP ${response.status}`);
 }

 // Cache API consumes the response body; clone before storing
 // and returning to the caller.
 await cache.put(url, response.clone());
 return response;
 } catch (err) {
 // Handle explicit quota limits or network failures
 if (err.name === 'QuotaExceededError') {
 console.error('Cache quota exceeded. Trigger cleanup routine.');
 // Implement cache eviction strategy here
 } else {
 console.error('Cache API write failed:', err.message);
 }
 throw err;
 }
}

Step 3: Implement IndexedDB State Sync

Isolate application state management. Use native openDB or the idb wrapper for structured data. Never route asset caching through this layer.

async function syncAppState(stateData) {
 try {
 // Assumes 'idb' library or equivalent native wrapper
 const db = await openDB('app-state-db', 1, {
 upgrade(db) {
 if (!db.objectStoreNames.contains('user-prefs')) {
 db.createObjectStore('user-prefs', { keyPath: 'id' });
 }
 }
 });
 
 // Use a transaction for atomic state updates
 const tx = db.transaction('user-prefs', 'readwrite');
 await tx.store.put({ id: 'active-session', ...stateData });
 await tx.done;
 } catch (err) {
 if (err.name === 'QuotaExceededError') {
 console.error('IndexedDB storage limit reached. Purge old sessions.');
 } else {
 console.error('IndexedDB transaction failed:', err.message);
 }
 throw err;
 }
}

Step 4: Service Worker Interception

Route static asset requests to the Cache API first. Implement a network fallback. Keep IndexedDB completely out of the fetch handler to prevent main-thread blocking and serialization delays.

self.addEventListener('fetch', (event) => {
 // Only intercept GET requests for static assets
 if (event.request.method !== 'GET') return;
 
 const isStaticAsset = ['document', 'script', 'style', 'image', 'font', 'manifest'].includes(event.request.destination);
 
 if (isStaticAsset) {
 event.respondWith(
 caches.match(event.request)
 .then(cached => {
 if (cached) return cached;
 return fetch(event.request).then(networkResponse => {
 // Clone and cache successful network responses
 if (networkResponse.ok) {
 const cacheClone = networkResponse.clone();
 caches.open('app-static-v1').then(cache => cache.put(event.request, cacheClone));
 }
 return networkResponse;
 });
 })
 .catch(err => {
 console.warn('Fetch fallback failed:', err.message);
 // Return a valid offline fallback response
 return new Response('Service temporarily offline. Please check your connection.', {
 status: 503,
 statusText: 'Service Unavailable',
 headers: new Headers({ 'Content-Type': 'text/plain' })
 });
 })
 );
 }
});

Validation Checklist