micromark-extension-mdxjs

micromark-extension-mdxjs is the syntax-extension package that teaches the micromark markdown tokenizer how to read MDX: JSX tags, curly-brace expressions, and ESM import/export statements, while disabling a handful of CommonMark constructs that don’t make sense inside MDX. Rather than implementing any of that parsing itself, it is a thin composition layer that wires together four sibling packages (micromark-extension-mdxjs-esm, micromark-extension-mdx-expression, micromark-extension-mdx-jsx, and micromark-extension-mdx-md) via micromark-util-combine-extensions, and wraps acorn plus acorn-jsx as the default JavaScript/JSX parser for embedded expressions and ESM statements.

It is the package that mdxjs.com’s own toolchain and remark-mdx use under the hood to get from raw MDX text to a syntax tree, and it is meant to be paired with a downstream consumer such as mdast-util-mdx rather than used to produce HTML directly (as the README notes, running it through micromark alone just strips MDX-specific syntax rather than rendering it). Because it is JavaScript-aware by design, projects that want MDX-shaped syntax without assuming JS/JSX semantics for expressions are pointed instead at the sibling micromark-extension-mdx package.

What You Get

• A single mdxjs() call that enables JSX tags, {expression} syntax, and import/export statements in micromark in one step
• Sensible defaults for parsing embedded JavaScript — acorn extended with acorn-jsx, ECMAScript 2024, module source type
• Automatic suppression of CommonMark features that conflict with MDX syntax, via the bundled micromark-extension-mdx-md
• Full TypeScript types (Options interface, extending micromark-extension-mdx-expression’s Options) with 100% type-coverage enforced in CI
• A stable low-level building block other tools compose on top of — remark-mdx and the wider mdxjs.com toolchain use it directly

Common Use Cases

• Adding MDX syntax support to a custom micromark-based markdown pipeline
• Building a syntax-tree-producing MDX parser by pairing this package with mdast-util-mdx
• Implementing MDX tooling (linters, formatters, syntax highlighters) that needs to tokenize MDX documents without a full compiler
• Understanding or debugging how remark-mdx / @mdx-js/mdx parse a specific piece of MDX syntax, since this package is the layer directly beneath them

Under The Hood

Architecture The package is a single 39-line composition module (lib/index.js) with no internal layering of its own: mdxjs(options) merges caller-supplied options over defaults (an acorn parser extended with acorn-jsx, ECMAScript 2024 module parsing, and addResult: true), then calls the four constituent extension factories — mdxjsEsm, mdxExpression, mdxJsx, mdxMd — and merges their returned micromark Extension objects via micromark-util-combine-extensions. There is no data flow to trace beyond that single delegation: the actual tokenizer state machines for JSX, expressions, and ESM live entirely in the four dependency packages, so this module’s sole responsibility is default-merging and composition, and any breaking change to combineExtensions or to one of the four sub-extensions’ Extension shape propagates directly into this package’s behavior.

Tech Stack A pure ESM (type: module) package with zero runtime framework of its own: it depends on acorn and acorn-jsx for parsing embedded JavaScript/JSX, and on the sibling micromark-extension-mdx-expression, micromark-extension-mdx-jsx, micromark-extension-mdx-md, and micromark-extension-mdxjs-esm packages plus micromark-util-combine-extensions and micromark-util-types for the micromark tokenizer machinery. Dev tooling follows the unified-collective standard: TypeScript type-checking against a hand-authored index.d.ts with type-coverage enforcing 100% strict coverage, xo (an ESLint preset) plus Prettier for lint/format, remark-cli with remark-preset-wooorm for linting the README itself, and c8 enforcing 100% test coverage over node:test-based tests, run under both --conditions development and --conditions production to exercise both branches of the dependency chain. No compiled build output ships — the package publishes its raw ESM source plus generated .d.ts files.

Code Quality A single test.js file uses node:test and node:assert/strict for three assertions: that the public API surface is exactly {mdxjs}, a happy-path parse through micromark, and one deliberately adversarial case with escaped braces and comment-like sequences to check the tokenizer isn’t fooled by them. Despite the small test count, c8’s --100 flag enforces full statement/branch coverage, which is feasible because the module under test is a thin, fully-exercised composition function. There is no explicit error handling in this module — errors from malformed MDX are raised by whichever sub-extension detects them — and typing is enforced via JSDoc annotations checked against index.d.ts, with xo/Prettier keeping style consistent and GitHub Actions workflows (main.yml, bb.yml) running the suite in CI.

API Design The public API is a single function, mdxjs(options?), that takes one optional options object and returns a micromark Extension ready to pass into extensions: [...] — about as low a barrier to entry as a micromark plugin can have. The Options type deliberately re-exports and extends micromark-extension-mdx-expression’s Options rather than inventing a new shape, keeping configuration consistent across the whole family of MDX packages, and the README documents exactly how to get from this package (a stripped-down, non-HTML-producing tokenizer) to a useful syntax tree by pairing it with mdast-util-from-markdown and mdast-util-mdx, which heads off the most likely point of confusion for a first-time integrator.