Installing MDX - Complete Setup Guide

How to get MDX installed and working with your bundler. Covers npm packages, Next.js, Vite, and webpack configs — plus fixing the errors you

MDX lets you drop React components right into your Markdown. But before you can do that, you need to install the right packages and tell your bundler how to handle .mdx files.

Let's get you set up.

Prerequisites

You need two things on your machine before we start:

Node.js

MDX needs Node.js 16 or higher. Check what you've got:

bash example

node --version

Output

v20.11.0

If you're behind, grab the latest from nodejs.org or use nvm:

bash example

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install the latest LTS version
nvm install --lts
nvm use --lts

Package Manager

Pick one — npm, yarn, or pnpm. They all work fine:

bash example

# Verify your package manager
npm --version
yarn --version
pnpm --version

Output

10.2.4
1.22.19
8.14.0

💡 Tip: No strong preference? Go with pnpm. It's strict about dependencies, which saves you from weird phantom-dependency bugs down the road.

Next.js Integration

Next.js has great MDX support. You've got two options depending on how your content works:

@next/mdx (MDX files as pages)

Use this when your .mdx files live in your project and you want them treated as pages or importable modules.

bash example

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

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

# pnpm
pnpm add @next/mdx @mdx-js/loader @mdx-js/react

Then update your next.config.mjs:

Example

