Skip to navigation


@parcel/transformer-mdx is the official plugin for Parcel 2.


npm install --save-dev parcel react react-dom
  • parcel in order to npm exec -- parcel.
  • react so Parcel detects that the @parcel/transformer-mdx output is JSX. This seems unnecessary, but actually it is. Probably in the future the MDX transformer will compile away the JSX -- but not in every case?
  • react-dom to render the output into the DOM.


npm exec -- parcel index.html


To get started, see the MDX + Parcel example, the Parcel web app and Parcel React recipes and the @mdx-js/react package.

Synthesizing those resources, assume your project contains the following three files: index.html, hello.js and hello.mdx, and that hello.js contains the following React:

// hello.js
import ReactDOM from 'react-dom'
import {MDXProvider} from '@mdx-js/react'
import Hello from './hello.mdx'

// Intercept headings.
function h1(props) {
  return <h1 style={{color: 'tomato'}} {...props} />

// Render the MDX into the DOM.
  <MDXProvider components={{h1}}>
    <Hello />

Running npm exec -- parcel index.html will build it, and visiting http://localhost:1234 will contain:

<h1 style="color:tomato">Hello, World! 2</h1>

... assuming hello.mdx contains:

# Hello, World! {1 + 1}

You need to use <script src="hello.js" type="module"></script> to reference hello.js from index.html, otherwise you will see the following error:

@parcel/transformer-js: Browser scripts cannot have imports or exports.