@kazzle/app 0.1.800 → 0.1.802

package/README.md

@@ -17,7 +17,8 @@ the AI stale types. This package replaces the copies with real imports:
 ```ts
 import { defineConfig } from '@kazzle/app';
 import { defineTools } from '@kazzle/app/tools';
-import { kazzleAppVite } from '@kazzle/app/vite';
+import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
+import { registerAppSW } from '@kazzle/app/pwa';
 ```
 
 ## Subpath exports — keep them separate
@@ -31,7 +32,8 @@ and the root export must stay tiny and dependency-free.
 | `@kazzle/app` | `defineConfig`, `KazzleConfig` + component/trigger/env types | none |
 | `@kazzle/app/tools` | `defineTools`, `KazzleTool` types, Zod input helper types | `zod` (peer, type-only) |
 | `@kazzle/app/client` | install-scoped client: per-install secrets, sibling component URLs | none |
-| `@kazzle/app/vite` | `kazzleAppVite` preview/runtime Vite helper | `vite` (peer, type-only) |
+| `@kazzle/app/vite` | `kazzleAppVite` + `kazzleAppPwa` (HOST/PORT + production SW plugins) | `vite` (peer), `vite-plugin-pwa` |
+| `@kazzle/app/pwa` | `registerAppSW()` browser registration (owns `virtual:pwa-register`) | none (virtual module at build) |
 | `@kazzle/app/templates` | programmatic template manifest + asset readers (server/generator only) | none |
 | `@kazzle/app/migrations` | versioned app upgrade metadata + codemods (server/CLI only) | none |
 

package/dist/pwa.d.ts

@@ -0,0 +1,15 @@
+export type RegisterAppSWOptions = {
+    immediate?: boolean;
+    onNeedRefresh?: () => void;
+    onOfflineReady?: () => void;
+    onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void;
+    onRegisterError?: (error: unknown) => void;
+};
+/**
+ * Register the production service worker. No-op in dev when
+ * `kazzleAppPwa()` left `devOptions.enabled: false` (required).
+ *
+ * `immediate: true` by default so autoUpdate can claim clients as soon as a
+ * new worker is waiting.
+ */
+export declare function registerAppSW(options?: RegisterAppSWOptions): (reloadPage?: boolean) => Promise<void>;

package/dist/pwa.js

@@ -0,0 +1,21 @@
+// @kazzle/app/pwa — browser service-worker registration for Kazzle UI apps.
+//
+// Published apps need a service worker with autoUpdate so users pick up new
+// builds without a hard refresh. Templates MUST call `registerAppSW()` from
+// this module and MUST NOT import `virtual:pwa-register` themselves — the
+// virtual module + its types are owned here so a missing vite-env.d.ts cannot
+// break `appdev.check` (TS2307) on every fresh create.
+//
+// Pair with `kazzleAppPwa()` from `@kazzle/app/vite` in vite.config.ts.
+// Never enable the PWA plugin's `devOptions` — a SW in dev breaks Vite HMR.
+import { registerSW } from 'virtual:pwa-register';
+/**
+ * Register the production service worker. No-op in dev when
+ * `kazzleAppPwa()` left `devOptions.enabled: false` (required).
+ *
+ * `immediate: true` by default so autoUpdate can claim clients as soon as a
+ * new worker is waiting.
+ */
+export function registerAppSW(options = {}) {
+    return registerSW({ immediate: true, ...options });
+}

package/dist/vite.d.ts

@@ -1,4 +1,5 @@
-import type { UserConfig } from 'vite';
+import type { Plugin, UserConfig } from 'vite';
+import { type VitePWAOptions } from 'vite-plugin-pwa';
 export interface KazzleAppViteOptions {
     /**
      * Name of the sibling process component that owns this app's backend/API
@@ -18,12 +19,28 @@ export interface KazzleAppViteOptions {
      */
     proxyPaths?: string[];
 }
+export type KazzleAppPwaOptions = {
+    /** Merged over Kazzle's default workbox precache/runtime config. */
+    workbox?: VitePWAOptions['workbox'];
+    /** Optional web app manifest. Omit for a SW-only install (no install prompt). */
+    manifest?: VitePWAOptions['manifest'];
+    includeAssets?: VitePWAOptions['includeAssets'];
+};
 /**
  * Kazzle preview/runtime Vite config. Spread the result into your Vite config:
  *
  *   export default defineConfig(({ command }) => ({
- *     plugins: [react(), tailwindcss()],
+ *     plugins: [react(), tailwindcss(), ...kazzleAppPwa()],
  *     ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/todos'] }),
  *   }));
  */
 export declare function kazzleAppVite(command: string, options?: KazzleAppViteOptions): UserConfig;
