evanw/esbuild · error · Error

The "worker" option only works in the browser

Error message

The "worker" option only works in the browser

What it means

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.

Source

Thrown at lib/npm/node.ts:237

    options,
    callback: (err, res) => { if (err) throw err; result = res! },
  }))
  return result!
}

export const stop = () => {
  if (stopService) stopService()
  if (workerThreadService) workerThreadService.stop()
  return Promise.resolve()
}

let initializeWasCalled = false

export let initialize: typeof types.initialize = options => {
  options = common.validateInitializeOptions(options || {})
  if (options.wasmURL) throw new Error(`The "wasmURL" option only works in the browser`)
  if (options.wasmModule) throw new Error(`The "wasmModule" option only works in the browser`)
  if (options.worker) throw new Error(`The "worker" option only works in the browser`)
  if (initializeWasCalled) throw new Error('Cannot call "initialize" more than once')
  ensureServiceIsRunning()
  initializeWasCalled = true
  return Promise.resolve()
}

interface Service {
  build: typeof types.build
  context: typeof types.context
  transform: typeof types.transform
  formatMessages: typeof types.formatMessages
  analyzeMetafile: typeof types.analyzeMetafile
}

let defaultWD = process.cwd()
let longLivedService: Service | undefined
let stopService: (() => void) | undefined

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Remove the `worker` option when using the `esbuild` package in Node.
2. If you need worker control, use `esbuild-wasm` in the browser.
3. Build the options object conditionally per environment.

Example fix

// before (Node)
await esbuild.initialize({ worker: false }) // throws

// after
await esbuild.initialize({})
// or in browser only:
import * as esbuild from 'esbuild-wasm'
await esbuild.initialize({ wasmURL, worker: false })

function sanitizeNodeInitOpts(opts: Record<string, unknown>) {
  delete opts.worker
  return opts
}

function isBrowserInitOpts(o: unknown): boolean {
  return !!o && typeof o === 'object' && 'worker' in o
}

When it happens

Trigger: Calling `esbuild.initialize({ worker: false })` (or `true`) against the Node `esbuild` package. Same root cause as error 18: browser-targeted option on Node entry.

Common situations: Sharing initialize code across browser and Node; migrating example code between esbuild and esbuild-wasm; copy-paste from browser docs.

Related errors

• The "wasmURL" option only works in the browser
• Must provide either the "wasmURL" option or the "wasmModule"
• The "buildSync" API only works in node
• You need to wait for the promise returned from "initialize"
• The package "${pkg}" could not be found, and is needed by es

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/919cf7aaa61fd07d.json. Report an issue: GitHub.