markdown-to-jsx

markdown-to-jsx is a GFM-and-CommonMark-compliant Markdown compiler for JavaScript and TypeScript projects, built around a single compact, table-driven parser that produces one AST and renders it through swappable backends for React, Vue, SolidJS, React Native, plain HTML, or round-tripped Markdown. It parses arbitrary raw HTML into proper JSX/host-tree nodes without dangerouslySetInnerHTML, supports full GFM syntax (tables, task lists, strikethrough, autolinks), and lets every rendered tag be overridden with custom components, extra props, or a different element entirely via the overrides option.

Performance and safety are first-class design goals rather than afterthoughts: the parser is tuned with byte-level character-class lookup tables and sticky regexes to stay fast enough for real-time interactivity, while a tag-filtering/sanitizer layer neutralizes dangerous tags (script, iframe, style, textarea) by default. Dedicated entry points (/react, /html, /native, /solid, /vue, /markdown) keep each renderer’s bundle tree-shaken, and a parser() export exposes the AST directly for consumers who want to inspect or transform nodes before rendering.

What You Get

• Multi-target renderers: dedicated /react, /html, /native, /solid, /vue, and /markdown entry points built from one shared AST/parser
• Full GFM support: tables, task lists, strikethrough, autolinks, and CommonMark-spec-tested edge cases
• Safe raw HTML handling: arbitrary HTML parses into real JSX/host nodes (no dangerouslySetInnerHTML) with a default tag-filter/sanitizer for dangerous tags
• Deep customization via options.overrides: swap any rendered tag for a custom component, add props, or change the element entirely
• Direct AST access via the parser() export for consumers who want to inspect or transform nodes before rendering
• React Server Component support out of the box — the Markdown component auto-detects RSC vs. client environments with no 'use client' directive required

Common Use Cases

• Rendering user-generated or CMS-authored Markdown (comments, docs, blog posts) directly to React/Vue/Solid components with custom styling via overrides
• Building chat and AI-assistant UIs that stream Markdown incrementally, using optimizeForStreaming to render partial documents smoothly
• Server-side or React Server Component rendering of Markdown content without client-side hydration overhead
• Cross-framework design systems that need one Markdown renderer shared across React, Vue, SolidJS, and React Native surfaces

Under The Hood

Architecture markdown-to-jsx is architected around a single shared parser (lib/src/parse.ts) that tokenizes and compiles Markdown into one AST (MarkdownToJSX.ASTNode), which every output backend consumes rather than re-parsing. toParseOptions() normalizes compiler options into a renderer-agnostic ParseOptions shape, and each entry point (react.tsx, html.ts, native.tsx, solid.tsx, vue.tsx, markdown.ts) implements only a thin render() switch over RuleType node kinds plus its own element-creation primitive — react.tsx’s createRawElement(), for instance, bypasses React.createElement entirely for performance. The legacy index.tsx entry re-exports from react.tsx to route around a Bun bundler symbol-reference bug. This shared-AST/thin-renderer split means adding a new target framework is additive rather than a parser rewrite, and it’s what would break if the core ASTNode/RuleType shape ever changed — every renderer would need updating in lockstep.

Tech Stack The library is written in strict TypeScript targeting ESNext, built with bunup (a Bun-based bundler) into dual ESM/CJS output plus declaration files for each of its seven entry points, with a custom build plugin that mangles internal _-prefixed properties post-minification while preserving React-reserved fields (_store, _owner, _debugStack, _debugTask) that RSC and dev builds require. Peer dependencies are optional and per-renderer (react, react-native, solid-js, vue), so consumers only install what they use. The repo is a Bun-workspace monorepo (lib, benchmarks, browser, native, site), with a dedicated site package for the docs website and a browser package for Playwright-driven smoke tests.

Code Quality Test coverage is extensive: thousands of lines across dedicated spec files per renderer (React, Vue, Solid, Native), a bundled CommonMark spec-conformance suite, a compiler-parity spec that checks renderers stay behaviorally consistent, a security-parity spec covering the tag-filter/sanitizer across every backend, and a fuzz-testing spec for adversarial-input robustness — all run via Bun’s test runner. Linting and formatting are enforced by Biome, unused-export detection runs via knip, and CI runs a full verification pass plus a Playwright-driven browser harness smoke test on every push and PR, alongside a separate CodeQL security-analysis workflow. This is an unusually rigorous quality setup for a library of this scope.

API Design The public API favors sane defaults with escape hatches over configuration-heavy setup: a bare <Markdown>{content}</Markdown> renders correctly out of the box, while options.overrides lets any consumer replace individual rendered tags with custom components or extra props without touching the parser. Framework-specific entry points keep each consumer’s bundle limited to the renderer it actually needs, and the Markdown component’s automatic RSC/client-environment detection removes a whole class of directive boilerplate that comparable renderers require. Detailed versioned migration guidance in the README and extensive internal design-rationale documentation reflect an unusually high documentation investment for a public API of this size.