create-react-app fork with support for .mdx files
Clone or download
Pull request Compare This branch is 16 commits ahead, 18 commits behind facebook:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Create React App w/ MDX support

A fork of the create-react-app project with support for .mdx files via the mdx-loader package.

For info on create-react-app itself, view the official repository »

Getting Started

For new projects

To add support for MDX to a new create-react-app project, all you need to do is pass the --react-scripts react-scripts-mdx option to create-react-app:

npx create-react-app --scripts-version react-scripts-mdx

With this, you'll be able to use Markdown and MDX files in your new project.

For existing projects

In your package.json, just change the react-scripts dependency to react-scripts-mdx. You can leave the occurences of react-scripts in the scripts object as is. Then, re-run yarn install or npm install and you're good to go! You'll now be able to import and use Markdown and MDX files as React components.

Importing and using Markdown

Once you've got your project set up, add a test.mdx file in your project's src directory:

# Hello, world

I'm an **MDX** file!

Then, import and use it in your App.js file as with any other component:

import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';
import MDXDocument from './test.mdx';

class App extends Component {
  render() {
    return (
      <div className="App">
        <MDXDocument />

export default App;

For more details on MDX itself, see the MDX documentation »

Why a fork?

While create-react-app 1 allowed for slight modifications to configuration through react-app-rewired, this wasn't supported by the create-react-app team itself.

With create-react-app 2, official support was added for some extensions through babel-plugin-macros. In fact, it's possible to get some form of MDX support with babel-plugin-macros, through the mdx.macro package (by yours truly). However, this package has a major drawback: you'll need to manually restart the server each time you change an .mdx file.

In order to implement proper MDX support through babel-plugin-macros, babel itself will need a new feature. And until this feature is added, the next best (and far easier) solution is this fork.

What this fork changes

This fork makes a single change to react-scripts, with the patched package published as react-scripts-mdx:

react-scripts-mdx will transform .md and .mdx files with mdx-loader.

I've used the mdx-loader package instead of @mdx-js/loader, as mdx-loader takes a batteries-included approach which is more in line with the create-react-app philosophy.

Future plans

This fork is only meant as a stop-gap measure until babel-plugins-macros adds support live reloading of imported files, or until create-react-app adds direct support for MDX files.


Create React App is open source software licensed as MIT.