PWA Builder Pack

The Service Worker Trap

You know the drill. You spend three days getting your manifest.json right, only to find the "Add to Home Screen" prompt never fires because the icon resolution is off by one pixel or the display mode is invalid. Then you write a service worker, thinking you've nailed the offline caching, but the browser rejects it because you missed a security header or the TLS handshake fails on a subresource. You're not building a Progressive Web App; you're debugging browser inconsistencies. Service workers act as proxy servers between your app and the network, but when they break, they break silently ^[5]. You end up with a web app that looks like a PWA but behaves like a broken tab. If you're starting from scratch, you can always look at guides for Building PWA From Existing Site, but even then, the underlying mechanics of the service worker lifecycle remain a minefield ^[4].

What Broken PWAs Cost You

Every failed install is a churn event. If your PWA doesn't install, you lose the ability to re-engage users with push notifications, which are critical for retention ^[1]. You're burning engineering hours on sw.js lifecycle edge cases instead of shipping features. Worse, if your push notifications don't work on Safari because you ignored the specific iOS requirements, you're blind to a massive segment of your user base ^[8]. You risk security vulnerabilities if your manifest or service worker doesn't enforce strict TLS and CSP headers, leaving your app exposed ^[7].

The cost isn't just time; it's the trust your users place in your app's reliability. A PWA is defined by its ability to provide a platform-specific experience through progressive enhancement ^[6], but when the offline fallback fails or the push endpoint returns a 403, you're just a slow website. If you're running experiments to optimize conversion, you need a solid A/B Testing Framework Pack to validate hypotheses, but those experiments are useless if the underlying app crashes on the first offline attempt. And if your app caches user data, you need legally compliant Privacy Policy & Terms Pack templates to disclose exactly how that offline data is handled.

A Logistics Team's Three-Week Detour

Imagine a logistics team shipping a field operations app. They need offline access for inventory checks and push alerts for route changes. They start with a basic sw.js, trying to cache assets for offline use. But when they try to implement push notifications, the subscription fails on iOS because they didn't handle the PushManager.subscribe() flow correctly ^[2]. They spend two weeks debugging cache keys and expiration plugins, only to find the app still fails to register as a PWA because the manifest lacked the required security metadata.

They eventually pivot to a native wrapper, doubling their maintenance overhead, when a proper Workbox configuration and strict manifest validation would have solved everything in a single afternoon. They could have used a React Native Mobile Pack to build the native side, but that's a band-aid on a web architecture problem. The real issue was a lack of canonical references for service worker strategies and security headers. Without a validation script to catch these errors early, they shipped a broken product and lost three weeks of development time.

What Changes Once the Pack Is Installed

With PWA Builder Pack installed, you stop guessing and start shipping. The sw.js template uses Workbox v7 modules, giving you production-grade precaching, runtime strategies like StaleWhileRevalidate, and automatic client claiming for SPAs. The manifest.json template enforces strict schema compliance, ensuring your app passes store submission checks and browser recognition. Push notifications work because the template includes the correct endpoint and consent flows.

You get a validation script that catches TLS issues and manifest errors before they hit production. You can even run A/B tests on features without breaking offline caching, thanks to integrated references on safe state management. If you need to validate your testing strategy across unit, integration, and E2E layers, this pack integrates cleanly with a Testing Mastery Pack to ensure your service worker updates don't regress core functionality. And for feature rollouts, the pack's references align perfectly with a Feature Flag Management Pack, allowing you to toggle push notification endpoints or caching strategies without redeploying the entire app.

What's in the PWA Builder Pack

• skill.md — Orchestrator skill that defines the PWA Builder Pack workflow, enforces best practices, and explicitly references all templates, scripts, validators, references, and examples by relative path to guide the AI agent.
• templates/sw.js — Production-grade Service Worker implementation using Workbox v7 modules. Handles precaching, navigation routing, runtime caching strategies (CacheFirst, NetworkFirst, StaleWhileRevalidate), expiration plugins, offline fallbacks, and skip-waiting messaging.
• templates/workbox-build.config.js — Node.js build script using workbox-build generateSW to automate SW generation. Configures glob patterns, precaching, runtime caching rules, navigation fallbacks, and client claiming for SPA deployments.
• templates/manifest.json — Strict PWA Web App Manifest template. Includes display modes, theme colors, icons, push notification endpoint, A/B experiment IDs, and security-related metadata required for store submission and browser recognition.
• templates/terms-legal.md — Legally compliant terms and privacy template generator. Covers offline data caching disclosures, push notification consent flows, A/B testing data collection, TLS encryption notices, and jurisdictional compliance placeholders.
• scripts/pwa-validate.sh — Executable validation script that checks PWA readiness. Verifies manifest existence and schema compliance, tests SW registration syntax, enforces TLS requirements, checks for required security headers, and exits non-zero on failure.
• validators/manifest-schema.json — JSON Schema validator for manifest.json. Enforces required PWA fields, icon resolution constraints, display mode values, push endpoint URL format, and A/B experiment ID patterns. Used by pwa-validate.sh.
• references/workbox-strategies.md — Canonical reference for Workbox caching strategies, service worker lifecycle, range request handling, cache expiration, and offline fallback patterns. Contains exact routing configurations and plugin usage from authoritative docs.
• references/pwa-security-tls.md — Canonical reference for PWA security. Covers TLS 1.2+ requirements, HSTS headers, Content Security Policy for service workers, push notification encryption/authentication, and secure A/B testing data transmission.
• references/ab-testing-implementation.md — Canonical reference for PWA A/B testing. Covers feature flag architecture, client-side experiment routing, safe state management, rollback strategies, and metrics collection without violating offline caching rules.
• examples/worked-deployment.md — Worked example showing complete project structure, configuration mapping between templates, build pipeline steps, and store submission checklist for Windows/Chromium and general web platforms.
• examples/test-suite.sh — Executable test suite that simulates PWA installation, triggers service worker activation, validates cache keys, checks push notification subscription flow, and exits non-zero if any critical check fails.

Install and Ship

Stop wrestling with service workers. Upgrade to Pro to install.