Building Pwa From Existing Site

The Hidden Cost of "Just a Website" on Mobile

You have a site. It works. Users visit it on mobile. But it feels like a website.

The address bar is there. The status bar bleeds through. Tapping "Add to Home Screen" does nothing because the browser doesn't recognize it as installable. When the subway signal drops, the user sees a broken page. No offline mode. No push notifications. No native-like experience.

We built this skill because we're tired of seeing engineers hand-roll service workers with copy-pasted snippets that break on edge cases. The gap between a "mobile-friendly site" and a "Progressive Web App" is small in theory but messy in practice. You need a manifest, icons, a service worker, caching strategies, and update handling. Doing this manually for an existing codebase is risky. You might cache an API response too long. You might miss a required manifest field. You might break authentication flows.

This skill guides you through the conversion safely. It doesn't ask you to rebuild your app. It takes your existing site and wraps it in PWA capabilities. We reference the standard tutorials ^[4], but we go further. We provide a production-grade workflow that handles the details most tutorials skip.

What Bad PWA Implementation Costs You

Ignoring PWA capabilities costs you retention. Users who install PWAs engage more ^[1]. If you don't give them that option, you lose the power users. But it's not just about installs. It's about reliability.

When a user goes offline, a bad service worker can serve stale data or break the UI entirely. Imagine a logistics dashboard that caches an API route for 24 hours. The driver sees a delivery as "Pending" when it's actually "Delivered". That's a trust failure. Or worse, the service worker crashes on registration, and the app becomes completely inaccessible.

Fixing a broken service worker later is harder than getting it right the first time. You also risk security issues. If you don't configure caching correctly, you might cache sensitive data or break authentication flows. And if you're managing a multi-origin setup, the complexity doubles ^[7].

The cost isn't just hours. It's user trust and app store visibility. Tools like the PWA report card ^[6] show you exactly where you're failing. Missing manifest fields, missing icons, missing service worker. These are easy to fix, but only if you have a structured approach. Not a blog post snippet. A validated workflow.

A Logistics Team's Three PWA Mistakes

Imagine a team running a fleet management dashboard built on a legacy React stack. They have 200 endpoints. They want their drivers to install the app.

They start by adding a manifest.json. They forget the start_url. The install prompt never fires. They add a service worker. They use generateSW because it's easier. It precaches everything, including dynamic API responses. Now the dashboard shows old data. The drivers are calling support.

They switch to injectManifest to have more control. They write a build script. They forget to handle the skipWaiting event. When the app updates, drivers keep seeing the old version until they close the tab. They finally get the caching right. But the offline fallback is just the browser's default error page. The drivers don't know how to fix it. They think the app is broken.

This is exactly the scenario our skill solves. We reference the CycleTracker tutorial's approach to service workers ^[3], but we go further. We provide a production-grade manifest ^[2]. We provide a Workbox configuration that handles precaching, navigation routing, and runtime caching strategies. We provide a validation script to catch errors before deployment. We provide an offline fallback page that actually helps the user. This isn't a theoretical exercise. It's a real workflow for real codebases.

What Changes Once the Skill Is Installed

Once you install this skill, the conversion process becomes deterministic. You run the orchestrator. It walks you through the steps. You get a manifest.json that passes all installability checks. Required fields, icon sizes, theme colors, display mode. You get a sw.js built with Workbox injectManifest. It precaches your shell. It caches images with CacheFirst. It caches APIs with NetworkFirst.

You get a register-sw.js that handles updates. When a new version is available, the user is prompted. The controllerchange event is handled. You get a offline.html that tells the user they're offline and offers a retry button. You get a validate-pwa.sh script that checks your project for compliance. You get a scaffold.sh script that sets up the templates in your target directory. You get a production-config.yaml example for complex sites. You get a test suite to ensure your validator works.

The result is a PWA that installs, works offline, updates gracefully, and feels like a native app. No more guessing. No more broken service workers. Just a reliable, installable experience. If you're also building a Chrome extension, check out our Building Chrome Extension skill. For settings pages, see Building Settings Preferences Page. Need CDN optimization? Try Configuring Cloudflare Cdn. Building a waitlist? Use Building Waitlist Page. Static sites? Check Building Static Site With Astro. Or generate landing pages with Building Landing Page Generator. We also have the PWA Builder Pack for broader PWA features.

What's in the Building PWA From Existing Site Pack

• skill.md — Orchestrator skill that defines the workflow for converting an existing site to a PWA. References all templates, scripts, validators, and references. Guides the agent through manifest creation, Workbox configuration, offline fallback setup, and validation.
• templates/manifest.json — Production-grade Web App Manifest with required fields, multiple icon sizes, display mode, and theme colors. Includes comments explaining optional fields like categories and orientation.
• templates/sw.js — Workbox service worker source using injectManifest pattern. Includes precaching, navigation routing, runtime caching for images/APIs/fonts, offline catch handler, and lifecycle management (skipWaiting/clientsClaim).
• templates/build-sw.js — Node.js build script using workbox-build.injectManifest. Configures glob patterns, injection point, cache busting exclusions, and max file size. Used to generate the final sw.js with the precache manifest injected.
• templates/offline.html — Minimal offline fallback page with retry button and clear messaging. Used by the service worker catch handler when navigation requests fail offline.
• templates/register-sw.js — Client-side registration script with robust update handling. Detects new service worker versions, prompts user to update, and handles controllerchange events.
• scripts/scaffold.sh — Executable scaffolding script that copies templates to a target directory, replaces placeholders (site name, origin, API routes), and validates the output structure. Exits non-zero on failure.
• scripts/validate-pwa.sh — Validator script that checks a project directory for PWA compliance. Verifies manifest keys, service worker syntax, offline page existence, and registration script presence. Exits 1 on any failure.
• references/canonical-knowledge.md — Embedded authoritative knowledge from Workbox docs. Covers generateSW vs injectManifest, caching strategies (CacheFirst, NetworkFirst, StaleWhileRevalidate), plugins (Expiration, CacheableResponse), precaching lifecycle, navigation fallbacks, and manifest requirements.
• examples/production-config.yaml — Example configuration mapping to build-sw.js options for a complex site. Defines API origins, image patterns, font caching rules, and runtime caching strategies for reference.
• tests/test-validator.sh — Test suite for the validator. Creates mock valid and invalid project structures, runs validate-pwa.sh, and asserts exit codes to ensure the validator correctly detects errors and passes valid configs.

Stop Guessing. Start Shipping.

Stop guessing at service worker configs. Start shipping installable apps. Upgrade to Pro to install this skill.