{children}
\n },\n blockquote({ children }) {\n return (\n\n {children}\n\n )\n },\n }}\n />\n )\n}\n```\n\n## Incremental parsing for streaming markdown\n\nUse `safe-mdx/incremental-parse` when markdown is changing rapidly, like during an LLM stream. Stable top-level mdast nodes are reused from a caller-owned cache, while only the live tail is parsed again. Parse errors are returned in `errors` instead of being thrown, so incomplete MDX can keep rendering the stable prefix.\n\n```tsx\nimport { useMemo } from 'react'\nimport { SafeMdxRenderer } from 'safe-mdx'\nimport {\n parseMarkdownIncremental,\n type SegmentCache,\n} from 'safe-mdx/incremental-parse'\n\nexport function StreamingMdx({ markdown }: { markdown: string }) {\n const cache = useMemo
\n {errors.length ?
\n )\n}\n```\n\nCustomize the parser with extra remark plugins by creating a processor once and passing it to the incremental parser.\n\n```ts\nimport remarkMath from 'remark-math'\nimport {\n createMdxProcessor,\n parseMarkdownIncremental,\n} from 'safe-mdx/incremental-parse'\n\nconst processor = createMdxProcessor({\n remarkPlugins: [remarkMath],\n})\n\nconst cache = new Map()\nconst { mdast, errors } = parseMarkdownIncremental({\n markdown,\n cache,\n processor,\n})\n```\n\n## JSX Components in Attributes\n\nsafe-mdx supports using JSX components inside component attributes, providing a secure alternative to JavaScript evaluation.\n\n```tsx\nimport { SafeMdxRenderer } from 'safe-mdx'\nimport { mdxParse } from 'safe-mdx/parse'\n\nconst code = `\n# Components in Attributes\n\n{errors[0]?.message} : null}\n {mdast.children.map((block, index) => (\n \n {icon}\n
\n {actions}
\n {children}
\n \n )\n },\n Icon({ name }) {\n return ⭐ // Your icon component\n },\n Button({ variant, children }) {\n return \n },\n }}\n />\n )\n}\n```\n\n### ESM Imports in Attributes\n\nTo use externally imported components in attributes, enable the `allowClientEsmImports` option:\n\n```tsx\nimport { SafeMdxRenderer } from 'safe-mdx'\nimport { mdxParse } from 'safe-mdx/parse'\n\nconst code = `\nimport { Icon } from 'https://esm.sh/lucide-react'\nimport Button from 'https://esm.sh/my-ui-library'\n\n# External Components in Attributes\n\n\n {icon}\n {action}\n
\n {children}
\n \n )\n },\n }}\n />\n )\n}\n```\n\n`safe-mdx` resolves the client ESM renderer through its own `safe-mdx/client`\nsubpath, so enabling `allowClientEsmImports` does not need any extra prop.\n\n**Security Note**: ESM imports are disabled by default. Only enable `allowClientEsmImports` when you trust the MDX source, as it allows loading external code.\n\n## Server-side Module Resolution\n\nResolve MDX `import` statements against pre-loaded modules on the server — no client-side `eval` or ESM fetching needed. This is the recommended approach when your MDX files import local components.\n\n**Simple case** — use Vite's `import.meta.glob` with `{ eager: true }` to load all modules upfront. The result is already the shape `modules` expects:\n\n```tsx\nimport { SafeMdxRenderer } from 'safe-mdx'\nimport { mdxParse } from 'safe-mdx/parse'\n\n// { eager: true } returns the modules directly instead of lazy loaders:\n// { './snippets/card.tsx': { Card, default: ... }, './snippets/badge.tsx': { Badge, ... } }\nconst modules = import.meta.glob('./snippets/**/*.tsx', { eager: true })\n\nconst code = `\nimport { Card } from '/snippets/card'\nimport { Badge } from '/snippets/badge'\n\n# Hello\n\n\n\n\n
{children}
,\n Cards: ({ children, ...props }) =>{children}
,\n },\n componentPropsSchema,\n })\n const jsx = visitor.run()\n\n if (visitor.errors.length) {\n // errors include type, line number, component name, property path, and message\n // [\n // { type: 'validation', message: 'Invalid props for component \"Heading\" at \"level\": Too big...', line: 3, schemaPath: 'level' },\n // { type: 'validation', message: 'Invalid props for component \"Cards\" at \"count\": Too small...', line: 5, schemaPath: 'count' },\n // ]\n }\n\n return jsx\n}\n```\n\n## RSC: don't pass components from a `'use client'` module\n\nWhen using `SafeMdxRenderer` in a React Server Component, the `components` prop must be a plain server-side object. If the file exporting your components map has `'use client'` at the top, the entire module becomes an opaque client reference in RSC. Spreading a client reference produces an empty object, so `SafeMdxRenderer` silently falls back to plain HTML tags with no styling.\n\n**Wrong:** exporting the components map from a `'use client'` file\n\n```tsx\n// components.tsx\n'use client'\nimport Zoom from 'react-medium-image-zoom'\n\nfunction P({ children }) {\n return {children}
\n}\nfunction Img(props) {\n return{children}
\n}\nexport const components = { p: P, img: Img }\n```\n\nOnly components that use browser-only APIs (hooks, DOM refs, client libraries) belong in `'use client'` files. Pure JSX with classnames, config objects, and component maps must stay in server-compatible modules.\n\n## Handling errors\n\n`safe-mdx` collects errors during rendering and exposes them via the `onError` callback or the `visitor.errors` array. Each error has a `type` field so you can filter by category.\n\n### Error types\n\nEvery error is a `SafeMdxError` object:\n\n```ts\ninterface SafeMdxError {\n type: 'validation' | 'missing-component' | 'expression' | 'esm-import' | 'sanitize'\n message: string\n line?: number // source line in the MDX\n schemaPath?: string // only for validation errors, e.g. \"user.age\"\n}\n```\n\n| Type | When it fires |\n|---|---|\n| `validation` | Component props fail schema validation (via `componentPropsSchema`) |\n| `missing-component` | MDX uses a `{title}{children}
\n}\n\nexport function formatTitle(text) {\n return text.toUpperCase()\n}\n\n# {formatTitle(\"hello\")}\n\n'}} />\n