{"id":"ca37eaacbd0490e9","repo":"evanw/esbuild","slug":"the-analyzemetafilesync-api-only-works-in-node","errorCode":null,"errorMessage":"The \"analyzeMetafileSync\" API only works in node","messagePattern":"The \"analyzeMetafileSync\" API only works in node","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/browser.ts","lineNumber":45,"sourceCode":"  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\n  transform: typeof types.transform\n  formatMessages: typeof types.formatMessages\n  analyzeMetafile: typeof types.analyzeMetafile\n}\n\nlet initializePromise: Promise<void> | undefined\nlet stopService: (() => void) | undefined\nlet longLivedService: Service | undefined","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/browser.ts#L27-L63","documentation":"The browser entry (`lib/npm/browser.ts:45`) stubs `analyzeMetafileSync` to throw. Analyzing a metafile synchronously requires spawning the native binary; the browser only supports the async variant via the wasm service.","triggerScenarios":"Calling `esbuild.analyzeMetafileSync(metafile, opts)` after the browser build was loaded.","commonSituations":"Bundle analyzers running in the browser; webpack/vite picking the `browser` field of esbuild; shared metafile-analysis utility loaded into a browser context.","solutions":["Use the async `esbuild.analyzeMetafile(metafile, opts)`.","Mark esbuild external in the browser bundler config.","Run metafile analysis in a Node build step and write the report to disk for the browser to consume.","Use `esbuild-wasm` with `initialize` for in-browser async analysis."],"exampleFix":"// before\nconst report = esbuild.analyzeMetafileSync(metafile)\n\n// after\nconst report = await esbuild.analyzeMetafile(metafile)","handlingStrategy":"validation","validationCode":"function analyze(metafile, opts) {\n  return typeof window === 'undefined'\n    ? Promise.resolve(esbuild.analyzeMetafileSync(metafile, opts))\n    : esbuild.analyzeMetafile(metafile, opts)\n}","typeGuard":"function isBrowser(): boolean {\n  return typeof window !== 'undefined'\n}","tryCatchPattern":"try {\n  return esbuild.analyzeMetafileSync(metafile, opts)\n} catch (e) {\n  if (/only works in node/.test((e as Error).message)) {\n    return await esbuild.analyzeMetafile(metafile, opts)\n  }\n  throw e\n}","preventionTips":["Use async analyzeMetafile in portable code.","Run metafile analysis in Node build step and persist the report.","Mark esbuild external in browser bundlers."],"tags":["browser","sync-api","node-only","metafile"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}