# mdx-js/mdx: compiling Markdown with JSX components into JavaScript

> The mdx-js/mdx monorepo ships the compiler and the React, Preact, Vue, Rollup, esbuild and webpack integrations for the MDX format. It is a good fit when content needs real components; it is the wrong tool when the content has to stay portable Markdown.

**mdx-js/mdx** — Markdown for the component era

- Repository: https://github.com/mdx-js/mdx
- Website: https://mdxjs.com
- Stars: 19,810 · Forks: 1,179
- Language: JavaScript
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/mdx-js-mdx

## What MDX solves that Markdown cannot

Plain Markdown has no way to express an interactive chart, a callout component, or a value computed at build time. MDX extends the format so that JSX can be written directly inside a document. The README's own example puts an import, an exported constant and a component call in the same file as a heading and two paragraphs:

```mdx
import {Chart} from './snowfall.js'
export const year = 2013

# Last year’s snowfall

In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.

<Chart year={year} color="#fcb32c" />
```

The audience is documentation teams, blogs and product sites where the prose and the UI live in the same repository. If your content is a README that must render identically on GitHub, npm and a static site generator, MDX is the wrong format, because it is compiled rather than parsed. The repository description puts it plainly: "Markdown for the component era."

## How the monorepo turns an MDX file into JavaScript

The root package.json is private and declares nine workspaces: packages/remark-mdx/, packages/mdx/, packages/react/, packages/preact/, packages/vue/, packages/esbuild/, packages/loader/, packages/node-loader/ and packages/rollup/. That layout is the architecture. remark-mdx handles the syntax layer, packages/mdx/ holds the compiler, and the remaining packages are integrations that plug the compiler into a bundler or a framework runtime.

The README describes the repository as containing "several packages for compiling the MDX format to JavaScript, integrating with bundlers such as webpack and Rollup, and for using it with frameworks such as React, Preact, and Vue." The output is JavaScript, not HTML. That matters for your pipeline: whatever consumes the result has to evaluate or bundle it, which is why the integrations exist rather than a single CLI. The dependency list also shows React 19 pinned through an overrides block for @types/react, react and react-dom, so the repository's own tooling targets that major version.

## Where to get mdx and how to compile a first document

The README does not carry install instructions itself. It says to see the Getting started page for how to integrate MDX into your project, and it links the playground on mdxjs.com for trying the format out. The repository is a monorepo whose packages are published under the mdxjs scope on npm, with packages/mdx/ holding the compiler, but the README does not spell out a package name or a command, so the exact install line has to come from that Getting started page rather than from anything quoted here.

What the README does show is the shape of a document once the toolchain is in place. The example below is reproduced from it verbatim, including the import path and the prop value:

```mdx
import {Chart} from './snowfall.js'
export const year = 2013

# Last year’s snowfall

In {year}, the snowfall was above average.
It was followed by a warm spring which caused
flood conditions in many of the nearby rivers.

<Chart year={year} color="#fcb32c" />
```

For a bundler workflow the repository provides packages/rollup/ and packages/esbuild/ rather than a hand-written compile step. The README lists Rollup and webpack among the supported bundlers, and the workspace list adds esbuild, a webpack loader and a Node loader. Which one you pick depends on your build tool, not on the format. If your project already runs Vite or Next.js, check the Getting started page before adding a second bundler integration, because the repository does not document a single universal setup command.

## Where MDX stops being the right tool

The format is compiled to JavaScript, and that is a boundary rather than a detail. A file containing an import statement or a JSX element is not valid Markdown, so any consumer that only understands Markdown will either render the syntax literally or fail. Documentation that has to be readable in a plain text editor, in a GitHub preview and in a published site at the same time is a case where MDX adds work instead of removing it.

There is a second constraint in the repository layout. The compiler lives in a monorepo with nine workspaces, and the integrations are separate packages. Adopting MDX means adopting the integration that matches your bundler and keeping it current. The README also links to a dedicated security page rather than summarising the topic inline, which is a signal that evaluating untrusted MDX input is a question you have to answer yourself before shipping. Nothing in the README describes a sandbox for untrusted documents, and it does not document rollback behaviour for a bad compile, so treat the compiler as a build step you control rather than a runtime you expose.

## MDX against remark and a plain Markdown pipeline

The most direct alternative is remark alone, which is the Markdown processor MDX is built on top of. The difference is where the extension point sits. A remark pipeline keeps the document as Markdown and transforms the syntax tree; plugins add behaviour without changing what the source file is. MDX changes the source language itself so that JSX is legal inside the document, and then compiles the whole thing to JavaScript.

That gives MDX a capability remark does not have: importing a component from a relative path and passing it a prop, as the README example does with ./snowfall.js. The cost is that the file is no longer Markdown. If your requirement is a table of contents, syntax highlighting or link rewriting, remark covers it while keeping the file portable. If your requirement is a chart embedded in the middle of a paragraph, remark cannot express it and MDX can. The repository's own packages/remark-mdx/ workspace shows the two are not competitors so much as layers, with remark-mdx supplying the syntax that the MDX compiler consumes.

## Maintenance, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-09-18. The release history is uneven rather than continuous: 3.0.1 landed on 2024-02-12, 3.1.0 on 2024-10-18, and 3.1.1 on 2025-08-29. Between 3.1.0 and 3.1.1 there were roughly ten months, so planning an upgrade around a fixed cadence would be a mistake. Pin an exact version and read changelog.md in the repository root before moving, since that file is where the project records what changed.

The licence is MIT, held by Compositor and Vercel according to the README's licence section. MIT permits commercial use and modification, but it also means the packages ship without warranty. If you fork the compiler or an integration, the licence text and attribution travel with your distribution. This is not legal advice; check the terms against how you ship.

The upgrade cost is structural rather than financial. Because the compiler and the integrations are separate workspaces, a major bump in packages/mdx/ can require a matching bump in packages/rollup/, packages/loader/ or packages/react/. Budget for that coordination rather than assuming a single dependency update is enough.

## Conclusion

Adopt mdx-js/mdx when your content genuinely needs imported components and you already render through React, Preact or Vue; the packages/mdx/, packages/react/ and packages/rollup/ workspaces exist exactly for that path. Do not adopt it if the same files must also be readable as plain Markdown elsewhere, because the format is compiled to JavaScript rather than parsed as Markdown. Before committing, verify that your chosen integration is one of the nine workspaces listed in package.json, confirm the MIT licence terms against your own distribution model, and check whether you need the 3.1.1 release or can pin to 3.1.0.

## FAQ

### What type of file is an MDX file?

It is an authorable format for documents that mix Markdown with JSX. The README describes MDX as letting you write JSX in Markdown documents and import components such as interactive charts or alerts into the content.

### What are the key differences between Markdown and MDX?

Markdown is parsed, while MDX is compiled to JavaScript. In MDX you can import a component and call it inside the prose, as the README example does with a Chart component and an exported year constant, which plain Markdown cannot express.

### What software opens MDX files?

The README does not list a viewer application. It points to the playground on mdxjs.com for trying the format and to the Getting started page for integrating MDX into a project, and the repository supplies compiler packages plus integrations for React, Preact, Vue, Rollup, esbuild and webpack.

## Sources

- [License: MIT](https://github.com/mdx-js/mdx/blob/main/LICENSE)
- [mdx-js/mdx on GitHub](https://github.com/mdx-js/mdx)
- [Project website](https://mdxjs.com)
- [README](https://github.com/mdx-js/mdx/blob/main/README.md)
- [Releases](https://github.com/mdx-js/mdx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mdx-js-mdx