mdx-loader

library3.0.2jsnpmunverified

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.

web-framework

npm install mdx-loader

github ↗package ↗

INSTALL

IMPORT

SIG · MDX-LOADER

mdx-loader

web-frameworkjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import Component from './doc.mdx'

✗ const Component = require('./doc.mdx')

Default export is a React component. ESM-only due to webpack loader chain; CJS require not supported directly.

frontMatter

✓ import { frontMatter } from './doc.mdx'

✗ 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.

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> ); }

Debug

Known issues

breakingThe 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.

affects: ^2.0.0 || ^3.0.0

deprecatedThe 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.

affects: >=3.0.0

gotchaRequires 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).

affects: >=3.0.0

gotchaSyntax highlighting only works if you import a Prism stylesheet manually.

fix

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

affects: >=3.0.0

Errors

Common errors & fixes

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

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.

Cannot find module '@mdx-js/mdx'

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

fix

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

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

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.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

babel-loaderrequiredmdx-loader produces ES2015 code and must be chained with babel-loader for browser compatibility.

@mdx-js/mdxrequiredCore MDX compiler used to transform Markdown to JSX.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/frontarm/mdx-util ↗

packagehttps://www.npmjs.com/package/mdx-loader ↗