Building PWAs That Actually Work Offline

Resilient PWA Architecture: Decoupling Shell and Data for Unreliable Networks

Current Situation Analysis

Progressive Web Apps (PWAs) promise native-grade reliability, yet many implementations collapse under network stress. The prevailing industry failure mode is treating the service worker as a binary switch rather than a granular caching engine. Developers frequently register a worker and assume offline capability emerges automatically, leading to "frozen" states where the UI hangs waiting for network responses that never arrive.

This problem is often misunderstood because basic PWA checklists emphasize the presence of a manifest.json and a service worker registration over the actual caching logic. The result is a brittle application that performs well on localhost but degrades catastrophically on unstable connections. Evidence from production telemetry shows that monolithic caching strategies cause install failures on slow networks due to payload bloat, while cache-first strategies for dynamic data result in users viewing stale information until a manual refresh occurs. Without a deliberate separation of concerns, PWAs cannot guarantee the perceived performance or offline continuity required for user retention.

WOW Moment: Key Findings

The critical differentiator between a fragile PWA and a resilient one is the architectural decoupling of the App Shell (static UI skeleton) from Dynamic Content (API responses). Implementing distinct caching strategies for these layers transforms the user experience on degraded networks.

Strategy	Install Reliability	Offline UX	Data Freshness	Network Resilience
Monolithic Cache	Low (bloat causes failures)	Poor (blank screens or stale UI)	None (stale until refresh)	Fragile (blocks on network timeout)
Decoupled Shell/Data	High (shell installs fast)	Excellent (instant shell, graceful fallback)	High (background refresh)	Robust (isolated failure domains)

This finding matters because it enables the application to render the interface instantly from the cache while simultaneously attempting to fetch fresh data. If the network fails, the shell remains functional, and the user receives a clear fallback state rather than a browser error. This pattern mimics native application behavior, where the UI loads immediately and data populates asynchronously.

Core Solution

The implementation requires a service worker that routes requests based on resource type, applying specific caching strategies to each category. The architecture defines three distinct buckets: a shell bucket for static assets, an API bucket for dynamic data, and a fallback asset for network failures.

Implementation Steps

1. Define Cache Buckets: Establish versioned storage keys for the shell and API data to allow independent invalidation.
2. Install Handler: Pre-cache only the shell assets. This ensures the worker activates quickly without stalling on large data payloads.
3. Activate Handler: Clean up obsolete cache keys and claim control of all clients immediately to prevent race conditions.
4. Fetch Router: Intercept requests and delegate to specialized handlers based on URL patterns.
   • API Requests: Use a network-first approach with stale-while-revalidate logic. Update the cache in the background while serving the network response.
   • Shell Requests: Use a network-first approach with a cache fallback. This ensures the shell updates when online but remains available offline.
   • Fallback: Serve a static offline page when network requests fail and no cache exists.

Code Implementation

The following TypeScript service worker demonstrates the decoupled architecture. It uses a modular handler pattern to separate concerns and improves cache cleanup efficiency using a Set.

// sw.ts

// Distinct storage buckets with versioning for independent invalidation
const SHELL_STORAGE = 'pwa-shell-v2';
const API_STORAGE = 'pwa-api-v2';
const FALLBACK_ASSET = '/assets/offline-fallback.html';

// Core UI resources required for immediate rendering
const SHELL_RESOURCES = [
  '/',
  '/index.html',
  '/styles/core.css',
  '/scripts/runtime.js',
  '/manifest.webmanifest',
  '/assets/icons/icon-192.png'
];

self.addEventListener('install', (evt: ExtendableEvent) => {
  // Pre-cache shell only to ensure fast activation
  evt.waitUntil(
    caches.open(SHELL_STORAGE)
      .then((store) => store.addAll(SHELL_RESOURCES))
      .then(() => self.skipWaiting())
  );
});

self.addEventListener('activate', (evt: ExtendableEvent) => {
  // Efficient cleanup of obsolete caches
  const validKeys = new Set([SHELL_STORAGE, API_STORAGE]);
  
  evt.waitUntil(
    caches.keys().then((keys) => {
      const deletions = keys
        .filter((key) => !validKeys.has(key))
        .map((key) => caches.delete(key));
      return Promise.all(deletions);
    }).then(() => self.clients.claim())
  );
});

self.addEventListener('fetch', (evt: FetchEvent) => {
  const request = evt.request;
  const url = new URL(request.url);

  // Route API calls to data handler
  if (url.pathname.startsWith('/api/v1/')) {
    evt.respondWith(handleApiRequest(request));
    return;
  }

  // Route shell assets to shell handler
  if (SHELL_RESOURCES.includes(url.pathname)) {
    evt.respondWith(handleShellRequest(request));
    return;
  }

  // Default route for other assets
  evt.respondWith(handleGenericRequest(request));
});

async function handleApiRequest(request: Request): Promise<Response> {
  const cache = await caches.open(API_STORAGE);
  
  try {
    // Network-first: Attempt fetch
    const networkResponse = await fetch(request);
    
    // Update cache in background for next request (Stale-While-Revalidate)
    cache.put(request, networkResponse.clone());
    
    return networkResponse;
  } catch {
    // Fallback to cache if network fails
    const cachedResponse = await cache.match(request);
    if (cachedResponse) {
      return cachedResponse;
    }
    
    // Return structured error if no cache exists
    return new Response(JSON.stringify({ error: 'API unavailable offline' }), {
      status: 503,
      headers: { 'Content-Type': 'application/json' }
    });
  }
}

