Proposal: Add a Service Worker to the Workshop frontend

[samkelleher]

Add production Service Worker support to packages/workshop-frontend using vite-plugin-pwa (generateSW). Static assets are precached and served Cache-First. With registerType: 'autoUpdate', new builds activate via skipWaiting / clientsClaim and open clients reload onto the new revision without an in-app update prompt.

Motivation

Workshop is a long-lived SPA. Without a Service Worker, every navigation and cold load re-fetches hashed assets, and there is no structured way to roll a new deploy under an already-open tab. Precaching improves repeat-load performance; autoUpdate plus virtual:pwa-register avoids leaving clients stuck on an old in-memory build when /sw.js changes.

After implementing this change, Cloudflare OS, can be installed as an desktop windowed app (in most browsers) and it starts instantly with no load time. It really makes this a first class experience.

Approach

Use the default generateSW strategy. Registration goes through virtual:pwa-register with immediate: true so:

1. The SW registers as soon as the entry module runs (not only on window.load).
2. When a new SW takes control, the tab reloads onto the new precache (required for true silent updates; plain injectRegister alone registers but does not reload open clients).

The web app manifest is declared in the Vite PWA plugin config so install metadata and the Service Worker ship from one place.

Dependencies

In packages/workshop-frontend:

pnpm add -D vite-plugin-pwa workbox-window

workbox-window is a peer of vite-plugin-pwa and must be declared on the package that imports virtual:pwa-register (pnpm will not hoist it otherwise).

vite.config.ts (drop-in)

Replace the package Vite config with:

import { defineConfig, loadEnv } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import tsconfigPaths from 'vite-tsconfig-paths'
import { TanStackRouterVite } from '@tanstack/router-plugin/vite'
import { VitePWA } from 'vite-plugin-pwa'

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  const backendHost = env.VITE_BACKEND_HOST?.trim() || 'localhost:8787'
  const frontendErrorReporting = env.VITE_FRONTEND_ERROR_REPORTING === 'true'
  return {
    plugins: [
      TanStackRouterVite({ target: 'react', autoCodeSplitting: true }),
      react(),
      tailwindcss(),
      tsconfigPaths(),
      VitePWA({
        // skipWaiting + clientsClaim; pair with virtual:pwa-register for client reload.
        registerType: 'autoUpdate',
        // Entry point imports virtual:pwa-register explicitly.
        injectRegister: null,
        workbox: {
          globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2,webmanifest}'],
          cleanupOutdatedCaches: true,
          navigateFallback: 'index.html',
          // Do not treat API / gatekeeper / screenshot traffic as SPA navigations.
          navigateFallbackDenylist: [
            /^\/api(?:\/|$)/,
            /^\/gatekeeper(?:\/|$)/,
            /^\/blueprint-screenshot(?:\/|$)/,
          ],
          // Large route chunks (e.g. editor) exceed Workbox's 2 MiB default.
          maximumFileSizeToCacheInBytes: 4 * 1024 * 1024,
        },
        manifest: {
          name: 'Workshop',
          short_name: 'Workshop',
          theme_color: '#ffffff',
          background_color: '#ffffff',
          display: 'standalone',
          start_url: '.',
          icons: [
            {
              src: 'pwa-192x192.png',
              sizes: '192x192',
              type: 'image/png',
            },
            {
              src: 'pwa-512x512.png',
              sizes: '512x512',
              type: 'image/png',
            },
          ],
        },
      }),
    ],
    server: {
      port: 3000,
      host: true,
      proxy: {
        '/api/client-errors': `http://${backendHost}`,
        '/blueprint-screenshot': `http://${backendHost}`,
        '/api/site-logo': `http://${backendHost}`,
      },
    },
    build: {
      sourcemap: frontendErrorReporting ? 'hidden' : false,
    },
  }
})

Place pwa-192x192.png and pwa-512x512.png under public/ (or adjust the icons paths). The plugin emits the web manifest and injects the corresponding <link rel="manifest"> at build time.

Entry point registration

At the top of src/main.tsx:

import { registerSW } from 'virtual:pwa-register'

// Registers immediately; autoUpdate reloads quietly when a new SW takes control.
registerSW({ immediate: true })

For TypeScript, either add "vite-plugin-pwa/client" to compilerOptions.types, or declare the virtual module in src/vite-env.d.ts.

Static asset headers

/sw.js must revalidate so clients discover new precache manifests promptly. Hashed workbox-*.js files sit next to sw.js (Workbox does not emit them under assets/) and are content-addressed, so they may use long-lived immutable caching—same policy as other hashed build outputs.

Example (Workers static-assets _headers style):

/sw.js
  Cache-Control: public, max-age=0, must-revalidate

/workbox-*.js
  Cache-Control: public, max-age=31536000, immutable

Behaviour notes

Concern	Behaviour
Precache	Build-time hashed JS/CSS/HTML (and configured static types)
Runtime API / WS	Not Cache-First; denylist keeps /api, /gatekeeper, /blueprint-screenshot off the SPA fallback
Updates	New /sw.js → install → skipWaiting / clientsClaim → client reload via virtual:pwa-register
Update UI	None; open tabs reload when the new SW takes control (can interrupt in-progress input)
Dev	Leave devOptions.enabled unset/false; SW is a production build concern

Out of scope / follow-ups

• Prompt-for-update UI (registerType: 'prompt') if forced reload is undesirable for long sessions.
• injectRegister: 'script' | 'inline' as a lighter alternative that registers without reloading open clients.
• Aligning manifest name/theme with admin-configured site branding at build or runtime.