Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@next/mdx) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

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

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.