Registry / devops / esbuild-plugin-node-worker

esbuild-plugin-node-worker

library1.0.8jsnpmunverified

An esbuild plugin that automatically detects and bundles Node.js Web Workers used in your source code. Version 1.0.8, stable maintenance. Workers are emitted as separate chunks into a workers/ directory with content hashing to avoid name collisions. It relies on the first string literal argument to Worker constructors being a relative path, supporting both ESM (new URL) and CJS (path.join). Differentiators: minimal configuration needed (just add the plugin), works with extended Worker classes, and integrates directly into esbuild's build pipeline. Peer dependency on esbuild. Ships TypeScript types.

devops

npm install esbuild-plugin-node-worker

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-NOD

esbuild-plugin-node-worker

devopsjavascriptv1.0.8

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

nodeWorker

✓ import { nodeWorker } from 'esbuild-plugin-node-worker'

✗ import nodeWorker from 'esbuild-plugin-node-worker'

Named export, not default. CommonJS require: const { nodeWorker } = require('esbuild-plugin-node-worker')

nodeWorker

✓ const { nodeWorker } = require('esbuild-plugin-node-worker')

✗ const nodeWorker = require('esbuild-plugin-node-worker')

CommonJS require must destructure the named export

type NodeWorkerOptions

✓ import type { NodeWorkerOptions } from 'esbuild-plugin-node-worker'

TypeScript type export available for configuring the plugin if needed

Shows minimal setup: import nodeWorker, add to esbuild plugins array, bundle for Node.js.

import { nodeWorker } from 'esbuild-plugin-node-worker'; import esbuild from 'esbuild'; await esbuild.build({ entryPoints: ['src/index.ts'], bundle: true, outdir: 'dist', platform: 'node', format: 'esm', plugins: [nodeWorker], });

esbuild --version

Debug

Known issues

gotchaOnly the first string literal argument in the Worker constructor is treated as the worker path. Dynamic paths or non-string first arguments are ignored.

fix

Ensure your worker path is a string literal, e.g., new Worker(new URL('./worker.mjs', import.meta.url)) or new Worker(path.join(__dirname, 'worker.cjs')).

affects: *

gotchaThe plugin does not work with workers created via a variable or require call (e.g., new Worker(require('path').join(...))).

fix

Use a direct path.join with string literals or new URL with string literal path.

affects: *

gotchaWorkers are emitted into a workers/ directory. Ensure your output directory structure does not interfere with expected worker paths at runtime.

fix

If your worker references assume a flat output, adjust paths or use publicPath option.

affects: *

Errors

Common errors & fixes

Error: Cannot find module './worker.mjs'

The plugin emitted the worker in 'workers/' subdirectory, but the runtime code expects it in the same directory as the entry.

fix

Update your worker constructor to use a relative path from the output directory, or use the plugin's 'publicPath' option if available.

TypeError: nodeWorker is not a function

Importing the plugin as default instead of named export.

fix

Use import { nodeWorker } from 'esbuild-plugin-node-worker' or const { nodeWorker } = require('esbuild-plugin-node-worker').

Error: Build failed with 1 error: error: No matching worker found

The plugin could not find a Worker constructor call with a string literal first argument.

fix

Check that your worker instantiation uses a string literal relative path as the first argument, e.g., new Worker(new URL('./worker.js', import.meta.url)).

Upgrade

Version history

1.0.8latest on npm

Audit

Dependencies

esbuildrequiredpeer dependency; plugin runs within esbuild's build system

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/s-h-a-d-o-w/esbuild-plugin-node-worker ↗

packagehttps://www.npmjs.com/package/esbuild-plugin-node-worker ↗