+/**
+ * Kazzle production PWA plugins. Spread into `plugins` next to react/tailwind:
+ *
+ *   plugins: [react(), tailwindcss(), ...kazzleAppPwa()]
+ *
+ * Always pair with `registerAppSW()` from `@kazzle/app/pwa` in main.tsx.
+ * Do not import `vite-plugin-pwa` or `virtual:pwa-register` in the app.
+ */
+export declare function kazzleAppPwa(options?: KazzleAppPwaOptions): Plugin[];

package/dist/vite.js

@@ -1,9 +1,9 @@
-// @kazzle/app/vite — Kazzle preview/runtime Vite helper.
+// @kazzle/app/vite — Kazzle preview/runtime Vite helpers.
 //
-// BUILD-TIME ONLY. This module imports vite types and is meant for a UI
-// component's vite.config.ts. Never import it from process/runtime code — the
-// subpath split exists so process apps don't pull vite into their dependency
-// graph. See README.md.
+// BUILD-TIME ONLY. This module imports vite (+ vite-plugin-pwa) and is meant
+// for a UI component's vite.config.ts. Never import it from process/runtime
+// code — the subpath split exists so process apps don't pull vite into their
+// dependency graph. See README.md.
 //
 // READ THIS BEFORE TOUCHING vite.config.ts (human or AI):
 // Kazzle assigns every UI component a specific HOST and PORT at preview/run
@@ -12,8 +12,19 @@
 // 5173) the tunnel gets ECONNREFUSED and the preview looks broken. This helper
 // is the ONE place that reads HOST/PORT and pins Vite to them (strictPort).
 //
-// Every UI component's vite.config.ts MUST spread `...kazzleAppVite(command)`
-// into its config instead of hand-writing server.host / server.port.
+// Every UI component's vite.config.ts MUST:
+//   1. Spread `...kazzleAppVite(command)` — never hand-write server.host/port.
+//   2. Spread `...kazzleAppPwa()` into plugins — never import vite-plugin-pwa
+//      or `virtual:pwa-register` in the app. Browser entry calls
+//      `registerAppSW()` from `@kazzle/app/pwa`.
+//
+// Keep this file self-contained (no relative imports). Vite loads the
+// published entry under Node ESM, which requires explicit .js extensions for
+// relatives — a single file avoids that footgun.
+import { createRequire } from 'node:module';
+import { VitePWA } from 'vite-plugin-pwa';
+const requireFromSdk = createRequire(import.meta.url);
+const DEFAULT_PWA_GLOB_PATTERNS = ['**/*.{js,css,html,ico,png,svg,woff2}'];
 function componentUrlEnvName(componentName) {
     const normalized = componentName.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_|_$/g, '');
     return `KAZZLE_APP_COMPONENT_${normalized}_URL`;
@@ -22,7 +33,7 @@ function componentUrlEnvName(componentName) {
  * Kazzle preview/runtime Vite config. Spread the result into your Vite config:
  *
  *   export default defineConfig(({ command }) => ({
- *     plugins: [react(), tailwindcss()],
+ *     plugins: [react(), tailwindcss(), ...kazzleAppPwa()],
  *     ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/todos'] }),
  *   }));
  */
@@ -75,3 +86,90 @@ export function kazzleAppVite(command, options = {}) {
         },
     };
 }
