worker-loader

library3.0.8jsnpmunverified

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.

devops

npm install worker-loader

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WORKER-LOADER

worker-loader

devopsjavascriptv3.0.8

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.

worker-loader

✓ import Worker from 'worker-loader!./Worker.js';

✗ const Worker = require('worker-loader!./Worker.js');

Inline syntax. In webpack 5, using inline loader syntax may cause deprecation warnings; prefer config-based approach.

Worker

✓ import Worker from './file.worker.js';

✗ const Worker = require('./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.

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);

Debug

Known issues

breakingIn 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.

affects: >=3.0.0

breakingv3.0.0 dropped support for Node.js < 10.13 and webpack < 4.

fix

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

affects: >=3.0.0

breakingv3.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.

affects: >=3.0.0

breakingv3.0.0 removed the 'fallback' option; replaced by 'inline' option.

fix

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

affects: >=3.0.0

gotchaInline 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.

affects: *

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

fix

Upgrade worker-loader to >=3.0.1.

affects: <3.0.1

Errors

Common errors & fixes

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

worker-loader is not installed or not in devDependencies.

fix

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

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'.

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

fix

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

TypeError: Worker is not a constructor

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.

Cannot find module 'worker-loader'

Missing dependency or incorrect path in inline loader syntax.

fix

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

Upgrade

Version history

3.0.8latest on npm

Audit

Dependencies

webpackoptionalpeer dependency - loader is designed to work with webpack 4 or 5

Agent activity

17 hits · last 30 days

node

Resources

githubhttps://github.com/webpack-contrib/worker-loader ↗

packagehttps://www.npmjs.com/package/worker-loader ↗

homepagehttps://webpack.js.org/loaders/worker-loader/ ↗