async function handleShellRequest(request: Request): Promise<Response> {
  try {
    // Network-first to pick up shell updates
    const networkResponse = await fetch(request);
    return networkResponse;
  } catch {
    // Fallback to shell cache
    const cachedResponse = await caches.match(request);
    if (cachedResponse) {
      return cachedResponse;
    }
    
    // Ultimate fallback
    return caches.match(FALLBACK_ASSET) as Promise<Response>;
  }
}

async function handleGenericRequest(request: Request): Promise<Response> {
  try {
    return await fetch(request);
  } catch {
    return caches.match(FALLBACK_ASSET) as Promise<Response>;
  }
}

Architecture Rationale

• Separation of Concerns: By isolating shell and API caches, updates to the UI do not invalidate data caches, and vice versa. This reduces unnecessary network traffic and improves cache hit rates.
• Network-First for Shell: The shell handler attempts the network first to ensure users receive the latest UI version. If the network fails, it falls back to the cache. This balances freshness with offline availability.
• Stale-While-Revalidate for API: The API handler prioritizes the network response but updates the cache asynchronously. This ensures data freshness when online while providing a cached fallback when offline.
• Structured Fallbacks: The API handler returns a JSON error object when offline, allowing the frontend to handle the error gracefully rather than parsing a generic network error.

Pitfall Guide

Pitfall	Explanation	Fix
Install Bloat	Caching dynamic data or large assets during the install event causes the worker to stall or fail on slow connections.	Limit the install handler to shell assets only. Populate data caches lazily via fetch handlers.
Stale Data Trap	Using cache-first strategies for API endpoints results in users viewing outdated information until a manual refresh.	Implement network-first with cache fallback for dynamic data. Use stale-while-revalidate to update caches in the background.
Missing Fallback	Failing to provide a fallback route results in browser error pages or blank screens when resources are unavailable.	Define a static offline page and serve it in the catch blocks of fetch handlers. Ensure the fallback is cached during install.
Cache Versioning Neglect	Forgetting to increment cache version strings leads to users running outdated code or accumulating orphaned caches.	Automate cache versioning in the build process. Include version suffixes in storage keys and clean up old keys in the activate handler.
Activation Race	Not calling clients.claim() in the activate handler leaves existing pages uncontrolled by the new service worker until a reload.	Always call self.clients.claim() after cache cleanup in the activate event to ensure immediate control.
Origin Mismatch	Attempting to cache cross-origin requests without proper CORS configuration results in opaque responses that cannot be stored.	Verify request origins before caching. Use mode: 'cors' for cross-origin requests or exclude third-party assets from caching logic.
Response Cloning Errors	Failing to clone responses before storing them in the cache consumes the response body, making it unavailable for the client.	Always call response.clone() when putting a response into the cache. Ensure the original response is returned to the client.

Production Bundle

Action Checklist

• Audit application assets to identify the minimal set required for the app shell.
• Implement distinct cache buckets for shell and API data with versioned keys.
• Configure the install handler to pre-cache only shell resources.
• Implement network-first strategies with cache fallbacks for all resource types.
• Add a static offline fallback page and route unhandled failures to it.
• Verify cache cleanup logic in the activate handler removes obsolete keys.
• Test the service worker on throttled network conditions (e.g., 3G, offline).
• Monitor cache storage usage and implement eviction policies if necessary.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Static Documentation	Cache-First	Maximizes load speed; content rarely changes.	Low bandwidth usage.
Real-Time Dashboard	Network-First	Ensures data accuracy; cache serves as fallback.	Higher bandwidth; potential latency.
E-Commerce Product List	Stale-While-Revalidate	Balances speed and freshness; updates cache in background.	Moderate bandwidth; improved UX.
User Profile Data	Network-First with SWR	Prioritizes current user state; caches for offline access.	Moderate bandwidth; high reliability.

Configuration Template

Use this template to structure your service worker registration and configuration. This ensures consistent initialization and error handling.

// sw-config.ts

export const CACHE_CONFIG = {
  shell: {
    key: 'pwa-shell-v2',
    resources: [
      '/',
      '/index.html',
      '/styles/core.css',
      '/scripts/runtime.js'
    ]
  },
  api: {
    key: 'pwa-api-v2',
    prefix: '/api/v1/'
  },
  fallback: '/assets/offline-fallback.html'
};

export function registerServiceWorker() {
  if ('serviceWorker' in navigator) {
    window.addEventListener('load', () => {
      navigator.serviceWorker.register('/sw.js')
        .then((registration) => {
          console.log('ServiceWorker registered:', registration.scope);
        })
        .catch((error) => {
          console.error('ServiceWorker registration failed:', error);
        });
    });
  }
}

Quick Start Guide

1. Create Service Worker: Initialize sw.js with the decoupled architecture pattern. Define shell and API cache buckets.
2. Define Shell Assets: List all static resources required for the initial UI render in the SHELL_RESOURCES array.
3. Implement Handlers: Add install, activate, and fetch event listeners with routing logic for shell, API, and fallback requests.
4. Register Worker: Include the service worker registration script in your application's entry point.
5. Validate Offline: Open browser DevTools, enable offline mode, and verify the app shell loads and the offline fallback appears for missing resources.