web-worker

library1.5.0jsnpmunverified

`web-worker` is a JavaScript library providing a consistent, cross-platform Web Worker API that operates natively in both browser environments and Node.js. It achieves this by aliasing to the browser's native `Worker` constructor when bundled for the browser and implementing a web-compatible `Worker` atop Node.js's `worker_threads` module. The current stable version is 1.5.0, with a fairly active release cadence addressing bug fixes, compatibility improvements, and new features like Bun support and `importScripts()`. Key differentiators include its ability to make worker code compatible across environments, native support for Module Workers in Node 12.8+, use of DOM-style events (`Event.data`, `Event.type`), support for event handler properties (`worker.onmessage`), and acceptance of module, Blob, or Data URLs. It also emulates `WorkerGlobalScope` within the worker context, offering a familiar environment for developers.

http-networking

npm install web-worker

github ↗package ↗

INSTALL

IMPORT

SIG · WEB-WORKER

web-worker

http-networkingjavascriptv1.5.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–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Worker

✓ import Worker from 'web-worker';

✗ import { Worker } from 'web-worker';

This is the primary way to import the Worker constructor when using ES Modules. `Worker` is a default export.

Worker

✓ const Worker = require('web-worker');

✗ import Worker from 'web-worker';

For CommonJS environments (e.g., in Node.js files without `type: 'module'` in package.json), `require()` is used. Using `import` in a CJS context will result in a syntax error.

WorkerOptions

✓ import type { WorkerOptions } from 'web-worker';

✗ import { WorkerOptions } from 'web-worker';

`WorkerOptions` is a TypeScript type defining the optional second argument for the `Worker` constructor, not a runtime value. It should be imported using `import type`.

This example demonstrates how to create and communicate with a simple Web Worker, handling file creation and cleanup, suitable for both browser and Node.js environments.

import Worker from 'web-worker'; import { readFileSync, writeFileSync, unlinkSync } from 'fs'; import { URL } from 'url'; import path from 'path'; async function runWorkerExample() { const workerContent = ` addEventListener('message', e => { if (e.data === 'hello') { postMessage('hiya!'); } }); `; // Create a temporary worker file const workerFilePath = path.join(__dirname, 'temp-worker.js'); writeFileSync(workerFilePath, workerContent); try { // Resolve worker path relative to the current module const workerUrl = new URL('./temp-worker.js', import.meta.url); const worker = new Worker(workerUrl); worker.addEventListener('message', e => { console.log('Main thread received:', e.data); // Expected: "hiya!" worker.terminate(); unlinkSync(workerFilePath); // Clean up the temporary worker file }); worker.postMessage('hello'); } catch (error) { console.error('Worker example failed:', error); unlinkSync(workerFilePath); // Ensure cleanup even on error } } // Run the example runWorkerExample();

Debug

Known issues

breakingBeginning with version 1.4.1, `web-worker` officially dropped support for Node.js versions 12 and 14 from its CI, potentially leading to unforeseen issues or lack of official compatibility on these environments.

fix

Upgrade Node.js to version 16 or higher for full compatibility and official support.

affects: >=1.4.1

gotchaWhen instantiating a `Worker` with a relative path in Node.js, `web-worker` by default resolves the URL relative to `process.cwd()`. This often leads to incorrect worker file loading if your application's working directory is not the worker's parent directory.

fix

Always use `new URL('./worker.js', import.meta.url)` to correctly resolve worker paths relative to the current module, ensuring consistent behavior across environments and preventing path resolution errors.

affects: <all versions>

gotchaPrior to version 1.4.0, users reported issues with CommonJS and ES Module compatibility when importing `web-worker` or within worker scripts themselves, leading to `ReferenceError` or module resolution problems in certain setups.

fix

Ensure `web-worker` is at least version 1.4.0, which includes compatibility fixes. If using mixed CJS/ESM environments, verify your build tooling properly handles module interop or consider standardizing on a consistent module type.

affects: <1.4.0

Errors

Common errors & fixes

ReferenceError: Worker is not defined in shared worker

A bug in `web-worker`'s implementation for shared workers in Node.js or older versions prevented the `Worker` global from being properly defined within the shared worker's scope.

fix

Upgrade `web-worker` to version 1.4.0 or higher, which includes a specific fix for this `ReferenceError` in shared worker contexts.

Error: ENOENT: no such file or directory, stat '/path/to/project/worker.js'

This error typically occurs in Node.js when a worker script's path is not resolved correctly. `web-worker` by default resolves relative paths from `process.cwd()`, not the calling module's directory, leading to the file not being found.

fix

Instantiate the worker with `new Worker(new URL('./worker.js', import.meta.url))` to ensure the worker script's path is resolved relative to the current module, providing consistent behavior across environments.

Upgrade

Version history

1.5.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/developit/web-worker ↗

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