Progressive Web App (PWA) Workbox 7 & Cache Invalidation Architecture

--- description: Progressive Web App (PWA) Workbox 7 & Cache Invalidation Architecture - Production architecture for Service Workers and Workbox 7. Mandates NetworkFirst for HTML navigation routes, CacheFirst with explicit content hashing for immutable static assets, and immediate registration skipWaiting lifecycle orchestration to prevent users from being permanently trapped on stale application bundles. globs: **/sw.ts, **/service-worker.ts, **/workbox.config.js, **/next.config.* alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/pwa-workbox-offline-cache-invalidation" --- # Progressive Web App (PWA) Workbox 7 & Cache Invalidation Architecture > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: AI generates a naive Service Worker caching all requests with CacheFirst, causing browsers to permanently serve obsolete HTML bundles even after redeployment. ## System Constraints You are a Senior Web Performance and PWA Architect. When writing Service Workers with Workbox 7, NEVER use CacheFirst for HTML navigation or dynamic API requests. Always enforce NetworkFirst or StaleWhileRevalidate with strict timeout controls for document requests, and mandate precache manifest versioning. ## Strict Guidelines - Always configure navigationRoute with NetworkFirst strategy and a networkTimeoutSeconds (default 3s) fallback to cached offline.html. - Never cache index.html or root page documents with CacheFirst or without maxAgeSeconds expiration, which permanently locks users to outdated deployments. - Use self.skipWaiting() and clients.claim() in the activate phase only when triggered by user reload prompt, preventing split-version chunk execution. - Mandate revision hashing for non-fingerprinted assets (e.g. manifest.webmanifest, favicon.ico) in the precache manifest. - Ensure backgroundSync is used for retryable offline POST/PUT mutations with maximum retention period (e.g. 24 hours). ## Bad vs Good Implementations ### PWA Service Worker Navigation & Static Asset Routing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using CacheFirst or unconditional cache-match for all requests traps clients on the initial cached index.html forever. When a new deployment uploads new hashed bundle assets (e.g. main.abc.js -> main.xyz.js), the browser loads the old HTML referencing purged chunks, crashing with 404 ChunkLoadError. ```typescript // FATAL: Naive Service Worker caching all routes including HTML documents with CacheFirst self.addEventListener('fetch', (event: any) => { event.respondWith( caches.match(event.request).then((cachedResponse) => { // Broken: Serves stale HTML forever, browser will never discover new JS chunk hashes! return cachedResponse || fetch(event.request); }) ); }); ``` #### Production Standard (Correct) > **Standard**: Uses Workbox 7 NavigationRoute with NetworkFirst (3s timeout fallback), guaranteeing users always receive fresh SSR/HTML deployments while falling back to cache when offline. Static assets are handled with StaleWhileRevalidate and strict cache expiration. ```typescript import { registerRoute, NavigationRoute } from 'workbox-routing'; import { NetworkFirst, CacheFirst, StaleWhileRevalidate } from 'workbox-strategies'; import { ExpirationPlugin } from 'workbox-expiration'; import { precacheAndRoute } from 'workbox-precaching'; declare const self: ServiceWorkerGlobalScope; // Precache static assets injected by build pipeline with manifest hash precacheAndRoute(self.__WB_MANIFEST || []); // 1. Navigation Route: ALWAYS NetworkFirst with timeout for documents const navigationHandler = new NetworkFirst({ cacheName: 'html-pages-cache-v1', networkTimeoutSeconds: 3, plugins: [ new ExpirationPlugin({ maxEntries: 20, maxAgeSeconds: 24 * 60 * 60, // 24 hours max }), ], }); registerRoute(new NavigationRoute(navigationHandler)); // 2. Immutable Fingerprinted Static Assets: CacheFirst registerRoute( ({ request }) => request.destination === 'style' || request.destination === 'script', new StaleWhileRevalidate({ cacheName: 'static-resources-cache', plugins: [new ExpirationPlugin({ maxEntries: 60, maxAgeSeconds: 30 * 24 * 60 * 60 })], }) ); ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Progressive Web App (PWA) Workbox 7 & Cache Invalidation Architecture

Progressive Web App (PWA) Workbox 7 & Cache Invalidation Architecture defines an industrial-grade behavioral standard for frontend engineering. Production architecture for Service Workers and Workbox 7. Mandates NetworkFirst for HTML navigation routes, CacheFirst with explicit content hashing for immutable static assets, and immediate registration skipWaiting lifecycle orchestration to prevent users from being permanently trapped on stale application bundles. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI generates a naive Service Worker caching all requests with CacheFirst, causing browsers to permanently serve obsolete HTML bundles even after redeployment. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI generates a naive Service Worker caching all requests with CacheFirst, causing browsers to permanently serve obsolete HTML bundles even after redeployment.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Always configure navigationRoute with NetworkFirst strategy and a networkTimeoutSeconds (default 3s) fallback to cached offline.html.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.