Next.js + MDX

Use MDX with Next.js

Installation

For usage with the app directory see the section below.

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

or

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

Usage

Create a next.config.js in your project

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

Optionally you can provide MDX plugins:

// 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

// 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:

// 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 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:

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

TypeScript

Follow this guide 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:

// This file is required to use @next/mdx in the `app` directory.
export function useMDXComponents(components) {
  return components
  // Allows customizing built-in components, e.g. to add styling.
  // return {
  //   h1: ({ children }) => <h1 style={{ fontSize: "100px" }}>{children}</h1>,
  //   ...components,
  // }
}

Create a next.config.js in your project

// 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 from the MDX docs.