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

Create the Web App Manifest

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

// 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:

<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">

Register a service worker with Workbox

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

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

// 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 */},
    }),
  ],
};

Implement a custom service worker for offline catalog

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

// 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'
);

Show an offline fallback page

// 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();
});

// 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>
  );
}

Implement Web Push notifications

// client: subscribe to push notifications
async function subscribeToPush() {
  const registration = await navigator.serviceWorker.ready;
  const subscription = await registration.pushManager.subscribe({
    userVisibleOnly: true,
    applicationServerKey: urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY!),
  });

  await fetch('/api/push/subscribe', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({subscription, customerId: user.id}),
  });
}

// server: send push notification for order status update
import webpush from 'web-push';

webpush.setVapidDetails(
  'mailto:support@mystore.com',
  process.env.VAPID_PUBLIC_KEY!,
  process.env.VAPID_PRIVATE_KEY!
);

export async function sendOrderUpdatePush(customerId: string, order: Order) {
  const subscriptions = await db.pushSubscriptions.findByCustomer(customerId);
  await Promise.allSettled(
    subscriptions.map(sub =>
      webpush.sendNotification(sub.data, JSON.stringify({
        title: `Order #${order.number} Update`,
        body: `Your order is now ${order.status}`,
        icon: '/icons/icon-192x192.png',
        url: `/orders/${order.id}`,
        tag: `order-${order.id}`,
      }))
    )
  );
}

Handle push events in the service worker:

self.addEventListener('push', (event) => {
  const data = event.data?.json();
  event.waitUntil(
    self.registration.showNotification(data.title, {
      body: data.body,
      icon: data.icon,
      badge: '/icons/badge-72x72.png',
      data: {url: data.url},
      tag: data.tag,
      renotify: true,
    })
  );
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow(event.notification.data.url));
});

Detect and respond to offline status in the UI

// hooks/use-online-status.ts
import {useState, useEffect} from 'react';

export function useOnlineStatus() {
  const [isOnline, setIsOnline] = useState(typeof navigator !== 'undefined' ? navigator.onLine : true);

  useEffect(() => {
    const setOnline = () => setIsOnline(true);
    const setOffline = () => setIsOnline(false);
    window.addEventListener('online', setOnline);
    window.addEventListener('offline', setOffline);
    return () => { window.removeEventListener('online', setOnline); window.removeEventListener('offline', setOffline); };
  }, []);

  return isOnline;
}

// Usage in a component
function CartButton() {
  const isOnline = useOnlineStatus();
  return (
    <button disabled={!isOnline} title={isOnline ? undefined : 'You are offline'}>
      Add to Cart
    </button>
  );
}

Examples

Lighthouse PWA audit checklist (automated)

# Install Lighthouse CLI
npm install -g lighthouse

# Audit PWA criteria
lighthouse https://mystore.com --preset=desktop --only-categories=pwa --output=json --output-path=./lighthouse-pwa.json

# Key scores to target:
# - "Installable" checks: manifest, service worker, HTTPS
# - "PWA Optimized" checks: themed address bar, offline page, mobile viewport

IndexedDB catalog cache for offline browsing

import {openDB} from 'idb';

const db = await openDB('catalog-db', 1, {
  upgrade(db) {
    db.createObjectStore('products', {keyPath: 'id'});
    db.createObjectStore('collections', {keyPath: 'id'});
  },
});

// Store products when user browses online
export async function cacheProductsLocally(products: Product[]) {
  const tx = db.transaction('products', 'readwrite');
  await Promise.all([...products.map(p => tx.store.put(p)), tx.done]);
}

// Retrieve from IDB when offline
export async function getProductFromCache(id: string): Promise<Product | null> {
  return db.get('products', id) ?? null;
}

Best Practices

Use StaleWhileRevalidate for product data — the user sees cached content immediately while the service worker fetches the latest data in the background
Never cache cart or checkout pages — these must always be fresh; use NetworkOnly strategy for /cart, /checkout, and account pages
Version your service worker cache names — when you update your app, increment cache names so stale assets are purged automatically
Test offline mode in Chrome DevTools — use the Network tab → "Offline" throttle to verify your offline experience before deploying
Generate VAPID keys once and store them securely — VAPID private key loss means losing all existing push subscriptions; store in a secrets manager
Request push permission with context — prompt users to allow notifications only after a relevant action (order placed, back-in-stock interested) to maximize opt-in rates
Set reasonable cache size limits — use ExpirationPlugin with maxEntries to prevent the service worker cache from consuming too much device storage

Common Pitfalls

Problem	Solution
Service worker not updating after deployment	Use `registerType: 'autoUpdate'` and call `skipWaiting()` in the service worker to take control immediately; show a "New version available" toast
Push notifications not shown on iOS	iOS requires the user to add the PWA to the Home Screen first; Web Push on iOS Safari requires iOS 16.4+ and `standalone` display mode
Cached API responses served after price changes	Set `maxAgeSeconds` appropriately; use on-demand cache invalidation by busting cache names on deployment
Background sync fails silently	Wrap background sync in try/catch and log errors; test with the DevTools Application → Background Sync panel
App installability failing Lighthouse audit	Check for: HTTPS, valid manifest with 512×512 maskable icon, registered service worker, and `start_url` responding with 200

Related Skills

@jamstack-storefront
@image-optimization-cdn
@edge-commerce
@monitoring-alerting-commerce

pwa-storefront