# @next/mdx

> Use [MDX](https://github.com/mdx-js/mdx) with [Next.js](https://github.com/vercel/next.js)

Latest version **16.4.6** (published 2026-11-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install @next/mdx
pnpm add @next/mdx
yarn add @next/mdx
bun add @next/mdx
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; popular repo; extremely popular.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 16.4.6 |
| Published | 2026-11-09 |
| First published | 2019-03-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 14.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 143096 |
| Maintainers | vercel-release-bot, matt.straka |

## Links

- npm: https://www.npmjs.com/package/@next/mdx
- Repository: https://github.com/vercel/next.js
- Homepage: https://github.com/vercel/next.js#readme
- Issues: https://github.com/vercel/next.js/issues
- npm.io page: https://npm.io/package/@next/mdx

## Dependencies (1)

- [source-map](https://npm.io/package/source-map.md) ^0.7.0

## Recent versions

- 16.4.6 (latest) — 2026-11-09
- 16.5.0-canary.60 (canary) — 2026-11-21
- 15.5.29 (backport) — 2026-11-03
- 16.3.0-preview.10 (preview) — 2026-07-28
- 15.0.8 (next-15-0-0) — 2026-01-26
- 15.1.12 (next-15-0) — 2026-01-26
- 15.2.9 (next-15-2) — 2026-01-26
- 15.3.9 (next-15-3) — 2026-01-26
- 14.2.35 (next-14) — 2025-12-11
- 16.0.0-beta.0 (beta) — 2025-10-10
- 12.3.7 (next-12-3-2) — 2025-03-28
- 13.5.11 (next-13) — 2025-03-27
- 15.0.0-rc.1 (rc) — 2024-10-15
- 14.1.1 (next-14-1) — 2024-02-29
- 12.2.6 (next-12-2-6) — 2022-09-29
- … 3671 more at https://npm.io/package/@next/mdx/versions

## README

# Next.js + MDX

Use [MDX](https://github.com/mdx-js/mdx) with [Next.js](https://github.com/vercel/next.js)

## Installation

For usage with the `app` directory see the section below.

```
npm install @next/mdx @mdx-js/loader
```

or

```
yarn add @next/mdx @mdx-js/loader
```

## Usage

Create a `next.config.js` in your project

```js
// next.config.js
const withMDX = require('@next/mdx')()
module.exports = withMDX()
```

Optionally you can provide [MDX plugins](https://mdxjs.com/advanced/plugins#plugins):

```js
// next.config.js
const withMDX = require('@next/mdx')({
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
})
module.exports = withMDX()
```

Optionally you can add your custom Next.js configuration as parameter

```js
// next.config.js
const withMDX = require('@next/mdx')()
module.exports = withMDX({
  webpack(config, options) {
    return config
  },
})
```

By default MDX will only match and compile MDX files with the `.mdx` extension.
However, it can also be optionally configured to handle markdown files with the `.md` extension, as shown below:

```js
// next.config.js
const withMDX = require('@next/mdx')({
  extension: /\.(md|mdx)$/,
})
module.exports = withMDX()
```

In addition, MDX can be customized with compiler options, see the [mdx documentation](https://mdxjs.com/packages/mdx/#compilefile-options) for details on supported options.

## Top level .mdx pages

Define the `pageExtensions` option to have Next.js handle `.md` and `.mdx` files in the `pages` directory as pages:

```js
// next.config.js
const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
})
module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
})
```

## TypeScript

Follow [this guide](https://mdxjs.com/advanced/typescript) from the MDX docs.

---

# App directory

## Installation

For usage with the `app` directory see below.

```
npm install @next/mdx
```

or

```
yarn add @next/mdx
```

## Usage

Create an `mdx-components.js` file at the root of your project with the following contents:

```js
// Allows customizing built-in components, e.g. to add styling.
const components = {
  // h1: ({ children }) => <h1 style={{ fontSize: "100px" }}>{children}</h1>,
}

export function useMDXComponents() {
  return components
}
```

Create a `next.config.js` in your project

```js
// next.config.js
const withMDX = require('@next/mdx')({
  // Optionally provide remark and rehype plugins
  options: {
    // If you use remark-gfm, you'll need to use next.config.mjs
    // as the package is ESM only
    // https://github.com/remarkjs/remark-gfm#install
    remarkPlugins: [],
    rehypePlugins: [],
  },
})

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Configure pageExtensions to include md and mdx
  pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
  // Optionally, add any other Next.js config below
  reactStrictMode: true,
}

// Merge MDX config with Next.js config
module.exports = withMDX(nextConfig)
```

## TypeScript

Follow [this guide](https://mdxjs.com/advanced/typescript) from the MDX docs.

---
_Source: https://npm.io/package/@next/mdx · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
