@vrowzer/vite-plugin 0.1.1 → 0.1.3

package/README.md

@@ -39,12 +39,81 @@ The auto-generated manifest is available via the `virtual:vrowzer-manifest` virt
 ```ts
 import manifest from 'virtual:vrowzer-manifest'
 
-const vrowzer = Vrowzer({ basePath: '/__preview__/' })
+const vrowzer = Vrowzer()
 await vrowzer.ready({
   files: { ...manifest.files, ...manifest.nodeModules }
 })
 ```
 
+### Preview base path
+
+The plugin's `basePath` is the source of truth for the application, Web Worker, and Service Worker bundles. Configure it once in `vite.config.ts`; application code can call `Vrowzer()` without repeating the value.
+
+For a host application served from a nested Vite base:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  base: '/app/',
+  plugins: [Vrowzer({ basePath: '/app/__preview__/' })]
+})
+```
+
+```ts
+// application code
+import { Vrowzer } from 'vrowzer'
+
+const vrowzer = Vrowzer()
+```
+
+The runtime `Vrowzer({ basePath })` option remains compatible. When it is also specified, its canonical path must match the plugin value; a mismatch throws during `Vrowzer()` creation. The Service Worker registration `serviceWorkerScope` is independent of this preview URL path.
+
+### Service Worker scope
+
+The plugin's `serviceWorkerScope` is the source of truth for both Service Worker registration and the `Service-Worker-Allowed` response header. Configure it once in `vite.config.ts`; the runtime option can be omitted:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  base: '/app/',
+  plugins: [
+    Vrowzer({
+      basePath: '/app/__preview__/',
+      serviceWorkerScope: '/app/'
+    })
+  ]
+})
+```
+
+```ts
+// application code
+import { Vrowzer } from 'vrowzer'
+
+const vrowzer = Vrowzer()
+```
+
+The runtime `Vrowzer({ serviceWorkerScope })` option remains available for compatibility and for builds without the plugin. If both values are provided, they must match or `Vrowzer()` throws before registration. Without either value, the scope and response header default to `/`.
+
+### Service Worker version
+
+The plugin's `serviceWorkerVersion` is the source of truth for the version expected by the application and reported by the Service Worker. Configure it once in `vite.config.ts`; application code can call `Vrowzer()` without repeating the value:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [Vrowzer({ serviceWorkerVersion: 'app-v2' })]
+})
+```
+
+```ts
+// application code
+import { Vrowzer } from 'vrowzer'
+
+const vrowzer = Vrowzer()
+```
+
+The runtime `Vrowzer({ serviceWorkerVersion })` option remains available for compatibility and for builds without the plugin. If both values are provided, they must match or `Vrowzer()` throws before Service Worker registration. Without either value, the version defaults to `vrowzer-v1`. The resolved version is also reflected in the Service Worker script URL, so changing it may trigger a Service Worker update.
+
 When the host page and preview content are in different directories, use `manifest.sourceDir`:
 
 ```ts
@@ -140,12 +209,12 @@ Vrowzer({
   // Default: '/__preview__/'
   basePath: '/__preview__/',
 
-  // Service Worker scope
+  // Service Worker registration scope and allowed response header
   // Default: '/'
   serviceWorkerScope: '/',
 
   // Service Worker version for cache management
-  // Default: 'SERVICE_WORKER_VERSION'
+  // Default: 'vrowzer-v1'
   serviceWorkerVersion: 'my-app-v1',
 
   // Explicit Service Worker entry file path
@@ -165,9 +234,9 @@ Vrowzer({
 | `auto`                 | `boolean`                    | `true`                                    | Enable auto manifest generation. Set `false` to use `VrowzerManifest()` manually.         |
 | `manifest`             | `VrowzerManifestOptions`     | `undefined`                               | Auto manifest options (sourceDir, pkgDir, targets). Used when `auto: true`.               |
 | `experimental`         | `VrowzerExperimentalOptions` | `undefined`                               | Experimental features. Currently supports `ide`.                                          |
-| `basePath`             | `string`                     | `'/__preview__/'`                         | Base path for the preview system. The Service Worker intercepts requests under this path. |
-| `serviceWorkerScope`   | `string`                     | `'/'`                                     | The scope for the Service Worker registration.                                            |
-| `serviceWorkerVersion` | `string`                     | `'SERVICE_WORKER_VERSION'`                | Version string for Service Worker cache management.                                       |
+| `basePath`             | `string`                     | `'/__preview__/'`                         | Preview URL pathname shared with the application and Service Worker bundles.              |
+| `serviceWorkerScope`   | `string`                     | `'/'`                                     | Registration scope and `Service-Worker-Allowed` header injected into the runtime.          |
+| `serviceWorkerVersion` | `string`                     | `'vrowzer-v1'`                            | Version shared with the application and Service Worker bundles.                           |
 | `serviceWorkerEntry`   | `string`                     | Resolved path to `vrowzer/service-worker` | Explicit Service Worker entry file path.                                                  |
 | `resolve`              | `{ alias?: Alias[] }`        | `undefined`                               | Worker-specific resolve settings passed to the internal Vite dev server.                  |
 
@@ -214,6 +283,7 @@ Auto-extracts user plugins from `vite.config.ts` using OXC parser, then pre-bund
 - Resolves `@vrowzer/*` imports from the plugin's own dependency graph
 - Inlines `readFileSync()` and `createRequire()` calls for Worker compatibility
 - Maps `vite` imports to `@vrowzer/vite-dev-server/vite`
+- Excludes `@vrowzer/vite-dev-server` from host dependency pre-bundling while keeping `vrowzer` optimizable
 
 #### 3. Preview Guard Middleware (`vrowzer:server-middleware`)
 
@@ -232,7 +302,7 @@ Sets up Vite configuration for the browser-based Vite dev server:
 
 - **`resolve.alias`** — Maps Node.js built-in modules (`node:fs`, `node:path`, `node:events`, etc.) to browser-compatible polyfills
 - **`worker.format`** — Set to `'es'` for ES Module workers
-- **CORS headers** — `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: credentialless`, plus `Service-Worker-Allowed: /`
+- **CORS headers** — `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: credentialless`, plus `Service-Worker-Allowed` matching `serviceWorkerScope` (default `/`)
 
 #### 6. Rolldown WASM Copy (`vrowzer:rolldown`)