Create React App

First, create a new app with CRA and change directory to enter it:

npx create-react-app my-app
cd my-app

Second, we need to configure some build tools. Install @mdx-js/loader and babel-loader as dev dependencies:

yarn add @mdx-js/loader babel-loader --dev

Also make sure that JSX in MDX is handled by Babel by creating a .babelrc JSON file in the project root of my-app:

{
  "presets": ["@babel/preset-react"]
}

Third, we can add our MDX content. Create an MDX file Content.mdx in the src/ folder:

export const Box = () => (
  <div style={{padding: 20, backgroundColor: 'tomato'}} />
)

# Hello, world!

This is **markdown** with <span style={{color: "red"}}>JSX</span>: MDX!

<Box />

And to use that MDX content in the app, replace the contents of App.js in the src/ folder with:

/* eslint-disable import/no-webpack-loader-syntax */
import Content from '!babel-loader!@mdx-js/loader!./Content.mdx'

function App() {
  return <Content />
}

export default App

We’re almost done! To start the development server, run:

yarn start

…but you will probably get this error:

$ react-scripts start

There might be a problem with the project dependency tree.
It is likely not a bug in Create React App, but something you need to fix locally.

The react-scripts package provided by Create React App requires a dependency:

  "babel-loader": "$VERSION"
…

CRA expects a certain babel-loader version but MDX also needs one. To fix the error, make sure the two babel-loader versions match, by running the following:

yarn add babel-loader@$VERSION --dev

(where $VERSION is the version number printed in the error message, such as 8.1.0).

Then, running yarn start again should do the trick! ✨

If you’re still seeing errors and you’re using TypeScript, then this guide might help.

Finally, see Support if you’re still running into problems.