0
# @next/mdx
1

2
@next/mdx is a Next.js plugin that enables MDX (Markdown with JSX) support in Next.js applications. It allows developers to write JSX components directly within markdown files, supporting both traditional pages directory and modern app directory patterns.
3

4
## Package Information
5

6
- **Package Name**: @next/mdx
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install @next/mdx @mdx-js/loader @mdx-js/react`
10

11
## Core Imports
12

13
```javascript
14
const withMDX = require('@next/mdx');
15
```
16

17
For TypeScript (import types only):
18

19
```typescript
20
import type { NextMDXOptions } from '@next/mdx';
21
```
22

23
ES Module import (with TypeScript/Babel transpilation):
24

25
```typescript
26
import withMDX from '@next/mdx';
27
```
28

29
## Basic Usage
30

31
```javascript
32
// next.config.js
33
const withMDX = require('@next/mdx')();
34

35
module.exports = withMDX({
36
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
37
});
38
```
39

40
With custom configuration:
41

42
```javascript
43
// next.config.js
44
const withMDX = require('@next/mdx')({
45
  extension: /\.mdx?$/,
46
  options: {
47
    remarkPlugins: [],
48
    rehypePlugins: [],
49
  },
50
});
51

52
module.exports = withMDX({
53
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
54
});
55
```
56

57
## Capabilities
58

59
### MDX Configuration Function
60

61
Creates a Next.js configuration wrapper that enables MDX processing.
62

63
```typescript { .api }
64
/**
65
 * Creates a Next.js configuration wrapper that enables MDX processing
66
 * @param options - Optional configuration for MDX processing
67
 * @returns WithMDX function that accepts and transforms Next.js config
68
 */
69
declare function nextMDX(options?: NextMDXOptions): WithMDX;
70
```
71

72
**Parameters:**
73
- `options` (optional): Configuration object of type `NextMDXOptions`
74

75
**Returns:** `WithMDX` function that transforms Next.js configuration
76

77
**Usage Examples:**
78

79
```javascript
80
// Basic usage
81
const withMDX = require('@next/mdx')();
82
module.exports = withMDX();
83

84
// With extension configuration
85
const withMDX = require('@next/mdx')({
86
  extension: /\.(md|mdx)$/,
87
});
88

89
// With MDX options
90
const withMDX = require('@next/mdx')({
91
  options: {
92
    remarkPlugins: [remarkGfm],
93
    rehypePlugins: [rehypeHighlight],
94
    providerImportSource: '@mdx-js/react',
95
  },
96
});
97

98
// Applied to Next.js config
99
module.exports = withMDX({
100
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
101
  reactStrictMode: true,
102
});
103
```
104

105
### Configuration Wrapper Function
106

107
The function returned by `nextMDX` that wraps Next.js configuration.
108

109
```typescript { .api }
110
/**
111
 * Function that wraps Next.js configuration to add MDX support
112
 * @param config - Next.js configuration object (optional, defaults to empty object)
113
 * @returns Enhanced Next.js configuration with MDX support
114
 */
115
type WithMDX = (config?: NextConfig) => NextConfig;
116
```
117

118
**Parameters:**
119
- `config` (optional): Next.js configuration object (defaults to empty object if not provided)
120

121
**Returns:** Enhanced Next.js configuration with MDX webpack rules and aliases
122

123
## Types
124

125
```typescript { .api }
126
// External types from dependencies
127
type NextConfig = import('next').NextConfig;
128
type Options = import('@mdx-js/loader').Options;
129
type RuleSetConditionAbsolute = import('webpack').RuleSetConditionAbsolute;
130

131
interface NextMDXOptions {
132
  /**
133
   * A webpack rule test to match files to treat as MDX.
134
   * @default /\.mdx$/
135
   * @example /\.mdx?$/ // Support both .md and .mdx files
136
   */
137
  extension?: RuleSetConditionAbsolute;
138

139
  /**
140
   * Options to pass to the MDX loader
141
   * @see https://mdxjs.com/packages/mdx/#api
142
   */
143
  options?: Options;
144
}
145

146
/**
147
 * Function type that transforms Next.js configuration to add MDX support
148
 * Note: Runtime allows config to be omitted (defaults to empty object)
149
 */
150
type WithMDX = (config?: NextConfig) => NextConfig;
151
```
152

153
## Configuration Details
154

155
### File Extension Handling
156

157
- **Default behavior**: Processes `.mdx` files only
158
- **Configurable**: Use `extension` option to support `.md` files or custom patterns
159
- **Page extensions**: Configure `pageExtensions` in Next.js config to treat MDX files as pages
160

161
### Loader Selection
162

163
The plugin automatically selects the appropriate loader based on Next.js configuration:
164

165
- **Standard mode**: Uses `@mdx-js/loader` for processing MDX files (default behavior)
166
- **Experimental mode**: Uses internal Rust-based loader (`mdx-rs-loader.js`) when `experimental.mdxRs` is enabled in Next.js config
167
- **Provider import**: Automatically configures MDX component resolution via `providerImportSource: 'next-mdx-import-source-file'`
168

169
**Experimental Rust Loader:**
170

171
When `experimental.mdxRs` is enabled in Next.js config, @next/mdx automatically switches to a Rust-based MDX compiler for improved performance:
172

173
```javascript
174
// next.config.js - Enable experimental Rust loader
175
const withMDX = require('@next/mdx')();
176

177
module.exports = withMDX({
178
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
179
  experimental: {
180
    mdxRs: true, // Enables Rust-based MDX compilation
181
  },
182
});
183
```
184

185
The Rust loader supports both `.md` and `.mdx` files and provides the same API as the standard loader but with faster compilation times.
186

187
### Webpack Integration
188

189
The plugin automatically:
190
- Adds webpack rules for MDX file processing
191
- Configures webpack alias `next-mdx-import-source-file` for component resolution
192
- Resolves MDX components in this priority order:
193
  1. `private-next-root-dir/src/mdx-components`
194
  2. `private-next-root-dir/mdx-components` 
195
  3. `@mdx-js/react`
196
- Integrates with Next.js default Babel loader
197

198
### App Directory Usage
199

200
For Next.js app directory, create `mdx-components.js`:
201

202
```javascript
203
// mdx-components.js
204
export function useMDXComponents(components) {
205
  return {
206
    // Customize built-in components
207
    h1: ({ children }) => <h1 style={{ color: 'blue' }}>{children}</h1>,
208
    ...components,
209
  };
210
}
211
```
212

213
### Dependencies
214

215
**Direct dependencies:**
216
- `source-map`: "^0.7.0"
217

218
**Peer dependencies (optional):**
219
- `@mdx-js/loader`: ">=0.15.0"
220
- `@mdx-js/react`: ">=0.15.0"
221

222
## Common Patterns
223

224
### Pages Directory Pattern
225

226
```javascript
227
// next.config.js
228
const withMDX = require('@next/mdx')({
229
  extension: /\.mdx?$/,
230
});
231

232
module.exports = withMDX({
233
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
234
});
235
```
236

237
### App Directory Pattern
238

239
```javascript
240
// next.config.js
241
const withMDX = require('@next/mdx')({
242
  options: {
243
    remarkPlugins: [],
244
    rehypePlugins: [],
245
  },
246
});
247

248
module.exports = withMDX({
249
  pageExtensions: ['ts', 'tsx', 'js', 'jsx', 'md', 'mdx'],
250
});
251
```