+/**
+ * Dev-only: a browser that previously visited a built/PWA version of this app
+ * at the same origin still has a service worker. With `devOptions.enabled:
+ * false` we don't serve a SW in dev, so the stale SW keeps intercepting with
+ * its old precache. This plugin serves a tiny unregister script at /sw.js and
+ * /registerSW.js during `vite serve` only.
+ */
+function devUnregisterServiceWorker() {
+    const body = [
+        "self.addEventListener('install', e => self.skipWaiting());",
+        "self.addEventListener('activate', e => e.waitUntil((async () => {",
+        "  try { await self.registration.unregister(); } catch {}",
+        "  try { const keys = await caches.keys(); await Promise.all(keys.map(k => caches.delete(k))); } catch {}",
+        "  const clients = await self.clients.matchAll({ type: 'window' });",
+        "  for (const c of clients) { try { c.navigate(c.url); } catch {} }",
+        "})());",
+    ].join('\n');
+    return {
+        name: 'kazzle:dev-unregister-sw',
+        apply: 'serve',
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.method !== 'GET')
+                    return next();
+                const url = req.url?.split('?')[0];
+                if (url !== '/sw.js' && url !== '/registerSW.js')
+                    return next();
+                res.setHeader('content-type', 'application/javascript; charset=utf-8');
+                res.setHeader('cache-control', 'no-store');
+                res.end(body);
+            });
+        },
+    };
+}
+/**
+ * Keep Vite from prebundling `@kazzle/app/pwa` — that entry imports
+ * `virtual:pwa-register`, which only exists after VitePWA's resolve hooks run.
+ * Also pin `workbox-window` to the SDK install so the app root does not need
+ * its own copy (vite-plugin-pwa's virtual register imports it).
+ */
+function excludeKazzlePwaFromOptimizeDeps() {
+    const workboxWindow = requireFromSdk.resolve('workbox-window');
+    return {
+        name: 'kazzle:exclude-pwa-optimize-deps',
+        config() {
+            return {
+                optimizeDeps: {
+                    exclude: ['@kazzle/app/pwa'],
+                },
+                resolve: {
+                    alias: {
+                        'workbox-window': workboxWindow,
+                    },
+                },
+            };
+        },
+    };
+}
+/**
+ * Kazzle production PWA plugins. Spread into `plugins` next to react/tailwind:
+ *
+ *   plugins: [react(), tailwindcss(), ...kazzleAppPwa()]
+ *
+ * Always pair with `registerAppSW()` from `@kazzle/app/pwa` in main.tsx.
+ * Do not import `vite-plugin-pwa` or `virtual:pwa-register` in the app.
+ */
+export function kazzleAppPwa(options = {}) {
+    const workbox = options.workbox ?? {};
+    const pwaPlugins = VitePWA({
+        registerType: 'autoUpdate',
+        workbox: {
+            globPatterns: DEFAULT_PWA_GLOB_PATTERNS,
+            ...workbox,
+        },
+        manifest: options.manifest,
+        includeAssets: options.includeAssets,
+        // Keep disabled in dev — enabling the SW breaks Vite HMR.
+        devOptions: {
+            enabled: false,
+        },
+    });
+    return [
+        excludeKazzlePwaFromOptimizeDeps(),
+        devUnregisterServiceWorker(),
+        ...(Array.isArray(pwaPlugins) ? pwaPlugins : [pwaPlugins]),
+    ];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kazzle/app",
-  "version": "0.1.800",
+  "version": "0.1.802",
   "description": "Contracts, tool helpers, Vite helper, and templates for building Kazzle apps.",
   "license": "UNLICENSED",
   "repository": {
@@ -28,6 +28,10 @@
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
     },
+    "./pwa": {
+      "types": "./dist/pwa.d.ts",
+      "import": "./dist/pwa.js"
+    },
     "./templates": {
       "types": "./dist/templates.d.ts",
       "import": "./dist/templates.js"
@@ -52,6 +56,10 @@
     "check": "bun run scripts/build.ts && bun test src",
     "test": "bun test src"
   },
+  "dependencies": {
+    "vite-plugin-pwa": "^1.0.0",
+    "workbox-window": "^7.4.1"
+  },
   "peerDependencies": {
     "vite": ">=5",
     "zod": "^3 || ^4"

package/templates/ai-app/components/ui/src/main.tsx

@@ -1,9 +1,12 @@
 import React from 'react';
 import { createRoot } from 'react-dom/client';
+import { registerAppSW } from '@kazzle/app/pwa';
 import { App } from './App';
 import './styles/theme.css';
 import './styles/app.css';
 
+registerAppSW();
+
 createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <App />

package/templates/ai-app/components/ui/vite.config.ts

@@ -1,20 +1,20 @@
 /**
  * Vite config for the UI component.
  *
- * Kazzle preview/runtime wiring (HOST/PORT binding, strictPort, allowedHosts,
- * backend proxy) lives in @kazzle/app/vite — the ONE shared place that must
- * never be reinvented. This template declares a backend `server` component; the
+ * Kazzle owns HOST/PORT (`kazzleAppVite`) and production PWA (`kazzleAppPwa`)
+ * in `@kazzle/app/vite`. This template declares a backend `server` component; the
  * browser calls relative owned routes (/chat, /image, …) and the helper proxies
  * them to the sibling component. Add new backend routes to `proxyPaths`. Do not
  * expose Kazzle's internal component URLs to the browser.
  */
+
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
-import { kazzleAppVite } from '@kazzle/app/vite';
+import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
 
 export default defineConfig(({ command }) => ({
-  plugins: [react(), tailwindcss()],
+  plugins: [react(), tailwindcss(), ...kazzleAppPwa()],
   ...kazzleAppVite(command, {
     apiComponent: 'server',
     proxyPaths: ['/chat', '/image', '/speech', '/transcribe', '/video', '/health'],

package/templates/realtime-app/components/ui/package.json

@@ -29,8 +29,6 @@
     "@vitejs/plugin-react": "^4.5.2",
     "tailwindcss": "^4.1.0",
     "typescript": "^5.8.3",
-    "vite": "^6.3.5",
-    "vite-plugin-pwa": "^1.0.0",
-    "workbox-window": "^7.3.0"
+    "vite": "^6.3.5"
   }
 }

package/templates/realtime-app/components/ui/src/main.tsx

@@ -25,7 +25,7 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
 import { PowerSyncContext } from '@powersync/react';
-import { registerSW } from 'virtual:pwa-register';
+import { registerAppSW } from '@kazzle/app/pwa';
 import { db } from './lib/sync';
 import { AppConnector } from './lib/connector';
 import App from './App';
@@ -34,11 +34,8 @@ import './styles/theme.css';
 db.init();
 db.connect(new AppConnector());
 
-// Register the service worker in production builds only. The plugin's
-// `virtual:pwa-register` is a no-op in dev (devOptions.enabled: false).
-// `autoUpdate` swaps to a new SW as soon as one is available; subsequent
-// reloads serve from the new cache.
-registerSW({ immediate: true });
+// Production SW — owned by `@kazzle/app/pwa` + `kazzleAppPwa()` in vite.config.
+registerAppSW();
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>

package/templates/realtime-app/components/ui/src/vite-env.d.ts

@@ -1,2 +1 @@
 /// <reference types="vite/client" />
-/// <reference types="vite-plugin-pwa/client" />

package/templates/realtime-app/components/ui/vite.config.ts

@@ -1,71 +1,25 @@
 /**
  * Vite config for the UI component.
  *
- * Kazzle preview/runtime wiring (HOST/PORT binding, strictPort, allowedHosts,
- * backend proxy) lives in @kazzle/app/vite — the ONE shared place that must
- * never be reinvented. This template declares a backend `server` component
+ * Kazzle owns HOST/PORT (`kazzleAppVite`) and production PWA (`kazzleAppPwa`)
+ * in `@kazzle/app/vite`. This template declares a backend `server` component
  * (PowerSync sync endpoint); we proxy `/sync` to it via the helper. Add new
  * backend routes to `proxyPaths`.
  *
- * PWA + worker config below is realtime-specific (offline-first PowerSync) and
- * stays here on top of the shared port contract.
+ * Offline-first extras (manifest, worker format) stay here on top of the
+ * shared PWA + port contract. Do not import `vite-plugin-pwa` directly.
  */
-import { defineConfig, type Plugin } from 'vite';
+
+import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
-import { VitePWA } from 'vite-plugin-pwa';
-import { kazzleAppVite } from '@kazzle/app/vite';
-
-/**
- * Dev-only: any browser that previously visited a built/PWA-enabled version
- * of this app at the same origin still has a service worker installed. With
- * `devOptions.enabled: false` we don't serve a SW in dev, so the stale SW
- * keeps intercepting requests with its old precache and the page renders
- * without current CSS/JS. This plugin responds to /sw.js (and the PWA
- * register helper) with a tiny script that unregisters every SW, clears all
- * caches, and reloads the page once. Once cleaned, the SW is gone and Vite
- * HMR works normally. Safe to keep enabled — production builds skip this
- * plugin (the `serve` command guard).
- */
-function devUnregisterServiceWorker(): Plugin {
-  const body = [
-    "self.addEventListener('install', e => self.skipWaiting());",
-    "self.addEventListener('activate', e => e.waitUntil((async () => {",
-    "  try { await self.registration.unregister(); } catch {}",
-    "  try { const keys = await caches.keys(); await Promise.all(keys.map(k => caches.delete(k))); } catch {}",
-    "  const clients = await self.clients.matchAll({ type: 'window' });",
-    "  for (const c of clients) { try { c.navigate(c.url); } catch {} }",
-    "})());",
-  ].join('\n');
-  return {
-    name: 'kazzle:dev-unregister-sw',
-    apply: 'serve',
-    configureServer(server) {
-      server.middlewares.use((req, res, next) => {
-        if (req.method !== 'GET') return next();
-        const url = req.url?.split('?')[0];
-        if (url !== '/sw.js' && url !== '/registerSW.js') return next();
-        res.setHeader('content-type', 'application/javascript; charset=utf-8');
-        res.setHeader('cache-control', 'no-store');
-        res.end(body);
-      });
-    },
-  };
-}
+import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
 
 export default defineConfig(({ command }) => ({
   plugins: [
     react(),
     tailwindcss(),
-    devUnregisterServiceWorker(),
-    // Service worker for offline-first behavior. `devOptions.enabled: false`
-    // is intentional — enabling the SW in dev breaks Vite HMR
-    // (templates.mdc note). The SW only ships in the production build, where
-    // it pre-caches the app shell + JS bundles so reload-while-offline keeps
-    // working. PowerSync's local SQLite stays readable in both modes.
-    VitePWA({
-      registerType: 'autoUpdate',
-      devOptions: { enabled: false },
+    ...kazzleAppPwa({
       workbox: { globPatterns: ['**/*.{js,css,html,svg,png,ico}'] },
       manifest: {
         name: 'Kazzle App',

package/templates/ui-app/components/ui/package.json

@@ -23,8 +23,6 @@
     "@vitejs/plugin-react": "^4.5.2",
     "tailwindcss": "^4.1.0",
     "typescript": "^5.8.3",
-    "vite": "^6.3.5",
-    "vite-plugin-pwa": "^0.21.1",
-    "workbox-window": "^7.3.0"
+    "vite": "^6.3.5"
   }
 }

package/templates/ui-app/components/ui/src/main.tsx

@@ -11,23 +11,18 @@
  * `StrictMode` double-invokes effects in dev to catch bugs from accidental
  * state mutation. It has no effect in production builds.
  *
- * Service worker: `vite-plugin-pwa` with `registerType: 'autoUpdate'` only
- * activates/reloads when the app calls `registerSW` from
- * `virtual:pwa-register`. Leaving that out leaves a registered worker that
- * never claims updates — published builds would stay stale until a hard
- * refresh. Keep this registration; do not enable `devOptions`.
+ * Service worker: call `registerAppSW()` from `@kazzle/app/pwa` (paired with
+ * `kazzleAppPwa()` in vite.config.ts). Do not import `virtual:pwa-register`.
  */
 
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import { registerSW } from 'virtual:pwa-register';
+import { registerAppSW } from '@kazzle/app/pwa';
 import App from './App';
 import './styles/theme.css';
 
-// Production only — `virtual:pwa-register` is a no-op when
-// `devOptions.enabled: false`. `immediate: true` + autoUpdate swaps in a new
-// worker as soon as `registration.update()` (or periodic checks) finds one.
-registerSW({ immediate: true });
+// Production only — no-op in dev (`kazzleAppPwa` keeps `devOptions.enabled: false`).
+registerAppSW();
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>

package/templates/ui-app/components/ui/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/ui-app/components/ui/vite.config.ts

@@ -1,62 +1,19 @@
 /**
  * Vite config for the UI component.
  *
- * Kazzle preview/runtime wiring (HOST/PORT binding, strictPort, allowedHosts,
- * backend proxy) lives in @kazzle/app/vite — the ONE shared place that must
- * never be reinvented. This file only declares plugins and spreads
- * `kazzleAppVite(command)`. This template has no backend component, so no
- * proxy options are passed; if you add one later, pass
- * `{ apiComponent, proxyPaths }` (see @kazzle/app/vite).
+ * Kazzle owns HOST/PORT (`kazzleAppVite`) and production PWA (`kazzleAppPwa`)
+ * in `@kazzle/app/vite`. This file only declares app plugins and spreads those
+ * helpers. Do not import `vite-plugin-pwa` or `virtual:pwa-register` here —
+ * browser entry calls `registerAppSW()` from `@kazzle/app/pwa`.
  *
- * The one non-obvious thing left here: we register a service worker via
- * `vite-plugin-pwa`, but ONLY for production builds. In dev, a service worker
- * would aggressively cache module responses and break Vite's HMR. The
- * `devUnregisterServiceWorker` plugin below cleans up stale SWs left by a
- * previous built visit to the same origin. Do not enable `devOptions`.
+ * This template has no backend component, so no proxy options are passed; if
+ * you add one later, pass `{ apiComponent, proxyPaths }` (see @kazzle/app/vite).
  */
 
-import { defineConfig, type Plugin } from 'vite';
+import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
-import { VitePWA } from 'vite-plugin-pwa';
-import { kazzleAppVite } from '@kazzle/app/vite';
-
-/**
- * Dev-only: any browser that previously visited a built/PWA-enabled version
- * of this app at the same origin still has a service worker installed. With
- * `devOptions.enabled: false` we don't serve a SW in dev, so the stale SW
- * keeps intercepting requests with its old precache and the page renders
- * without current CSS/JS. This plugin responds to /sw.js (and the PWA
- * register helper) with a tiny script that unregisters every SW, clears all
- * caches, and reloads the page once. Once cleaned, the SW is gone and Vite
- * HMR works normally. Safe to keep enabled — production builds skip this
- * plugin (the `serve` command guard).
- */
-function devUnregisterServiceWorker(): Plugin {
-  const body = [
-    "self.addEventListener('install', e => self.skipWaiting());",
-    "self.addEventListener('activate', e => e.waitUntil((async () => {",
-    "  try { await self.registration.unregister(); } catch {}",
-    "  try { const keys = await caches.keys(); await Promise.all(keys.map(k => caches.delete(k))); } catch {}",
-    "  const clients = await self.clients.matchAll({ type: 'window' });",
-    "  for (const c of clients) { try { c.navigate(c.url); } catch {} }",
-    "})());",
-  ].join('\n');
-  return {
-    name: 'kazzle:dev-unregister-sw',
-    apply: 'serve',
-    configureServer(server) {
-      server.middlewares.use((req, res, next) => {
-        if (req.method !== 'GET') return next();
-        const url = req.url?.split('?')[0];
-        if (url !== '/sw.js' && url !== '/registerSW.js') return next();
-        res.setHeader('content-type', 'application/javascript; charset=utf-8');
-        res.setHeader('cache-control', 'no-store');
-        res.end(body);
-      });
-    },
-  };
-}
+import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
 
 export default defineConfig(({ command }) => ({
   plugins: [
@@ -65,13 +22,8 @@ export default defineConfig(({ command }) => ({
     // tailwind.config.js or PostCSS setup needed; tokens/primitives live in
     // src/styles/theme.css.
     tailwindcss(),
-    devUnregisterServiceWorker(),
-    VitePWA({
-      registerType: 'autoUpdate',
+    ...kazzleAppPwa({
       workbox: {
-        // Precache the static asset bundle. Network requests to anything
-        // ending in these extensions get served from cache first.
-        globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
         runtimeCaching: [
           {
             // External API responses get cached briefly and revalidated in
@@ -86,10 +38,6 @@ export default defineConfig(({ command }) => ({
           },
         ],
       },
-      // Keep disabled in dev — see header comment.
-      devOptions: {
-        enabled: false,
-      },
     }),
   ],
   // HOST/PORT/strictPort/allowedHosts — the port contract. See @kazzle/app/vite.

package/templates/ui-db-app/components/ui/src/main.tsx

@@ -1,8 +1,11 @@
 import React from 'react';
 import { createRoot } from 'react-dom/client';
+import { registerAppSW } from '@kazzle/app/pwa';
 import { App } from './App';
 import './styles/theme.css';
 
+registerAppSW();
+
 createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <App />

package/templates/ui-db-app/components/ui/vite.config.ts

@@ -1,19 +1,19 @@
 /**
  * Vite config for the UI component.
  *
- * Kazzle preview/runtime wiring (HOST/PORT binding, strictPort, allowedHosts,
- * backend proxy) lives in @kazzle/app/vite — the ONE shared place that must
- * never be reinvented. This template declares a backend `server` component, so
+ * Kazzle owns HOST/PORT (`kazzleAppVite`) and production PWA (`kazzleAppPwa`)
+ * in `@kazzle/app/vite`. This template declares a backend `server` component, so
  * we pass its name plus the relative routes the browser calls; the helper
  * proxies them to the sibling component and refuses to serve until Kazzle has
  * injected the backend URL. Add new backend routes to `proxyPaths`.
  */
+
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
-import { kazzleAppVite } from '@kazzle/app/vite';
+import { kazzleAppVite, kazzleAppPwa } from '@kazzle/app/vite';
 
 export default defineConfig(({ command }) => ({
-  plugins: [react(), tailwindcss()],
+  plugins: [react(), tailwindcss(), ...kazzleAppPwa()],
   ...kazzleAppVite(command, { apiComponent: 'server', proxyPaths: ['/categories', '/todos'] }),
 }));