MDX

@mdx-js/mdx is the core compiler behind MDX, an authorable file format that blends Markdown’s readability with the full expressive power of JSX components. It parses markdown into an AST with remark, transforms it into HTML-like hast with rehype, and finally emits a JavaScript/JSX program via recma, letting authors import and render live React (or Preact/Vue) components inline with their prose.

The package exposes a small, composable API — compile, evaluate, and run — so it can be dropped into build-time pipelines (bundler loaders, static-site generators) or used to evaluate MDX strings at runtime. It underpins the broader @mdx-js ecosystem, including webpack/Rollup/esbuild integrations and framework bindings, and is the engine that projects like Next.js, Docusaurus, and Astro’s own MDX integration build on top of.

What You Get

• A compile/compileSync API that turns an MDX string or file into a JavaScript module exporting a React (or other JSX-runtime) component
• An evaluate/evaluateSync API for compiling and directly executing MDX at runtime without a separate build step
• Full support for standard Markdown syntax (CommonMark plus GFM extensions via plugins) interleaved with arbitrary JSX, import/export statements, and JS expressions in curly braces
• A pluggable unified/remark/rehype plugin pipeline (remarkPlugins, rehypePlugins, recmaPlugins options) for extending or customizing the compile process
• Source-map generation and development-mode diagnostics for accurate error locations in authored MDX files
• The foundation package that @mdx-js/loader, @mdx-js/rollup, @mdx-js/esbuild, @mdx-js/react, @mdx-js/preact, and @mdx-js/vue all build on

Common Use Cases

• Documentation sites that need live, interactive code examples embedded directly in Markdown content (Docusaurus, Next.js docs, Astro content collections)
• Blog and content platforms where authors write in Markdown but occasionally need custom React components (charts, callouts, embeds) inline
• Design-system and component-library docs where the same component being documented is rendered live next to its usage example
• Static-site generators and content pipelines that compile authored content to pre-rendered pages at build time

Under The Hood

Architecture: The compiler is a linear unified pipeline defined in packages/mdx/lib/core.js’s createProcessor: markdown source is parsed by remark-parse into an mdast tree, remark-mdx extends that parser to understand JSX/expression/ESM syntax, a custom remark-mark-and-unravel plugin normalizes how JSX nodes nest inside paragraphs, remark-rehype converts to hast, rehype-recma bridges hast to an estree JS AST, and finally recma-document/recma-jsx-rewrite/recma-build-jsx/recma-stringify assemble that AST into a printable JS program that exports a component function. lib/compile.js, lib/evaluate.js, and lib/run.js are thin wrappers around this shared core for the three usage modes (compile-to-source, compile-and-eval, and eval-a-precompiled-body).

Tech Stack: Pure ESM JavaScript ("type": "module") with TypeScript types authored via JSDoc and emitted through tsc --emitDeclarationOnly (see tsconfig.json, checkJs: true, strict: true). Dependencies are almost entirely other unified-ecosystem packages it owns or coordinates with (unified, remark-parse, remark-rehype, remark-mdx, rehype-recma, recma-*, hast-util-to-jsx-runtime, vfile), plus acorn/estree-walker/estree-util-* for JS AST manipulation and source-map for source-map output. No runtime dependency on React itself — JSX runtime import source is configurable (jsxImportSource), which is how the sibling @mdx-js/preact and @mdx-js/vue packages reuse this same compiler.

Code Quality: The package enforces c8 --100 test coverage (npm run test-coverage fails under anything less than 100%), backed by roughly 3,000 lines of tests across test/compile.js, test/evaluate.js, test/core.js, and test/syntax.js, exercised with Node’s built-in test runner and assert. Source files carry extensive JSDoc @typedef/@property blocks that double as the type surface (no hand-written .d.ts), and the xo-based lint config keeps style consistent across the monorepo’s 196 contributors.

API Design: The public surface is deliberately tiny — five exports (compile, compileSync, evaluate, evaluateSync, run, runSync, createProcessor) covering build-time and runtime use without requiring consumers to understand the internal remark/rehype/recma pipeline. Sensible defaults (format: 'mdx', jsxRuntime: 'automatic', outputFormat: 'program') mean a working setup is a one-line compile(mdxString) call, while remarkPlugins/rehypePlugins/recmaPlugins options give power users direct access to the underlying unified pipeline for advanced customization.