worker-plugin

5.0.1 verified Sat Apr 25 auth: no javascript

Webpack plugin that automatically bundles and compiles Web Workers (including SharedWorkers) integrated into your build. Version 5.0.1 supports both Webpack 4 and 5, with fixes for malformed options objects. It simplifies worker usage by allowing standard `new Worker('./worker.js', { type: 'module' })` syntax, which works without bundling but becomes universally compatible when bundled. Unlike Webpack 5's built-in worker support (which uses `new URL` syntax), worker-plugin uses the more traditional approach and adds SharedWorker support. It does not require runtime changes and supports ESM modules in workers.

Common errors

error Error: Module not found: Error: Can't resolve './worker.js' ↓

cause The worker file path is incorrect or not handled by webpack loaders.

fix

Ensure the worker filename is a string literal and the path is relative to the current module. For TypeScript, use .ts extension: new Worker('./worker.ts', { type: 'module' })

error Warning: WorkerPlugin: No workers found. Ensure you are using `new Worker(fileURL)` syntax with a string argument. ↓

cause The plugin did not detect any Worker constructor calls with string arguments and { type: 'module' }.

fix

Double-check that you are using the exact syntax: new Worker('./path.js', { type: 'module' }). Dynamic variables or missing module type will not be bundled.

error Error: WorkerPlugin: SharedWorker is not supported in this version of Webpack ↓

cause SharedWorker support requires webpack 5.

fix

Upgrade to webpack 5 or disable sharedWorker option in WorkerPlugin.

Warnings

breaking In v3.0.0, plugins are no longer inherited by default. You must explicitly pass plugins via the 'plugins' option if you need them in worker compilation. ↓

fix Use the 'plugins' option to specify which plugins to apply to workers, e.g., new WorkerPlugin({ plugins: ['SomePlugin'] })

deprecated Webpack 5 now includes built-in worker bundling. worker-plugin is still useful for SharedWorker support and simpler syntax, but consider migrating to Webpack 5's native support using `new Worker(new URL('./worker.js', import.meta.url))`. ↓

fix Evaluate whether to migrate to Webpack 5's built-in worker support or continue using this plugin.

gotcha WorkerPlugin only bundles workers with string URL/filename arguments. Dynamic URLs, Blob URLs, data URLs, or not providing { type: 'module' } will leave the worker unmodified and print a warning. ↓

fix Ensure you always pass a static string filename and { type: 'module' } option to the Worker constructor.

gotcha If output.filename is set to a static name (e.g., 'bundle.js'), multiple workers will overwrite each other's output files. ↓

fix Set output.filename to a dynamic pattern like '[name].bundle.js' to give each worker a unique filename.

gotcha Setting output.globalObject to 'window' (common for web targets) breaks Hot Module Replacement in workers. WorkerPlugin will emit a warning. ↓

fix Either avoid setting globalObject to 'window' or pass globalObject: false to WorkerPlugin to suppress the warning.

Install

npm install worker-plugin

yarn add worker-plugin

pnpm add worker-plugin

Imports

WorkerPlugin
wrong
```
import WorkerPlugin from 'worker-plugin';
```
correct
```
const WorkerPlugin = require('worker-plugin');
```
CommonJS require is the default and recommended usage. ESM import is not supported by the package.
WorkerPlugin (ESM)
wrong
```
const WorkerPlugin = require('worker-plugin').default;
```
correct
```
import WorkerPlugin from 'worker-plugin';
```
If using ESM, the default import works as the package exports a single function. Do not try to use .default with CommonJS.
WorkerPlugin (TypeScript)
wrong
```
const WorkerPlugin = require('worker-plugin');
```
correct
```
import WorkerPlugin from 'worker-plugin';
```
TypeScript users should use default import for type inference. The package provides types.

Quickstart

Shows basic setup: install worker-plugin, add to webpack config, create a simple worker module and invoke it from main thread.

const WorkerPlugin = require('worker-plugin');

// webpack.config.js
module.exports = {
  output: {
    filename: '[name].bundle.js'
  },
  plugins: [
    new WorkerPlugin()
  ]
};

// In your application code:
// worker.js
self.addEventListener('message', event => {
  self.postMessage('Hello from worker');
});

// main.js
const worker = new Worker('./worker.js', { type: 'module' });
worker.onmessage = event => console.log(event.data);
worker.postMessage('');