esbuild-mdx

0.2.0 verified Fri May 01 auth: no javascript

esbuild-mdx is a plugin for esbuild that resolves .md and .mdx files into React components, enabling markdown-driven content in React apps. Current stable version is 0.2.0 (released 2021), with a low release cadence (3 releases). Key differentiators: integrates directly with esbuild's plugin system, supports options passing to MDX, and is lightweight compared to Webpack-based MDX bundlers. Alternative to @mdx-js/loader but for esbuild. Minimum peer dependencies: react, react-dom, and @mdx-js/react.

Common errors

error Error: Plugin esbuild-mdx: Cannot find module '@mdx-js/react' ↓

cause @mdx-js/react is a peer dependency but not installed.

fix

Run: npm install @mdx-js/react@^1.6.22

error TypeError: require(...) is not a function ↓

cause Forgetting to invoke the plugin creator function: require('esbuild-mdx') instead of require('esbuild-mdx')()

fix

Correct: require('esbuild-mdx')()

error Error: Cannot find module 'esbuild-mdx' ↓

cause esbuild-mdx is not installed in node_modules.

fix

Run: npm install esbuild-mdx --save-dev

error Error: MDX components must be imported with .mdx extension, got .md ↓

cause The plugin supports both .md and .mdx files, but esbuild may not resolve .md without proper configuration.

fix

Ensure your esbuild entry points or resolve extensions include .md and .mdx, e.g., resolveExtensions: ['.js', '.md', '.mdx']

error Error: [plugin esbuild-mdx] Expected value of type 'object' for options ↓

cause Passing a non-object argument to the plugin creator (e.g., a string)

fix

Call require('esbuild-mdx')() with no arguments or an options object: require('esbuild-mdx')({})

Warnings

breaking Version 0.2.0 changed the plugin invocation pattern from requiring options differently. Use require('esbuild-mdx')() with empty call if no options. ↓

fix Update to 0.2.0 and pass options object to the function if needed, e.g., require('esbuild-mdx')({ remarkPlugins: [] })

deprecated The package relies on @mdx-js/react v1; newer versions of @mdx-js/react (v2+) are incompatible. ↓

fix Use @mdx-js/react@^1.6.22 exactly. Do not upgrade to v2+.

gotcha Because this is an esbuild plugin, it cannot be used in a browser environment directly; it's intended for build-time bundling. ↓

fix Ensure you only use esbuild-mdx in a Node.js build script, not in client-side code.

gotcha The package only exports a CommonJS module. If you are using ESM for your esbuild config, you may need to use dynamic import for the plugin. ↓

fix Use const mdxPlugin = (await import('esbuild-mdx')).default() in an ESM context.

breaking No ESM export is provided; attempting to import { default } from 'esbuild-mdx' will fail with a parse error. ↓

fix Use require() or dynamic import with .default.

Install

npm install esbuild-mdx

yarn add esbuild-mdx

pnpm add esbuild-mdx

Imports

default (plugin creator)
wrong
```
import mdxPlugin from 'esbuild-mdx'()
```
correct
```
const mdxPlugin = require('esbuild-mdx')()
```
The package exports a default function that returns a plugin instance. It is CommonJS-only (no ESM export). Ensure you invoke the function with parentheses.
esbuild
wrong
```
const esbuild = require('esbuild')
```
correct
```
import * as esbuild from 'esbuild'
```
esbuild itself supports both ESM and CJS import styles. The import style must match the module system of your esbuild script.

Quickstart

Shows how to set up esbuild with esbuild-mdx plugin and import a .md file as a React component.

// esbuild.js (CJS)
const esbuild = require('esbuild');
const mdxPlugin = require('esbuild-mdx')();

esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [mdxPlugin],
}).catch(() => process.exit(1));

// Your React component
import React from 'react';
import ReactDOM from 'react-dom';
import MarkdownComponent from './example.md';

function App() {
  return (
    <div>
      <MarkdownComponent />
    </div>
  );
}

ReactDOM.render(<App />, document.getElementById('root'));