{"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/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/browser.ts#L19-L55","documentation":"Same stub pattern as `buildSync`: the browser entry (`lib/npm/browser.ts:37`) exports `transformSync` as an unconditional thrower. `transformSync` needs `execFileSync` against the native esbuild binary or a worker-thread sync bridge, neither of which exists in a browser. Calling it means the browser build was loaded.","triggerScenarios":"Calling `esbuild.transformSync(code, opts)` when `esbuild` resolves to the browser build. Same resolution causes as error 1: bundlers targeting the browser field, or running in a browser/worker/edge runtime.","commonSituations":"SSR frameworks that bundle server code into a browser-evaluable module; React-router style code sharing where `transformSync` runs in a shared utility loaded on both sides; misconfigured `resolve.mainFields`/`browser` field in webpack.","solutions":["Use the async `esbuild.transform(code, opts)` (Promise-based) which works in the browser after `initialize`.","Mark `esbuild` as external in your browser bundler so the Node build is retained for server code.","Switch to `esbuild-wasm` with `initialize({ wasmURL })` if you need transformation in the browser.","Gate the call behind a Node environment check (`if (typeof window === 'undefined')`)."],"exampleFix":"// before\nconst out = esbuild.transformSync(ts, { loader: 'ts' })\n\n// after\nconst out = await esbuild.transform(ts, { loader: 'ts' })","handlingStrategy":"validation","validationCode":"function transform(code, opts) {\n  if (typeof window !== 'undefined') {\n    return esbuild.transform(code, opts) // async\n  }\n  return Promise.resolve(esbuild.transformSync(code, opts))\n}","typeGuard":"function isNodeSyncCapable(): boolean {\n  return typeof process !== 'undefined' && !!process.versions?.node && typeof window === 'undefined'\n}","tryCatchPattern":"try {\n  return esbuild.transformSync(code, opts)\n} catch (e) {\n  if (/only works in node/.test((e as Error).message)) {\n    return await esbuild.transform(code, opts)\n  }\n  throw e\n}","preventionTips":["Use async transform() in shared/isomorphic code.","Mark esbuild external for browser bundles.","Keep transformSync calls in Node-only modules."],"tags":["browser","sync-api","node-only","transform"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}