esbuild-mdx

library0.2.0jsnpmunverified

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.

web-framework

npm install esbuild-mdx

github ↗package ↗

INSTALL

IMPORT

SIG · ESBUILD-MDX

esbuild-mdx

web-frameworkjavascriptv0.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (plugin creator)

✓ const mdxPlugin = require('esbuild-mdx')()

✗ import mdxPlugin from '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

✓ import * as esbuild from 'esbuild'

✗ const esbuild = require('esbuild')

esbuild itself supports both ESM and CJS import styles. The import style must match the module system of your esbuild script.

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'));

Debug

Known issues

breakingVersion 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: [] })

affects: <0.2.0

deprecatedThe 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+.

affects: >=0.2.0

gotchaBecause 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.

affects: >=0.0.0

gotchaThe 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.

affects: >=0.0.0

breakingNo 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.

affects: >=0.0.0

Errors

Common errors & fixes

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

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

fix

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

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

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

fix

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

Error: Cannot find module 'esbuild-mdx'

esbuild-mdx is not installed in node_modules.

fix

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

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

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: [plugin esbuild-mdx] Expected value of type 'object' for options

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')({})

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

@mdx-js/reactrequiredPeer dependency for rendering MDX components

reactrequiredPeer dependency

react-domrequiredPeer dependency

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/zaydek/esbuild-mdx ↗

packagehttps://www.npmjs.com/package/esbuild-mdx ↗