Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mdx (default export)
✓ import mdx from 'vite-plugin-mdx'
✗ const mdx = require('vite-plugin-mdx')
ESM-only; CommonJS require is not supported.
Vite Plugin Options
✓ import type { Plugin } from 'vite'
import mdx from 'vite-plugin-mdx'
// or for TypeScript: import mdx from 'vite-plugin-mdx'
// The plugin returns a Vite Plugin instance.
✗ const mdx = require('vite-plugin-mdx').default
CommonJS require is not available; use ESM import.
(no named exports)
✓ import mdx from 'vite-plugin-mdx'
✗ import { mdx } from 'vite-plugin-mdx'
vite-plugin-mdx uses a default export only. Named exports like `mdx` are not available.
Sets up vite-plugin-mdx with Vite and shows MDX usage with a React counter component.
// vite.config.js
import { defineConfig } from 'vite'
import mdx from 'vite-plugin-mdx'
const options = {
remarkPlugins: [
// e.g. require('remark-frontmatter')
],
rehypePlugins: [],
}
export default defineConfig({
plugins: [mdx(options)]
})
// hello.mdx
// ---
// title: Hello
// ---
// import { Counter } from './Counter.jsx'
//
// # Hello
//
// This text is written in Markdown.
//
// MDX allows Rich React components to be used directly in Markdown: <Counter/>
// Counter.jsx
import React, { useState } from 'react'
function Counter() {
const [count, setCount] = useState(0)
return (
<button onClick={() => setCount(c => c + 1)}>
Counter: {count}
</button>
)
}
export { Counter }
Errors
Common errors & fixes
Error: Cannot find module 'vite-plugin-mdx'
Missing npm install of vite-plugin-mdx.
fixRun `npm install vite-plugin-mdx`.
SyntaxError: Cannot use import statement outside a module
Using ESM in a CommonJS environment without type:module or .mjs extension.
fixEnsure package.json has "type": "module" or rename file to .mjs.
TypeError: mdx is not a function
Using a named import `{ mdx }` instead of default import.
fixUse `import mdx from 'vite-plugin-mdx'`.
Error: The package `@mdx-js/mdx` is not installed
Missing peer dependency @mdx-js/mdx.
fixRun `npm install @mdx-js/mdx@1` (MDX v1).
Error: Unsupported MDX version. Required: <2.
Using MDX v2 which is not supported by vite-plugin-mdx >=3.6.0.
fixDowngrade to @mdx-js/mdx@1 or migrate to @mdx-js/rollup for MDX v2.
Audit
Dependencies
@mdx-js/mdxrequiredCore MDX compiler used to transform MDX files - peer dependency
viterequiredVite build tool - peer dependency