mdx-loader

3.0.2 verified Sat Apr 25 auth: no javascript maintenance

A batteries-included webpack loader for converting Markdown files into React components using MDX. Version 3.0.2 (latest) builds on mdx-js/mdx to provide emoji support (remark-emoji), automatic image embedding (remark-images), heading IDs (remark-slug), Prism.js syntax highlighting (rehype-prism), front matter export (gray-matter), table of contents (mdx-table-of-contents), and typographic improvements (remark-textr). Released as part of the mdx-util monorepo, it offers a zero-config experience for Webpack projects and can also be used inline with create-react-app via webpack loader syntax. Releases are infrequent; the loader uses MDX v1 and has not been updated for MDX v2, which is a breaking change. Key differentiator: all-in-one setup without needing separate remark/rehype plugins.

Common errors

error Module parse failed: Unexpected token (14:9). You may need an appropriate loader to handle this file type. ↓

cause Webpack is missing the rule for .mdx files or the loader chain is incorrect.

fix

Add { test: /\.mdx$/, use: ['babel-loader', 'mdx-loader'] } to module.rules.

error Cannot find module '@mdx-js/mdx' ↓

cause @mdx-js/mdx is a required peer dependency not installed.

fix

Run npm install --save-dev @mdx-js/mdx

error export 'frontMatter' (imported as 'frontMatter') was not found in './doc.mdx' ↓

cause The file does not contain front matter, or the loader is not processing it correctly.

fix

Ensure the markdown file has YAML front matter delimited by '---'. Also verify that mdx-loader is in the webpack config.

Warnings

breaking The package is not compatible with MDX v2. Do not use with @mdx-js/mdx@^2. ↓

fix Use a different loader like @mdx-js/loader, or stay on MDX v1.

deprecated The package has not been updated since 2020; consider alternatives like @mdx-js/loader for new projects. ↓

fix Migrate to @mdx-js/loader or next-mdx-remote for newer MDX features.

gotcha Requires babel-loader in the chain; output is ES2015 and must be transpiled for older browsers. ↓

fix Ensure babel-loader is installed and configured (e.g., @babel/preset-env).

gotcha Syntax highlighting only works if you import a Prism stylesheet manually. ↓

fix Add `import 'prismjs/themes/prism-tomorrow.css'` in your app entry.

Install

npm install mdx-loader

yarn add mdx-loader

pnpm add mdx-loader

Imports

default
wrong
```
const Component = require('./doc.mdx')
```
correct
```
import Component from './doc.mdx'
```
Default export is a React component. ESM-only due to webpack loader chain; CJS require not supported directly.
frontMatter
wrong
```
import frontMatter from './doc.mdx'
```
correct
```
import { frontMatter } from './doc.mdx'
```
Named export for front matter object; not a default export.
tableOfContents
```
import { tableOfContents } from './doc.mdx'
```
Named export for table of contents tree; available when loader processes the file.

Quickstart

Webpack configuration to process .mdx files with mdx-loader and babel-loader, and a React component importing the MDX document, its front matter, and table of contents.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.mdx?$/,
        use: ['babel-loader', 'mdx-loader']
      }
    ]
  }
};

// Component.js
import React from 'react';
import Doc, { frontMatter, tableOfContents } from './doc.mdx';

export default function MyPage() {
  return (
    <div>
      <h1>{frontMatter.title}</h1>
      <Doc />
      <pre>{JSON.stringify(tableOfContents, null, 2)}</pre>
    </div>
  );
}