worker-loader

3.0.8 verified Sat Apr 25 auth: no javascript

Webpack loader for bundling Web Workers as separate files or inline blobs. Version 3.0.8 is the latest stable release (Feb 2021). Actively maintained as part of the webpack-contrib ecosystem. Key differentiators: supports inline workers via BLOB to avoid separate HTTP requests, allows customization of worker constructor (Worker/SharedWorker), and provides fine-grained control over filename, publicPath, and esModule output. Requires webpack 4 or 5 and Node >=10.13.

Common errors

error Module not found: Error: Can't resolve 'worker-loader' ↓

cause worker-loader is not installed or not in devDependencies.

fix

Run 'npm install worker-loader --save-dev'.

error Error: [webpack-cli] Invalid configuration object. webpack has been initialized using a configuration object that does not match the API schema. - configuration.module.rules[0].use has an unknown property 'name'. ↓

cause Using the old 'name' option which was renamed to 'filename' in v3.

fix

Change 'name' to 'filename' in worker-loader options.

error TypeError: Worker is not a constructor ↓

cause The imported module does not export a constructor; likely using wrong import syntax or outdated config.

fix

Ensure you are using 'import MyWorker from './file.worker.js'' (ESM) and that the file matches the rule pattern.

error Cannot find module 'worker-loader' ↓

cause Missing dependency or incorrect path in inline loader syntax.

fix

Install worker-loader and use correct inline syntax: 'worker-loader!./file.js'.

Warnings

breaking In v3.0.0, the 'name' option was renamed to 'filename'. Using 'name' will cause an error. ↓

fix Replace 'name' with 'filename' in your worker-loader options.

breaking v3.0.0 dropped support for Node.js < 10.13 and webpack < 4. ↓

fix Upgrade Node.js to >=10.13 and webpack to >=4.

breaking v3.0.0 switched to ES module syntax by default. Old CommonJS imports may break. ↓

fix Use import instead of require, or set options.esModule to false for backward compatibility.

breaking v3.0.0 removed the 'fallback' option; replaced by 'inline' option. ↓

fix Use 'inline: 'fallback'' or 'inline: 'no-fallback'' instead of 'fallback'.

gotcha Inline workers (blob) may not work in some CSP (Content Security Policy) environments that restrict blobs. ↓

fix Use a separate file worker instead of inline, or adjust CSP to allow blob: scripts.

gotcha When using webpack 5 with persistent caching, ensure worker-loader is compatible (fixed in 3.0.1). ↓

fix Upgrade worker-loader to >=3.0.1.

Install

npm install worker-loader

yarn add worker-loader

pnpm add worker-loader

Imports

worker-loader
wrong
```
const Worker = require('worker-loader!./Worker.js');
```
correct
```
import Worker from 'worker-loader!./Worker.js';
```
Inline syntax. In webpack 5, using inline loader syntax may cause deprecation warnings; prefer config-based approach.
Worker
wrong
```
const Worker = require('./file.worker.js');
```
correct
```
import Worker from './file.worker.js';
```
When using config rule for .worker.js files. Since v3, esModule defaults to true, so ESM import is expected.
SharedWorker
```
const worker = new SharedWorker();
```
Set via options.worker: 'SharedWorker' or { type: 'SharedWorker' }. Not imported separately.

Quickstart

Shows basic webpack config to automatically bundle .worker.js files as Web Workers, and how to import and use the worker in app code.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.worker\.js$/,
        use: { loader: 'worker-loader' }
      }
    ]
  }
};

// src/app.js
import MyWorker from './my.worker.js';
const worker = new MyWorker();
worker.postMessage({ hello: 'world' });
worker.onmessage = (e) => console.log(e.data);