{"id":25377,"library":"esbuild-plugin-node-worker","title":"esbuild-plugin-node-worker","description":"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.","status":"active","version":"1.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/s-h-a-d-o-w/esbuild-plugin-node-worker","tags":["javascript","esbuild","esbuild-plugin","typescript"],"install":[{"cmd":"npm install esbuild-plugin-node-worker","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-node-worker","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-node-worker","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; plugin runs within esbuild's build system","package":"esbuild","optional":false}],"imports":[{"note":"Named export, not default. CommonJS require: const { nodeWorker } = require('esbuild-plugin-node-worker')","wrong":"import nodeWorker from 'esbuild-plugin-node-worker'","symbol":"nodeWorker","correct":"import { nodeWorker } from 'esbuild-plugin-node-worker'"},{"note":"CommonJS require must destructure the named export","wrong":"const nodeWorker = require('esbuild-plugin-node-worker')","symbol":"nodeWorker","correct":"const { nodeWorker } = require('esbuild-plugin-node-worker')"},{"note":"TypeScript type export available for configuring the plugin if needed","wrong":"","symbol":"type NodeWorkerOptions","correct":"import type { NodeWorkerOptions } from 'esbuild-plugin-node-worker'"}],"quickstart":{"code":"import { nodeWorker } from 'esbuild-plugin-node-worker';\nimport esbuild from 'esbuild';\n\nawait esbuild.build({\n  entryPoints: ['src/index.ts'],\n  bundle: true,\n  outdir: 'dist',\n  platform: 'node',\n  format: 'esm',\n  plugins: [nodeWorker],\n});","lang":"typescript","description":"Shows minimal setup: import nodeWorker, add to esbuild plugins array, bundle for Node.js."},"warnings":[{"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')).","message":"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.","severity":"gotcha","affected_versions":"*"},{"fix":"Use a direct path.join with string literals or new URL with string literal path.","message":"The plugin does not work with workers created via a variable or require call (e.g., new Worker(require('path').join(...))).","severity":"gotcha","affected_versions":"*"},{"fix":"If your worker references assume a flat output, adjust paths or use publicPath option.","message":"Workers are emitted into a workers/ directory. Ensure your output directory structure does not interfere with expected worker paths at runtime.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Update your worker constructor to use a relative path from the output directory, or use the plugin's 'publicPath' option if available.","cause":"The plugin emitted the worker in 'workers/' subdirectory, but the runtime code expects it in the same directory as the entry.","error":"Error: Cannot find module './worker.mjs'"},{"fix":"Use import { nodeWorker } from 'esbuild-plugin-node-worker' or const { nodeWorker } = require('esbuild-plugin-node-worker').","cause":"Importing the plugin as default instead of named export.","error":"TypeError: nodeWorker is not a function"},{"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)).","cause":"The plugin could not find a Worker constructor call with a string literal first argument.","error":"Error: Build failed with 1 error: error: No matching worker found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}