{"record":{"id":"f3ff1c4fae1949da","repo":"evanw/esbuild","slug":"the-wasmurl-option-only-works-in-the-browser","errorCode":null,"errorMessage":"The \"wasmURL\" option only works in the browser","messagePattern":"The \"wasmURL\" option only works in the browser","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/node.ts","lineNumber":234,"sourceCode":"    callName: 'analyzeMetafileSync',\n    refs: null,\n    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","sourceCodeStart":216,"sourceCodeEnd":252,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/node.ts#L216-L252","documentation":"In the node entry, initialize() (lib/npm/node.ts:232) validates options and explicitly rejects wasmURL, throwing because node does not use WebAssembly for esbuild (it spawns the native binary directly). wasmURL is a browser-only option; passing it in node indicates a config meant for esbuild-wasm/esbuild browser being reused under native esbuild.","triggerScenarios":"Calling esbuild.initialize({ wasmURL: '...' }) (or a shared config object containing wasmURL) while importing the native node esbuild package.","commonSituations":"Shared initialization helper used by both browser (esbuild-wasm) and node (esbuild) code paths that unconditionally passes browser options; copy-pasting a browser example into node.","solutions":["Remove wasmURL from the options passed to initialize in node (node does not need or accept it).","Omit the initialize() call entirely in node; the service auto-starts on first use.","If you truly need WebAssembly in node, use the esbuild-wasm package instead of esbuild."],"exampleFix":"// before\nimport * as esbuild from 'esbuild'          // native node build\nawait esbuild.initialize({ wasmURL: '/esbuild.wasm' })  // throws\n\n// after\nimport * as esbuild from 'esbuild'\nawait esbuild.build({ entryPoints: ['a.ts'] })  // auto-starts, no initialize needed","handlingStrategy":"validation","validationCode":"// Strip browser-only options before calling initialize in node.\nfunction nodeInitOptions(opts) {\n  const { wasmURL: _drop1, wasmModule: _drop2, worker: _drop3, ...rest } = opts || {}\n  return rest\n}\n// In node you usually skip initialize() entirely; the service auto-starts.","typeGuard":"// Ensure an options object is free of browser-only keys for node.\nfunction hasNoBrowserOnlyOptions(o: any): o is Record<string, never> {\n  return o.wasmURL === undefined && o.wasmModule === undefined && o.worker === undefined\n}","tryCatchPattern":null,"preventionTips":["Do not share a single config object verbatim between esbuild (node) and esbuild-wasm (browser).","In node, omit initialize() altogether; the native service starts automatically.","Use esbuild-wasm if you actually need WebAssembly in node."],"tags":["node","initialization","wasm","platform","validation"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}