Registry / web-framework / vite-plugin-prebundle-workers

vite-plugin-prebundle-workers

library1.0.0jsnpmunverified

A Vite plugin that bundles classic web workers during development, mirroring build-time behavior. Current stable version is 1.0.0, released with a single patch update. Key differentiator: it ensures workers are bundled in dev, preventing issues like missing imports that occur when using raw `new Worker(new URL(...))` patterns. Lightweight and simple, it builds on esbuild for fast bundling. Alternatives like `vite-plugin-worker` or manual handling are more complex or don't cover dev-time bundling. Includes filtering options via `include`/`exclude`.

web-framework devops

npm install vite-plugin-prebundle-workers

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-PREBUN

vite-plugin-prebundle-workers

web-frameworkjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

prebundleWorkers

✓ import prebundleWorkers from 'vite-plugin-prebundle-workers'

✗ const prebundleWorkers = require('vite-plugin-prebundle-workers')

ESM-only; CommonJS require will fail. This is the default export.

PluginOptions

✓ import type { PluginOptions } from 'vite-plugin-prebundle-workers'

✗ import { PluginOptions } from 'vite-plugin-prebundle-workers'

PluginOptions is a TypeScript type; use `import type` for type-only imports.

configureEsBuild

✓ prebundleWorkers({ configureEsBuild(id, config) { ... } })

✗ prebundleWorkers({ configureEsBuild: (id, config) => { ... } })

configureEsBuild is not imported; it's a property of the options object passed to prebundleWorkers().

Configures the plugin to bundle .worker.ts files during dev, with custom esbuild define.

// vite.config.js import { defineConfig } from 'vite'; import prebundleWorkers from 'vite-plugin-prebundle-workers'; export default defineConfig({ plugins: [ prebundleWorkers({ include: 'src/**/*.worker.ts', configureEsBuild(id, config) { // Custom esbuild options config.define = { 'process.env.NODE_ENV': '"development"' }; return config; } }) ] });

Debug

Known issues

gotchaOne of `include` or `exclude` must be provided, otherwise the plugin throws an error.

fix

Always specify either `include` or `exclude` option.

affects: >=1.0.0

gotchaThe plugin only affects workers created via `new Worker(new URL(...), import.meta.url)`; other patterns may not be bundled.

fix

Use the standard Vite worker pattern: `new Worker(new URL('./worker.ts', import.meta.url))`.

affects: >=1.0.0

gotchaIf using Vite's built-in worker handling (e.g., `?worker` suffix), the plugin may conflict or double-bundle.

fix

Avoid mixing the plugin with Vite's native worker imports; use one approach.

affects: >=1.0.0

breakingWorker scripts bundled by this plugin run in a separate context and do not have access to Vite's module graph (e.g., HMR).

fix

Treat workers as separate bundles; do not rely on Vite HMR inside workers.

affects: >=1.0.0

gotchaThe plugin does not support dynamic imports or all esbuild features; configureEsBuild only passes a subset of options.

fix

Check esbuild documentation for supported options; test your worker's imports.

affects: >=1.0.0

Errors

Common errors & fixes

Error: You must provide either `include` or `exclude`

Neither `include` nor `exclude` was specified in the plugin options.

fix

Add `include: 'src/**/*.worker.ts'` or an appropriate pattern to the plugin options.

SyntaxError: Cannot use import statement outside a module

Worker script uses ES imports but is not being bundled by the plugin.

fix

Ensure the worker path matches the `include` pattern and that the plugin is properly configured.

ReferenceError: process is not defined

Worker code references Node.js globals like `process` that are not available in the web worker context.

fix

Use esbuild `define` in `configureEsBuild` to replace `process.env`, or remove Node-specific references.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

@rollup/pluginutilsrequiredUsed for file filtering (include/exclude patterns)

esbuildrequiredUsed to bundle workers during development

viterequiredPeer dependency; plugin requires Vite as the host environment

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/itsjohncs/vite-plugin-prebundle-workers ↗

packagehttps://www.npmjs.com/package/vite-plugin-prebundle-workers ↗