{"record":{"id":"eb99fe6f6af00512","repo":"evanw/esbuild","slug":"the-wasmmodule-option-only-works-in-the-browser","errorCode":null,"errorMessage":"The \"wasmModule\" option only works in the browser","messagePattern":"The \"wasmModule\" option only works in the browser","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/node.ts","lineNumber":235,"sourceCode":"    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\nlet stopService: (() => Promise<void>) | undefined","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/node.ts#L217-L253","documentation":"In the node entry, initialize() (lib/npm/node.ts:235) rejects the wasmModule option, throwing because the native node build spawns a real binary executable and has no use for a precompiled WebAssembly.Module. wasmModule is browser-only (used by the esbuild-wasm/browser build to avoid recompiling the wasm each time).","triggerScenarios":"Calling esbuild.initialize({ wasmModule: someCompiledModule }) (or a config object that includes wasmModule) while running the native node esbuild package.","commonSituations":"A shared config helper for both browser and node that always sets wasmModule; migrating browser code to node without trimming browser-only options; using a precompiled module for performance and forgetting node does not support it.","solutions":["Drop wasmModule from the options object when calling initialize in node.","Skip initialize() in node entirely; the native service starts automatically.","Use the esbuild-wasm package if you specifically need the WebAssembly module path in node."],"exampleFix":"// before\nimport * as esbuild from 'esbuild'            // native node build\nawait esbuild.initialize({ wasmModule: mod })   // throws\n\n// after\nimport * as esbuild from 'esbuild'\nawait esbuild.build({ entryPoints: ['a.ts'] })  // no initialize / wasmModule needed","handlingStrategy":"validation","validationCode":"// Remove wasmModule (and other browser-only keys) for node initialize.\nfunction nodeInitOptions(opts) {\n  const { wasmURL: _a, wasmModule: _b, worker: _c, ...rest } = opts || {}\n  return rest\n}\n// Typically you simply do not call initialize() under native esbuild.","typeGuard":"// Narrow options to the node-safe subset (no browser-only keys).\nfunction isNodeSafeOptions(o: any): boolean {\n  return o.wasmURL === undefined && o.wasmModule === undefined && o.worker === undefined\n}","tryCatchPattern":null,"preventionTips":["Pass wasmModule only when using the browser/esbuild-wasm build.","Keep a separate config builder for node vs browser initialize calls.","Rely on node's auto-starting service and avoid initialize() entirely when possible."],"tags":["node","initialization","wasm","platform","validation"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}