{"record":{"id":"06bc8c354ccf15b7","repo":"evanw/esbuild","slug":"the-buildsync-api-only-works-in-node","errorCode":null,"errorMessage":"The \"buildSync\" API only works in node","messagePattern":"The \"buildSync\" API only works in node","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/browser.ts","lineNumber":33,"sourceCode":"export let version = ESBUILD_VERSION\n\nexport let build: typeof types.build = (options: types.BuildOptions) =>\n  ensureServiceIsRunning().build(options)\n\nexport let context: typeof types.context = (options: types.BuildOptions) =>\n  ensureServiceIsRunning().context(options)\n\nexport const transform: typeof types.transform = (input: string | Uint8Array, options?: types.TransformOptions) =>\n  ensureServiceIsRunning().transform(input, options)\n\nexport const formatMessages: typeof types.formatMessages = (messages, options) =>\n  ensureServiceIsRunning().formatMessages(messages, options)\n\nexport const analyzeMetafile: typeof types.analyzeMetafile = (metafile, options) =>\n  ensureServiceIsRunning().analyzeMetafile(metafile, options)\n\nexport const buildSync: typeof types.buildSync = () => {\n  throw new Error(`The \"buildSync\" API only works in node`)\n}\n\nexport const transformSync: typeof types.transformSync = () => {\n  throw new Error(`The \"transformSync\" API only works in node`)\n}\n\nexport const formatMessagesSync: typeof types.formatMessagesSync = () => {\n  throw new Error(`The \"formatMessagesSync\" API only works in node`)\n}\n\nexport const analyzeMetafileSync: typeof types.analyzeMetafileSync = () => {\n  throw new Error(`The \"analyzeMetafileSync\" API only works in node`)\n}\n\nexport const stop = () => {\n  if (stopService) stopService()\n  return Promise.resolve()\n}","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/browser.ts#L15-L51","documentation":"The browser entry of esbuild (lib/npm/browser.ts) defines buildSync as a function that unconditionally throws, because the browser build is backed by WebAssembly which is inherently asynchronous and cannot perform a synchronous build. esbuild ships this stub so that code importing the browser variant still sees the buildSync export (preserving the type surface) but fails loudly instead of silently doing nothing.","triggerScenarios":"A module resolver / bundler selects lib/npm/browser.ts (via the package.json 'browser' field or because the environment is detected as a browser) and application code then calls esbuild.buildSync(options).","commonSituations":"Node-targeted code that calls buildSync gets reused or bundled into a browser build; using esbuild-wasm with the same API calls as native esbuild; test files run under a browser test runner.","solutions":["Replace the synchronous call with the asynchronous esbuild.build(...) and await its result.","If you genuinely need the native binary, import the node entry (esbuild, not esbuild-wasm) and run under node.","Refactor shared code to be async so it works in both node and browser."],"exampleFix":"// before\nconst result = esbuild.buildSync({ entryPoints: ['app.ts'], bundle: true })\n\n// after\nconst result = await esbuild.build({ entryPoints: ['app.ts'], bundle: true })","handlingStrategy":"validation","validationCode":"// Detect the browser build and avoid the sync stub.\nconst isBrowserBuild =\n  typeof window !== 'undefined' && typeof window.document !== 'undefined'\n\nif (isBrowserBuild) {\n  // use async build\n  const result = await esbuild.build(options)\n} else {\n  const result = esbuild.buildSync(options)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer the asynchronous API everywhere; it works in both node and browser.","Keep esbuild usage async in any code that might run in a browser or WASM context.","When sharing modules between node and browser, never rely on the *Sync APIs."],"tags":["browser","sync","async","platform","wasm"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}