{"id":22781,"library":"vite-plugin-prebundle-workers","title":"Vite Plugin Prebundle Workers","description":"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`.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/itsjohncs/vite-plugin-prebundle-workers","tags":["javascript","plugin","utility","worker","webworker","vite","vite-plugin"],"install":[{"cmd":"npm install vite-plugin-prebundle-workers","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-prebundle-workers","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-prebundle-workers","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for file filtering (include/exclude patterns)","package":"@rollup/pluginutils","optional":false},{"reason":"Used to bundle workers during development","package":"esbuild","optional":false},{"reason":"Peer dependency; plugin requires Vite as the host environment","package":"vite","optional":false}],"imports":[{"note":"ESM-only; CommonJS require will fail. This is the default export.","wrong":"const prebundleWorkers = require('vite-plugin-prebundle-workers')","symbol":"prebundleWorkers","correct":"import prebundleWorkers from 'vite-plugin-prebundle-workers'"},{"note":"PluginOptions is a TypeScript type; use `import type` for type-only imports.","wrong":"import { PluginOptions } from 'vite-plugin-prebundle-workers'","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'vite-plugin-prebundle-workers'"},{"note":"configureEsBuild is not imported; it's a property of the options object passed to prebundleWorkers().","wrong":"prebundleWorkers({ configureEsBuild: (id, config) => { ... } })","symbol":"configureEsBuild","correct":"prebundleWorkers({ configureEsBuild(id, config) { ... } })"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite';\nimport prebundleWorkers from 'vite-plugin-prebundle-workers';\n\nexport default defineConfig({\n  plugins: [\n    prebundleWorkers({\n      include: 'src/**/*.worker.ts',\n      configureEsBuild(id, config) {\n        // Custom esbuild options\n        config.define = { 'process.env.NODE_ENV': '\"development\"' };\n        return config;\n      }\n    })\n  ]\n});","lang":"javascript","description":"Configures the plugin to bundle .worker.ts files during dev, with custom esbuild define."},"warnings":[{"fix":"Always specify either `include` or `exclude` option.","message":"One of `include` or `exclude` must be provided, otherwise the plugin throws an error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use the standard Vite worker pattern: `new Worker(new URL('./worker.ts', import.meta.url))`.","message":"The plugin only affects workers created via `new Worker(new URL(...), import.meta.url)`; other patterns may not be bundled.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid mixing the plugin with Vite's native worker imports; use one approach.","message":"If using Vite's built-in worker handling (e.g., `?worker` suffix), the plugin may conflict or double-bundle.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Treat workers as separate bundles; do not rely on Vite HMR inside workers.","message":"Worker scripts bundled by this plugin run in a separate context and do not have access to Vite's module graph (e.g., HMR).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Check esbuild documentation for supported options; test your worker's imports.","message":"The plugin does not support dynamic imports or all esbuild features; configureEsBuild only passes a subset of options.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add `include: 'src/**/*.worker.ts'` or an appropriate pattern to the plugin options.","cause":"Neither `include` nor `exclude` was specified in the plugin options.","error":"Error: You must provide either `include` or `exclude`"},{"fix":"Ensure the worker path matches the `include` pattern and that the plugin is properly configured.","cause":"Worker script uses ES imports but is not being bundled by the plugin.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Use esbuild `define` in `configureEsBuild` to replace `process.env`, or remove Node-specific references.","cause":"Worker code references Node.js globals like `process` that are not available in the web worker context.","error":"ReferenceError: process is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}