{"record":{"id":"c846fef530660e48","repo":"BoundaryML/baml","slug":"cannot-import-name-from-boundaryml-baml-in-browser-index","errorCode":null,"errorMessage":"Cannot import ${name} from '@boundaryml/baml' in browser environment. Please import from '@boundaryml/baml/browser' instead.","messagePattern":"Cannot import (.+?) from '@boundaryml/baml' in browser environment\\. Please import from '@boundaryml/baml/browser' instead\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"engine/language_client_typescript/typescript_src/index.ts","lineNumber":12,"sourceCode":"export * from './safe_imports'\n\nexport * from './errors'\n\nexport * from './logging'\n\n// Detect if we're in a Node.js environment\nconst isNode = typeof process !== 'undefined' && process.versions != null && process.versions.node != null\n\nif (!isNode) {\n  const browserError = (name: string) => {\n    throw new Error(\n      `Cannot import ${name} from '@boundaryml/baml' in browser environment. Please import from '@boundaryml/baml/browser' instead.`,\n    )\n  }\n\n  // Provide helpful error messages for browser imports\n  Object.defineProperty(exports, 'Image', {\n    get: () => browserError('Image'),\n    enumerable: true,\n  })\n\n  Object.defineProperty(exports, 'Audio', {\n    get: () => browserError('Audio'),\n    enumerable: true,\n  });\n\n  Object.defineProperty(exports, 'Pdf', {\n    get: () => browserError('Pdf'),\n    enumerable: true,","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_typescript/typescript_src/index.ts#L1-L30","documentation":"The main '@boundaryml/baml' entry point only works under Node.js. When loaded in a browser (no process.versions.node), module-level shims replace Node-dependent exports such as Image with functions that throw this error, directing you to the browser-specific build.","triggerScenarios":"Importing { Image } (or other Node-only exports) from '@boundaryml/baml' in a browser bundle (Vite/webpack/Next.js client component), or in any environment where `process.versions.node` is undefined.","commonSituations":"Adding BAML to a frontend app and importing from the root package; bundlers resolving the wrong export map target; SSR code accidentally executed in the browser after hydration.","solutions":["Change imports of Node-only symbols to '@boundaryml/baml/browser'","Check the package's export map / bundler aliasing so browser builds pick the browser entry point","Keep Node-only BAML calls (Image, runtime, client) in server-side code; for SSR, guard imports to server-only modules","Use dynamic import inside a Node-only code path if the symbol is only needed server-side"],"exampleFix":"// before\nimport { Image } from '@boundaryml/baml'; // throws in browser\n// after\nimport { Image } from '@boundaryml/baml/browser';","handlingStrategy":"fallback","validationCode":"const isNode = typeof process !== 'undefined' && process.versions?.node;\nconst mod = isNode ? await import('@boundaryml/baml') : await import('@boundaryml/baml/browser');","typeGuard":"const isNodeEnv = () => typeof process !== 'undefined' && !!process.versions?.node;","tryCatchPattern":"try { Image = require('@boundaryml/baml').Image; }\ncatch (e) { if (String(e.message).includes('browser environment')) Image = require('@boundaryml/baml/browser').Image; else throw e; }","preventionTips":["Import Node-only BAML APIs only in server code","Use the package's browser entry point for frontend bundles","Mark server-only modules so bundlers error early on client import","Check bundler resolve conditions (exports map) when this surfaces in builds"],"tags":["browser","nodejs","import","environment"],"backgroundTag":"unsupported-platform","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}