@vrowzer/vite-plugin

Vite plugin for vrowzer - browser-based Vite dev server preview system.

This plugin configures Vite for running @vrowzer/vite-dev-server in Service Worker and Web Worker environments. It handles auto manifest generation, Node.js polyfills, CORS headers, process global injection, WASM file copying, Worker config extraction/prebundling, Service Worker bundling, and an experimental browser IDE.

💿 Installation

# npm
npm install -D @vrowzer/vite-plugin

# pnpm
pnpm add -D @vrowzer/vite-plugin

# yarn
yarn add -D @vrowzer/vite-plugin

🚀 Usage

Auto mode (default)

The plugin automatically generates a manifest from the project's package.json dependencies and source files. No manual manifest file or VrowzerManifest() plugin is needed.

// vite.config.ts
import vue from '@vitejs/plugin-vue'
import { Vrowzer } from '@vrowzer/vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [vue(), Vrowzer()]
})

The auto-generated manifest is available via the virtual:vrowzer-manifest virtual module:

import manifest from 'virtual:vrowzer-manifest'

const vrowzer = Vrowzer({ basePath: '/__preview__/' })
await vrowzer.ready({
  files: { ...manifest.files, ...manifest.nodeModules }
})

When the host page and preview content are in different directories, use manifest.sourceDir:

Vrowzer({
  manifest: {
    sourceDir: './app', // scan ./app/ for preview content
    targets: ['vue'] // only include vue (+ transitive deps)
  }
})

Manual mode

For advanced use cases (e.g. multiple fixtures), disable auto mode and use VrowzerManifest() with a manually created vrowzer-manifest.json.

// vite.config.ts
import { Vrowzer, VrowzerManifest } from '@vrowzer/vite-plugin'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [VrowzerManifest(), Vrowzer({ auto: false })]
})

Browser IDE (experimental)

Enable the browser IDE to get a full development environment at /__vrowzer__/ with File Explorer, Monaco Editor, and live Preview.

Vrowzer({
  manifest: {
    sourceDir: './app',
    targets: ['vue']
  },
  experimental: { ide: true }
})

The IDE is a pre-built Vue app bundled into the plugin (no additional dependencies required). It includes:

• File Explorer with vscode-icons
• Monaco Editor with web language support (HTML, CSS, JS, TS, Vue, etc.)
• Live Preview powered by vrowzer (HMR via Web Worker + Service Worker)
• File sync via birpc WebSocket (edits are saved to local filesystem)

On vite dev, the IDE URL is printed in the console:

  ➜  Local:   http://localhost:5173/
  ➜  Vrowzer IDE: http://localhost:5173/__vrowzer__/

You can also specify a custom port for the birpc WebSocket server:

Vrowzer({
  experimental: {
    ide: { port: 7900 }
  }
})

⚙️ Options

Vrowzer({
  // Enable auto manifest generation
  // Default: true
  auto: true,

  // Auto manifest options (used when auto: true)
  manifest: {
    // Directory to scan for source files (index.html, src/, public/)
    // Default: Vite project root
    sourceDir: './app',
    // Package directory for node_modules resolution
    // Default: Vite project root
    pkgDir: '.',
    // Package name(s) to include in nodeModules
    // Default: all dependencies
    targets: ['vue']
  },

  // Experimental features
  experimental: {
    // Enable browser IDE at /__vrowzer__/
    // Default: false
    ide: true // or { port: 7900 }
  },

  // Base path for the preview system
  // Default: '/__preview__/'
  basePath: '/__preview__/',

  // Service Worker scope
  // Default: '/'
  serviceWorkerScope: '/',

  // Service Worker version for cache management
  // Default: 'SERVICE_WORKER_VERSION'
  serviceWorkerVersion: 'my-app-v1',

  // Explicit Service Worker entry file path
  // Default: Resolved path to 'vrowzer/service-worker'
  serviceWorkerEntry: 'vrowzer/service-worker',

  // Worker-specific resolve settings
  // Default: undefined
  resolve: {
    alias: [{ find: 'my-lib', replacement: '/libs/my-lib.js' }]
  }
})