import createMDX from '@next/mdx'; /** @type {import('next').NextConfig} */ const nextConfig = { // Allow .mdx extensions for files pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'], }; const withMDX = createMDX({ // Add markdown plugins here options: { remarkPlugins: [], rehypePlugins: [], }, }); // Merge MDX config with Next.js config export default withMDX(nextConfig);

next-mdx-remote (Content from a CMS or database)

Use this when your MDX content doesn't live in your source code — maybe it comes from a CMS, a database, or an API.

bash example

# npm
npm install next-mdx-remote

# yarn
yarn add next-mdx-remote

# pnpm
pnpm add next-mdx-remote

Here's how you'd use it with the App Router:

Example

// app/blog/[slug]/page.js import { MDXRemote } from 'next-mdx-remote/rsc'; import { getPostBySlug } from '@/lib/posts'; export default async function BlogPost({ params }) { const post = await getPostBySlug(params.slug); return ( <article> <h1>{post.title}</h1> <MDXRemote source={post.content} /> </article> ); }

💡 Tip: Using the App Router? Import from next-mdx-remote/rsc for server component support. On the Pages Router, use the standard next-mdx-remote imports with serialize and MDXRemote.

Webpack Configuration

Running a custom webpack setup without a framework? Here's what you need:

bash example

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

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

# pnpm
pnpm add @mdx-js/loader @mdx-js/mdx @mdx-js/react

Add the MDX loader to your webpack.config.js:

Example

module.exports = { module: { rules: [ { test: /\.mdx?$/, use: [ { loader: 'babel-loader', options: { presets: ['@babel/preset-react'] }, }, { loader: '@mdx-js/loader', options: { remarkPlugins: [], rehypePlugins: [], }, }, ], }, ], }, };

Vite Configuration

Vite uses the Rollup plugin:

bash example

# npm
npm install @mdx-js/rollup @mdx-js/react

# yarn
yarn add @mdx-js/rollup @mdx-js/react

# pnpm
pnpm add @mdx-js/rollup @mdx-js/react

Configure vite.config.js:

Example

import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import mdx from '@mdx-js/rollup'; export default defineConfig({ plugins: [ { enforce: 'pre', ...mdx() }, react({ include: /\.(jsx|js|mdx|md|tsx|ts)$/ }), ], });

⚠️ Warning: That enforce: 'pre' bit is important. Without it, Vite processes files in the wrong order and you'll get cryptic compilation errors.

Optional: Useful Plugins

These remark/rehype plugins are worth grabbing for most projects:

bash example

# Syntax highlighting
npm install rehype-highlight

# GitHub Flavored Markdown (tables, strikethrough, etc.)
npm install remark-gfm

# Auto-link headings
npm install rehype-slug rehype-autolink-headings

# Math/LaTeX support
npm install remark-math rehype-katex

Troubleshooting Common Issues

Error: "Cannot find module '@mdx-js/react'"

Usually means it's not installed, or your lockfile is out of sync:

bash example

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Error: "Unexpected token" when importing .mdx files

Your bundler doesn't know what to do with .mdx files. Double-check that the MDX loader or plugin is actually registered in your config.

Error: "React is not defined" in MDX files

MDX v2+ uses the automatic JSX runtime. If you're seeing this, tell Babel to use it:

Example

{ "presets": [ ["@babel/preset-react", { "runtime": "automatic" }] ] }

Version Conflicts Between MDX v1 and v2/v3

Upgrading from v1? Rip out the old packages first, then install fresh:

bash example

npm uninstall @mdx-js/mdx @mdx-js/react @mdx-js/loader
npm install @mdx-js/mdx@latest @mdx-js/react@latest @mdx-js/loader@latest

TypeScript Support

Add the MDX type definitions so TypeScript stops complaining:

bash example

npm install --save-dev @types/mdx

Then add to your tsconfig.json:

Example

{ "compilerOptions": { "types": ["@types/mdx"] } }

Verifying Your Installation

Quick sanity check — create a test file and see if it compiles:

bash example

# Create a test file
echo '# Hello MDX\n\nThis is **working**!' > test.mdx

Output

# test.mdx created successfully
# Your build tool should compile it without errors

If your build runs clean, you're good to go.

Summary

Here's the cheat sheet:

Core packages: @mdx-js/mdx (compiler) + @mdx-js/react (React glue)
Next.js: @next/mdx for file-based MDX, next-mdx-remote for dynamic content
Webpack: Add @mdx-js/loader to your module rules
Vite: Use @mdx-js/rollup with enforce: 'pre'
Always match package versions — don't mix v1 and v2/v3
Grab remark/rehype plugins for syntax highlighting, GFM tables, etc.

You're installed. Next up: creating your first MDX file.

MDX lets you drop React components right into your Markdown. But before you can do that, you need to install the right packages and tell your bundler how to handle .mdx files.

Let's get you set up.

Prerequisites

You need two things on your machine before we start:

Node.js

MDX needs Node.js 16 or higher. Check what you've got:

bash example

node --version

Output

v20.11.0

If you're behind, grab the latest from nodejs.org or use nvm:

bash example

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install the latest LTS version
nvm install --lts
nvm use --lts

Package Manager

Pick one — npm, yarn, or pnpm. They all work fine:

bash example

# Verify your package manager
npm --version
yarn --version
pnpm --version

Output

10.2.4
1.22.19
8.14.0

💡 Tip: No strong preference? Go with pnpm. It's strict about dependencies, which saves you from weird phantom-dependency bugs down the road.

Next.js Integration

Next.js has great MDX support. You've got two options depending on how your content works:

@next/mdx (MDX files as pages)

Use this when your .mdx files live in your project and you want them treated as pages or importable modules.

bash example

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

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

# pnpm
pnpm add @next/mdx @mdx-js/loader @mdx-js/react

Then update your next.config.mjs:

Example

next-mdx-remote (Content from a CMS or database)

Use this when your MDX content doesn't live in your source code — maybe it comes from a CMS, a database, or an API.

bash example

# npm
npm install next-mdx-remote

# yarn
yarn add next-mdx-remote

# pnpm
pnpm add next-mdx-remote

Here's how you'd use it with the App Router:

Example

💡 Tip: Using the App Router? Import from next-mdx-remote/rsc for server component support. On the Pages Router, use the standard next-mdx-remote imports with serialize and MDXRemote.

Webpack Configuration

Running a custom webpack setup without a framework? Here's what you need:

bash example

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

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

# pnpm
pnpm add @mdx-js/loader @mdx-js/mdx @mdx-js/react

Add the MDX loader to your webpack.config.js:

Example

Vite Configuration

Vite uses the Rollup plugin:

bash example

# npm
npm install @mdx-js/rollup @mdx-js/react

# yarn
yarn add @mdx-js/rollup @mdx-js/react

# pnpm
pnpm add @mdx-js/rollup @mdx-js/react

Configure vite.config.js:

Example

⚠️ Warning: That enforce: 'pre' bit is important. Without it, Vite processes files in the wrong order and you'll get cryptic compilation errors.

Optional: Useful Plugins

These remark/rehype plugins are worth grabbing for most projects:

bash example

# Syntax highlighting
npm install rehype-highlight

# GitHub Flavored Markdown (tables, strikethrough, etc.)
npm install remark-gfm

# Auto-link headings
npm install rehype-slug rehype-autolink-headings

# Math/LaTeX support
npm install remark-math rehype-katex

Troubleshooting Common Issues

Error: "Cannot find module '@mdx-js/react'"

Usually means it's not installed, or your lockfile is out of sync:

bash example

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Error: "Unexpected token" when importing .mdx files

Your bundler doesn't know what to do with .mdx files. Double-check that the MDX loader or plugin is actually registered in your config.

Error: "React is not defined" in MDX files

MDX v2+ uses the automatic JSX runtime. If you're seeing this, tell Babel to use it:

Example

{ "presets": [ ["@babel/preset-react", { "runtime": "automatic" }] ] }

Version Conflicts Between MDX v1 and v2/v3

Upgrading from v1? Rip out the old packages first, then install fresh:

bash example

npm uninstall @mdx-js/mdx @mdx-js/react @mdx-js/loader
npm install @mdx-js/mdx@latest @mdx-js/react@latest @mdx-js/loader@latest

TypeScript Support

Add the MDX type definitions so TypeScript stops complaining:

bash example

npm install --save-dev @types/mdx

Then add to your tsconfig.json:

Example

{ "compilerOptions": { "types": ["@types/mdx"] } }

Verifying Your Installation

Quick sanity check — create a test file and see if it compiles:

bash example

# Create a test file
echo '# Hello MDX\n\nThis is **working**!' > test.mdx

Output

# test.mdx created successfully
# Your build tool should compile it without errors

If your build runs clean, you're good to go.

Summary

Here's the cheat sheet:

Core packages: @mdx-js/mdx (compiler) + @mdx-js/react (React glue)
Next.js: @next/mdx for file-based MDX, next-mdx-remote for dynamic content
Webpack: Add @mdx-js/loader to your module rules
Vite: Use @mdx-js/rollup with enforce: 'pre'
Always match package versions — don't mix v1 and v2/v3
Grab remark/rehype plugins for syntax highlighting, GFM tables, etc.

You're installed. Next up: creating your first MDX file.

Installing MDX - Complete Setup Guide

Prerequisites

Node.js

Package Manager

Next.js Integration

@next/mdx (MDX files as pages)

next-mdx-remote (Content from a CMS or database)

Webpack Configuration

Vite Configuration

Optional: Useful Plugins

Troubleshooting Common Issues

Error: "Cannot find module '@mdx-js/react'"

Error: "Unexpected token" when importing .mdx files

Error: "React is not defined" in MDX files

Version Conflicts Between MDX v1 and v2/v3

TypeScript Support

Verifying Your Installation

Summary

Continue learning this concept

Installing MDX - Complete Setup Guide

Prerequisites

Node.js

Package Manager

Next.js Integration

@next/mdx (MDX files as pages)

next-mdx-remote (Content from a CMS or database)

Webpack Configuration

Vite Configuration

Optional: Useful Plugins

Troubleshooting Common Issues

Error: "Cannot find module '@mdx-js/react'"

Error: "Unexpected token" when importing .mdx files

Error: "React is not defined" in MDX files

Version Conflicts Between MDX v1 and v2/v3

TypeScript Support

Verifying Your Installation

Summary

Continue learning this concept