{"record":{"id":"0784f91e3a967515","repo":"evanw/esbuild","slug":"the-transformsync-api-only-works-in-node","errorCode":null,"errorMessage":"The \"transformSync\" API only works in node","messagePattern":"The \"transformSync\" API only works in node","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/browser.ts","lineNumber":37,"sourceCode":"\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}\n\ninterface Service {\n  build: typeof types.build\n  context: typeof types.context","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/browser.ts#L19-L55","documentation":"The browser entry of esbuild (lib/npm/browser.ts) defines transformSync as a stub that always throws. The WebAssembly-backed browser build cannot run synchronously, so esbuild blocks the call rather than pretending to work.","triggerScenarios":"Application code calls esbuild.transformSync(input, options) while the resolved module is the browser build (esbuild-wasm or the package 'browser' field).","commonSituations":"Copy-pasting node-oriented esbuild usage into a browser bundle; sharing a transform helper module across node and browser targets.","solutions":["Use esbuild.transform(...) and await the returned promise.","Switch to the native esbuild package running under node if synchronous execution is required.","Make the calling code async-compatible."],"exampleFix":"// before\nconst out = esbuild.transformSync(code, { loader: 'ts' })\n\n// after\nconst out = await esbuild.transform(code, { loader: 'ts' })","handlingStrategy":"validation","validationCode":"// Guard against the browser sync stub by using the async transform.\nconst isBrowserBuild =\n  typeof window !== 'undefined' && typeof window.document !== 'undefined'\n\nconst out = isBrowserBuild\n  ? await esbuild.transform(code, { loader: 'ts' })\n  : esbuild.transformSync(code, { loader: 'ts' })","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default to esbuild.transform(...) (async) for code that may run in browsers.","Reserve transformSync for node-only code paths.","Centralize transform calls behind an async wrapper."],"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"}