pwa-storefront

What this skill does

# PWA Storefront

## Overview

A Progressive Web App (PWA) storefront combines the reach of the web with native-app-like capabilities: offline catalog browsing, push notifications, home screen installation, and fast repeat loads from cache. Service workers intercept network requests and implement caching strategies that keep the store functional on flaky connections. This skill covers implementing a service worker with Workbox, creating a Web App Manifest, caching product catalogs, and sending push notifications for order updates.

## When to Use This Skill

- When your customers are in regions with unreliable mobile internet connectivity
- When you want to enable "Add to Home Screen" for higher re-engagement rates without a native app
- When repeat page loads should be instant by serving assets from cache
- When you want to send push notifications for order status updates, back-in-stock alerts, or promotions
- When building a mobile-first storefront that needs to compete with native apps in UX quality

## Prerequisites & Platform Notes

**This skill is written for custom/headless storefronts** (Node.js, Python, or similar backend). The code examples use TypeScript/Node.js and can be adapted to any stack.

**Shopify**: Shopify Hydrogen is Shopify's headless framework. MACH/composable patterns apply when using Shopify as the commerce backend with a custom frontend, or when mixing Shopify with other best-of-breed services.
**WooCommerce**: WooCommerce can serve as a headless backend via its REST API and WPGraphQL. These patterns apply when decoupling the frontend from WordPress.
**Magento**: Magento's GraphQL API and PWA Studio support headless architectures. These composable patterns apply to Magento as a backend service in a MACH stack.

**You'll need**:
- Node.js 18+ (or adapt to your backend language)
- PostgreSQL (or your preferred relational database)
- Redis for caching/queues
- An email sending service (SendGrid, AWS SES, or Postmark)
- CDN (Cloudflare, CloudFront, or Fastly)

## Core Instructions

1. **Create the Web App Manifest**

   The manifest makes the app installable on Android and iOS (iOS has partial support):

   ```json
   // public/manifest.json
   {
     "name": "My Commerce Store",
     "short_name": "MyStore",
     "description": "Fast, reliable shopping from anywhere",
     "start_url": "/?source=pwa",
     "display": "standalone",
     "background_color": "#ffffff",
     "theme_color": "#1a1a2e",
     "orientation": "portrait-primary",
     "icons": [
       { "src": "/icons/icon-72x72.png", "sizes": "72x72", "type": "image/png" },
       { "src": "/icons/icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "any maskable" },
       { "src": "/icons/icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "any maskable" }
     ],
     "screenshots": [
       { "src": "/screenshots/home.png", "sizes": "390x844", "type": "image/png", "form_factor": "narrow" }
     ],
     "categories": ["shopping"],
     "share_target": {
       "action": "/search",
       "method": "GET",
       "params": { "title": "q" }
     }
   }
   ```

   Link in your HTML:
   ```html
   <link rel="manifest" href="/manifest.json">
   <meta name="theme-color" content="#1a1a2e">
   <meta name="apple-mobile-web-app-capable" content="yes">
   <meta name="apple-mobile-web-app-status-bar-style" content="default">
   <link rel="apple-touch-icon" href="/icons/icon-192x192.png">
   ```

2. **Register a service worker with Workbox**

   ```bash
   npm install workbox-webpack-plugin
   # or for Vite:
   npm install vite-plugin-pwa
   ```

   Using `vite-plugin-pwa` (recommended for Vite/Next.js projects):

   ```typescript
   // vite.config.ts
   import {VitePWA} from 'vite-plugin-pwa';

   export default {
     plugins: [
       VitePWA({
         registerType: 'autoUpdate',
         workbox: {
           globPatterns: ['**/*.{js,css,html,svg,png,webp,woff2}'],
           runtimeCaching: [
             {
               urlPattern: /^https:\/\/fonts\.googleapis\.com/,
               handler: 'CacheFirst',
               options: {cacheName: 'google-fonts-cache', expiration: {maxAgeSeconds: 60 * 60 * 24 * 365}},
             },
             {
               urlPattern: /\/api\/products/,
               handler: 'StaleWhileRevalidate',
               options: {
                 cacheName: 'products-cache',
                 expiration: {maxEntries: 500, maxAgeSeconds: 60 * 60 * 24}, // 24h
                 cacheableResponse: {statuses: [0, 200]},
               },
             },
             {
               urlPattern: /\/api\/collections/,
               handler: 'NetworkFirst',
               options: {
                 cacheName: 'collections-cache',
                 networkTimeoutSeconds: 3,
                 expiration: {maxEntries: 50, maxAgeSeconds: 60 * 60},
               },
             },
           ],
         },
         manifest: {/* inline manifest or path */},
       }),
     ],
   };
   ```

3. **Implement a custom service worker for offline catalog**

   For fine-grained control, write the service worker directly:

   ```javascript
   // public/sw.js
   import {precacheAndRoute, cleanupOutdatedCaches} from 'workbox-precaching';
   import {registerRoute} from 'workbox-routing';
   import {StaleWhileRevalidate, CacheFirst, NetworkFirst} from 'workbox-strategies';
   import {ExpirationPlugin} from 'workbox-expiration';
   import {BackgroundSyncPlugin} from 'workbox-background-sync';

   // Precache app shell (injected by build tool)
   precacheAndRoute(self.__WB_MANIFEST);
   cleanupOutdatedCaches();

   // Product images: Cache-first with 7-day expiry
   registerRoute(
     ({url}) => url.hostname.includes('cdn.shopify.com') || url.pathname.includes('/product-images/'),
     new CacheFirst({
       cacheName: 'product-images',
       plugins: [
         new ExpirationPlugin({maxEntries: 200, maxAgeSeconds: 60 * 60 * 24 * 7}),
       ],
     })
   );

   // Product API: Stale-while-revalidate (show cached, refresh in background)
   registerRoute(
     ({url}) => url.pathname.startsWith('/api/products') || url.pathname.startsWith('/api/collections'),
     new StaleWhileRevalidate({
       cacheName: 'api-products',
       plugins: [
         new ExpirationPlugin({maxEntries: 500, maxAgeSeconds: 60 * 60 * 24}),
       ],
     })
   );

   // Background sync for cart operations when offline
   const cartSyncPlugin = new BackgroundSyncPlugin('cart-sync-queue', {
     maxRetentionTime: 24 * 60, // Retry for 24 hours
   });

   registerRoute(
     ({url, request}) => url.pathname.startsWith('/api/cart') && request.method !== 'GET',
     new NetworkFirst({plugins: [cartSyncPlugin]}),
     'POST'
   );
   ```

4. **Show an offline fallback page**

   ```javascript
   // In the service worker
   import {setCatchHandler, setDefaultHandler} from 'workbox-routing';

   // Precache the offline page during installation
   precacheAndRoute([{url: '/offline', revision: '1'}]);

   // Serve offline page for navigation requests when network fails
   setCatchHandler(async ({event}) => {
     if (event.request.destination === 'document') {
       return caches.match('/offline');
     }
     return Response.error();
   });
   ```

   ```typescript
   // app/offline/page.tsx
   export default function OfflinePage() {
     return (
       <div className="flex flex-col items-center justify-center min-h-screen">
         <h1>You're offline</h1>
         <p>Check your connection. Recently viewed products are still available below.</p>
         <RecentlyViewedProducts /> {/* Reads from IndexedDB */}
       </div>
     );
   }
   ```

5. **Implement Web Push notifications**

   ```typescript
   // client: subscribe to push notifications
   async function subscribeToPush() {
     const registration = await navigator.serviceWorker.ready;
     const subscription = await registration.pushManager.subscribe({
       userVisibleOnly: true,
       applica