| Option | Type | Default | Description | | ---------------------- | ---------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------- | | 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. | | 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. |

VrowzerManifestOptions

| Option | Type | Default | Description | | ----------- | ---------- | ----------------- | ----------------------------------------------------------------------- | | sourceDir | string | Vite project root | Directory to scan for project source files (index.html, src/, public/). | | pkgDir | string | Vite project root | Package directory for node_modules resolution. | | targets | string[] | all dependencies | Package name(s) to include. Only these packages + transitive deps. |

VrowzerExperimentalOptions

| Option | Type | Default | Description | | ------ | ------------------------------ | ------- | ---------------------------------------------------------------- | | ide | boolean \| VrowzerIdeOptions | false | Enable browser IDE at /__vrowzer__/. true uses all defaults. |

VrowzerIdeOptions

| Option | Type | Default | Description | | ------ | -------- | ------- | ------------------------------------ | | port | number | auto | Port for the birpc WebSocket server. |

🔌 Exported Plugins

Vrowzer(options?)

Returns an array of Vite plugins that configure the environment for vrowzer:

1. Auto Manifest Generation (vrowzer:auto-manifest)

When auto: true (default), automatically generates a vrowzer manifest in configResolved:

• Scans project source files (index.html, src/, public/)
• Collects npm dependencies from package.json
• Auto-bundles CJS packages to ESM using Rolldown
• Caches results in node_modules/.vrowzer-manifest/ (keyed by deps + lockfile hash)
• Provides virtual:vrowzer-manifest virtual module with file contents resolved

2. Worker Config Extraction & Prebundling (vrowzer:config)

Auto-extracts user plugins from vite.config.ts using OXC parser, then pre-bundles them with Rolldown for the Web Worker environment. The prebundled config is written to node_modules/.vrowzer/config.bundled.mjs.

• 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

3. Preview Guard Middleware (vrowzer:server-middleware)

Prevents Vite's SPA fallback from serving index.html for basePath requests when the Service Worker is not yet active. Returns a 503 with auto-retry instead.

4. Process Global Injection

Injects process polyfill (@vrowzer/node-polyfill/process) for browser/Worker environments:

• Dev mode: Uses @rollup/plugin-inject
• Build mode: Uses Rolldown's native transform.inject

5. Environment Configuration (vrowzer:env)

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

6. Rolldown WASM Copy (vrowzer:rolldown)

Copies @vrowzer/rolldown WASM binary and sub-worker to dist/assets/ during production builds.

7. Service Worker Bundling

Uses @vrowzer/unplugin-service-worker to detect, bundle, and deploy the Service Worker with ESM format.

8. Browser IDE (vrowzer:ide)

When experimental.ide is enabled (dev mode only):

• Serves a pre-built Vue app at /__vrowzer__/ with File Explorer, Monaco Editor, and Preview
• Provides /__vrowzer__/client.js virtual module that imports vrowzer and virtual:vrowzer-manifest
• Starts a birpc WebSocket server for file sync (write-back edits to local filesystem)
• Watches for external file changes via Vite's chokidar watcher and pushes updates to the IDE

VrowzerManifest()

Transforms vrowzer-manifest.json imports (with ?vrowzer query suffix) by reading referenced files and embedding their contents into the imported object. Supports files and nodeModules fields. JS files in nodeModules are automatically minified with OXC (minifySync) to reduce bundle size.

Used in manual mode (auto: false) with a pre-generated vrowzer-manifest.json file.

// Import with ?vrowzer query to trigger content resolution
import manifest from './vrowzer-manifest.json?vrowzer'

generateManifest(options, log?)

Core manifest generation function, also available as a standalone export from @vrowzer/vite-plugin/manifest-generate. Used internally by the auto manifest plugin and by scripts/generate-manifest.ts.

import { generateManifest } from '@vrowzer/vite-plugin/manifest-generate'

const manifest = await generateManifest({
  pkgDir: '/path/to/project',
  sourceDir: '/path/to/project',
  targets: ['vue'],
  name: 'My App'
})

🤝 Sponsors

©️ License

MIT