next-mdx

Purpose

@next/mdx lets users author pages in MDX — Markdown plus inline JSX. The package is a Next.js plugin (a function that wraps next.config.js) that registers the right webpack loader and the Turbopack loader so .md and .mdx files become first-class pages or components.

Source: packages/next-mdx/.

Directory layout

packages/next-mdx/
├── README.md
├── index.js              # Plugin entry — wraps next.config
├── index.d.ts
├── mdx-components.js     # Default mdx-components export
├── mdx-js-loader.js      # webpack loader using @mdx-js/loader
├── mdx-rs-loader.js      # webpack loader using the Rust mdxjs-rs (faster)
└── package.json

The plugin is small (a few KB) because most of the work is done by @mdx-js/loader (or its Rust replacement mdxjs-rs).

Two compilers

next-mdx supports two compilation paths:

graph LR
    Mdx[*.mdx file] --> Choose{useMdxRs?}
    Choose -- false --> JsLoader[mdx-js-loader.js<br/>uses @mdx-js/loader]
    Choose -- true --> RsLoader[mdx-rs-loader.js<br/>uses mdxjs-rs]
    JsLoader --> Compiled[compiled component]
    RsLoader --> Compiled

The Rust loader (mdx-rs-loader.js) is materially faster on cold builds. The JS loader (mdx-js-loader.js) is the default for compatibility with the full remark/rehype plugin ecosystem.

How users wire it up

// next.config.mjs
import nextMdx from '@next/mdx';
import remarkGfm from 'remark-gfm';

const withMDX = nextMdx({
  options: { remarkPlugins: [remarkGfm], rehypePlugins: [] },
});

export default withMDX({
  pageExtensions: ['ts', 'tsx', 'md', 'mdx'],
});

The pageExtensions config tells the framework that .md/.mdx files in app/ or pages/ should be treated as routes.

mdx-components.js

packages/next-mdx/mdx-components.js is a tiny default export of mdx-components used to provide React component overrides for HTML elements rendered from MDX. Users typically override it in their own mdx-components.tsx at the root of the App Router.

Turbopack support

When Turbopack is the bundler, MDX is handled by turbopack/crates/turbopack-mdx/. The Rust crate uses the same mdxjs-rs compiler as the webpack mdx-rs-loader.js, so behavior matches across bundlers.

Key source files

File	Purpose
packages/next-mdx/index.js	Plugin that wraps next.config
packages/next-mdx/mdx-js-loader.js	webpack loader using JavaScript MDX compiler
packages/next-mdx/mdx-rs-loader.js	webpack loader using Rust MDX compiler
turbopack/crates/turbopack-mdx/	Turbopack MDX module type