vite-plugin-mdx

3.6.1 verified Mon Apr 27 auth: no javascript deprecated

Vite plugin for using MDX v1 with Vite v2. Version 3.6.1 locks peer dependencies to @mdx-js/mdx <2 and vite <3. The project is no longer actively maintained; the README recommends migrating to MDX v2 with @mdx-js/rollup for Vite v3+. Key differentiators: works with React and Preact, supports HMR and SSR, remark/rehype plugins, and pre-built transclusion of other MDX/MD files. TypeScript types are included.

Common errors

error Error: Cannot find module 'vite-plugin-mdx' ↓

cause Missing npm install of vite-plugin-mdx.

fix

Run npm install vite-plugin-mdx.

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM in a CommonJS environment without type:module or .mjs extension.

fix

Ensure package.json has "type": "module" or rename file to .mjs.

error TypeError: mdx is not a function ↓

cause Using a named import `{ mdx }` instead of default import.

fix

Use import mdx from 'vite-plugin-mdx'.

error Error: The package `@mdx-js/mdx` is not installed ↓

cause Missing peer dependency @mdx-js/mdx.

fix

Run npm install @mdx-js/mdx@1 (MDX v1).

error Error: Unsupported MDX version. Required: <2. ↓

cause Using MDX v2 which is not supported by vite-plugin-mdx >=3.6.0.

fix

Downgrade to @mdx-js/mdx@1 or migrate to @mdx-js/rollup for MDX v2.

Warnings

deprecated Project is no longer actively maintained; looking for a maintainer. ↓

fix Migrate to MDX v2 with @mdx-js/rollup for Vite v3+.

breaking Peer dependencies locked to @mdx-js/mdx <2 and vite <3 in v3.6.0+. ↓

fix If using MDX v2 or Vite v3+, switch to @mdx-js/rollup.

gotcha Only defaults export is available; named imports do not work. ↓

fix Use `import mdx from 'vite-plugin-mdx'`.

gotcha Vue support is marked as Work In Progress and may not function correctly. ↓

fix Consider using @mdx-js/vue instead.

deprecated The plugin is only compatible with MDX v1; MDX v2 requires a different setup. ↓

fix Use @mdx-js/rollup with MDX v2.

Install

npm install vite-plugin-mdx

yarn add vite-plugin-mdx

pnpm add vite-plugin-mdx

Imports

mdx (default export)

wrong

const mdx = require('vite-plugin-mdx')

correct

import mdx from 'vite-plugin-mdx'

ESM-only; CommonJS require is not supported.

Vite Plugin Options

wrong

const mdx = require('vite-plugin-mdx').default

correct

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.

CommonJS require is not available; use ESM import.

(no named exports)
wrong
```
import { mdx } from 'vite-plugin-mdx'
```
correct
```
import mdx from 'vite-plugin-mdx'
```
vite-plugin-mdx uses a default export only. Named exports like `mdx` are not available.

Quickstart

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 }