esbuild-plugin-node-worker

1.0.8 verified Fri May 01 auth: no javascript

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.

Common errors

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

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

error TypeError: nodeWorker is not a function ↓

cause 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 Error: Build failed with 1 error: error: No matching worker found ↓

cause 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)).

Warnings

gotcha Only 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')).

gotcha The 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.

gotcha Workers 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.

Install

npm install esbuild-plugin-node-worker

yarn add esbuild-plugin-node-worker

pnpm add esbuild-plugin-node-worker

Imports

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

nodeWorker

wrong

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

correct

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

Quickstart

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],
});