{"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":237,"sourceCode":"    options,\n    callback: (err, res) => { if (err) throw err; result = res! },\n  }))\n  return result!\n}\n\nexport const stop = () => {\n  if (stopService) stopService()\n  if (workerThreadService) workerThreadService.stop()\n  return Promise.resolve()\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: (() => void) | undefined\n","sourceCodeStart":219,"sourceCodeEnd":255,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/node.ts#L219-L255","documentation":"The Node entry's `initialize` (`node.ts:237`) rejects the `worker` option. `worker` controls whether esbuild-wasm runs the Go runtime in a Web Worker — a browser-only concern. Node uses a native subprocess and the option is meaningless there.","triggerScenarios":"Calling `esbuild.initialize({ worker: false })` (or `true`) against the Node `esbuild` package. Same root cause as error 18: browser-targeted option on Node entry.","commonSituations":"Sharing initialize code across browser and Node; migrating example code between esbuild and esbuild-wasm; copy-paste from browser docs.","solutions":["Remove the `worker` option when using the `esbuild` package in Node.","If you need worker control, use `esbuild-wasm` in the browser.","Build the options object conditionally per environment."],"exampleFix":"// before (Node)\nawait esbuild.initialize({ worker: false }) // throws\n\n// after\nawait esbuild.initialize({})\n// or in browser only:\nimport * as esbuild from 'esbuild-wasm'\nawait esbuild.initialize({ wasmURL, worker: false })","handlingStrategy":"validation","validationCode":"function sanitizeNodeInitOpts(opts: Record<string, unknown>) {\n  delete opts.worker\n  return opts\n}","typeGuard":"function isBrowserInitOpts(o: unknown): boolean {\n  return !!o && typeof o === 'object' && 'worker' in o\n}","tryCatchPattern":null,"preventionTips":["Drop the worker option when using esbuild in Node.","Branch initialize options by runtime environment.","Reserve worker-option code for esbuild-wasm in browsers."],"tags":["node","worker","initialize","configuration","browser-only-option"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}