How to Fix: Dev server not working when using `@next/mdx` with plugins and `–turbo`

The failure is not in your MDX content—it is in the compiler pipeline. When @next/mdx is configured with custom remark/rehype plugins and the app is started with next dev –turbo, Turbopack currently cannot execute that MDX plugin chain the same way the classic webpack-based dev server can. The result is a dev server that crashes, hangs, or fails to compile pages that otherwise work without --turbo.

Understanding the Root Cause

This issue happens because Turbopack support for MDX plugin transforms is not fully compatible with the configuration path used by @next/mdx when external plugins are involved. In a standard setup, @next/mdx passes MDX files through a compilation stage that can apply remark plugins, rehype plugins, and other AST-based transforms.

With the classic Next.js dev server, that plugin chain is handled through the established webpack integration. With –turbo, the development server switches to Turbopack, which has historically had feature gaps compared to webpack, especially around advanced loader behavior and plugin-driven content transforms.

In practical terms, the problem usually looks like this:

• MDX without plugins works
• MDX with plugins works without –turbo
• MDX with plugins fails with –turbo

That pattern strongly indicates the breakage is not caused by your content or your plugin syntax alone, but by the current state of Turbopack compatibility for that specific MDX processing path.

If your repository reproduces the bug only when both conditions are true—@next/mdx plugins are enabled and next dev --turbo is used—then the root cause is a tooling limitation, not an application logic bug.

Step-by-Step Solution

The most reliable fix today is to disable Turbopack for local development in projects that rely on MDX plugins.

1. Update your development script

Open package.json and remove --turbo from the dev command.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

If your current script looks like this:

{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

change it to:

{
  "scripts": {
    "dev": "next dev"
  }
}

2. Keep your MDX plugin configuration as-is

Your existing next.config.js or next.config.mjs can still use @next/mdx with plugins. For example:

import createMDX from '@next/mdx'
import remarkGfm from 'remark-gfm'

const withMDX = createMDX({
  options: {
    remarkPlugins: [remarkGfm],
    rehypePlugins: []
  }
})

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx']
}

export default withMDX(nextConfig)

The important change is not the MDX config itself. The important change is running the project with the webpack-based dev server until Turbopack support for this scenario is stable.

3. Reinstall and restart cleanly

After changing scripts, clear cached output and restart development.

rm -rf .next
npm install
npm run dev

If you use Yarn or pnpm:

rm -rf .next
yarn install
yarn dev

rm -rf .next
pnpm install
pnpm dev

4. Confirm the issue is specifically tied to Turbopack

A good verification step is to compare both modes:

next dev

and:

next dev --turbo

If the first works and the second fails, you have confirmed the bug is a Turbopack + MDX plugins compatibility issue.

5. Optional temporary workaround: remove plugins if Turbopack is mandatory

If you must use –turbo for a local experiment, the only temporary workaround may be to remove the custom MDX plugins.

import createMDX from '@next/mdx'

const withMDX = createMDX({
  options: {
    remarkPlugins: [],
    rehypePlugins: []
  }
})

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx']
}

export default withMDX(nextConfig)

This is not the ideal fix, because it changes behavior and may remove features such as GitHub Flavored Markdown, heading transforms, syntax enhancements, or custom HTML processing. But it can help isolate the issue or unblock a short-term test.

6. Track framework updates

Because this is a framework-level compatibility issue, the long-term resolution will usually come from a Next.js, Turbopack, or @next/mdx update. Monitor the relevant repository and release notes through the Next.js GitHub project.

Common Edge Cases

Plugin package format mismatch

Some MDX plugins are ESM-only. If your config file or import style does not match the package format, you may see errors that look similar but are unrelated to Turbopack.

import remarkGfm from 'remark-gfm'

If you are mixing CommonJS and ESM carelessly, fix that first.

Using unsupported plugin options

A plugin may work in one environment and fail in another if it depends on Node.js APIs, dynamic imports, or assumptions about how the compiler executes transforms.

If disabling a single plugin makes the issue disappear, test each plugin independently.

App Router vs Pages Router confusion

Make sure your MDX integration matches your routing model. An MDX setup for the Pages Router may differ from one used in the App Router, especially around file placement and rendering behavior.

Stale build cache

Old cached artifacts in .next can make the issue appear inconsistent. Always clear the cache after changing build tooling or MDX config.

Version drift across Next.js and MDX packages

If next, @next/mdx, and plugin packages are on mismatched versions, compatibility problems become harder to diagnose. Keep them aligned and retest before assuming every failure is the same Turbopack bug.

FAQ

Does this mean MDX is broken in Next.js?

No. MDX itself is not the problem. The issue is specific to using MDX plugins together with Turbopack dev mode. In many cases, MDX works correctly without plugins or when using the non-Turbopack dev server.

Can I use Turbopack in production instead?

This issue is about the development server path triggered by next dev --turbo. Production behavior may differ, but if your local compilation pipeline is failing, you should not assume production will be safe without testing carefully.

What is the safest fix for teams right now?

The safest fix is to remove –turbo from the dev script for projects that depend on @next/mdx with remark or rehype plugins. That preserves plugin functionality and avoids unstable compiler behavior during development.

In short, the correct resolution for this GitHub issue is to treat it as a current Turbopack limitation. If your project needs plugin-powered MDX today, use next dev without –turbo until upstream support catches up.