{"record":{"id":"919cf7aaa61fd07d","repo":"evanw/esbuild","slug":"the-worker-option-only-works-in-the-browser","errorCode":null,"errorMessage":"The \"worker\" option only works in the browser","messagePattern":"The \"worker\" option only works in the browser","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/node.ts","lineNumber":236,"sourceCode":"    metafile: typeof metafile === 'string' ? metafile : JSON.stringify(metafile),\n    options,\n    callback: (err, res) => { if (err) throw err; result = res! },\n  }))\n  return result!\n}\n\nexport const stop = async () => {\n  if (stopService) await stopService()\n  if (workerThreadService) workerThreadService.stop()\n}\n\nlet initializeWasCalled = false\n\nexport let initialize: typeof types.initialize = options => {\n  options = common.validateInitializeOptions(options || {})\n  if (options.wasmURL) throw new Error(`The \"wasmURL\" option only works in the browser`)\n  if (options.wasmModule) throw new Error(`The \"wasmModule\" option only works in the browser`)\n  if (options.worker) throw new Error(`The \"worker\" option only works in the browser`)\n  if (initializeWasCalled) throw new Error('Cannot call \"initialize\" more than once')\n  ensureServiceIsRunning()\n  initializeWasCalled = true\n  return Promise.resolve()\n}\n\ninterface Service {\n  build: typeof types.build\n  context: typeof types.context\n  transform: typeof types.transform\n  formatMessages: typeof types.formatMessages\n  analyzeMetafile: typeof types.analyzeMetafile\n}\n\nlet defaultWD = process.cwd()\nlet longLivedService: Service | undefined\nlet stopService: (() => Promise<void>) | undefined\n","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/node.ts#L218-L254","documentation":"esbuild's Node entry spawns the native binary directly and never uses a Web Worker, so the `worker` option to initialize() is meaningless there and is explicitly rejected. The `worker` flag exists only for the browser/WASM build (esbuild-wasm), where it spawns a Web Worker to run WebAssembly off the main thread. Passing it in Node throws at lib/npm/node.ts:236 inside initialize().","triggerScenarios":"Calling `initialize({ worker: true })` (or any truthy value) while importing the native `esbuild` package in Node.js. The initialize() function at lib/npm/node.ts:232 validates options then rejects `worker` (alongside `wasmURL` and `wasmModule`) before starting the service.","commonSituations":"Copying an esbuild-wasm browser initialization snippet into a Node script; sharing one config object between a browser (esbuild-wasm) frontend and a Node (esbuild) build; migrating from esbuild-wasm to native esbuild and forgetting to drop the worker flag.","solutions":["Remove the `worker` property from the options passed to initialize() when running in Node.","If you genuinely need WASM in Node, install and import `esbuild-wasm` instead of `esbuild` (there `worker` is honored).","Branch your config on environment: only set `worker` when `typeof window !== 'undefined'` / using the wasm package."],"exampleFix":"// before\nimport { initialize } from 'esbuild'\nawait initialize({ worker: true })\n\n// after\nimport { initialize } from 'esbuild'\nawait initialize({})","handlingStrategy":"validation","validationCode":"// Before calling initialize, drop browser-only keys when running in Node\nfunction sanitizeInitOptions(opts) {\n  const cleaned = { ...opts }\n  if (typeof process !== 'undefined' && process.versions?.node) {\n    delete cleaned.worker   // native esbuild ignores/rejects this\n    delete cleaned.wasmURL\n    delete cleaned.wasmModule\n  }\n  return cleaned\n}\nawait initialize(sanitizeInitOptions(myOpts))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only set `worker` when importing from esbuild-wasm in a browser context.","Keep your Node build config and browser wasm config in separate modules.","Run a smoke-test build in CI to catch init-option mistakes early."],"tags":["config","initialize","node","browser","environment"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}