{"id":25299,"library":"esbuild-mdx","title":"esbuild-mdx","description":"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.","status":"active","version":"0.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/zaydek/esbuild-mdx","tags":["javascript"],"install":[{"cmd":"npm install esbuild-mdx","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-mdx","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-mdx","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for rendering MDX components","package":"@mdx-js/react","optional":false},{"reason":"Peer dependency","package":"react","optional":false},{"reason":"Peer dependency","package":"react-dom","optional":false}],"imports":[{"note":"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.","wrong":"import mdxPlugin from 'esbuild-mdx'()","symbol":"default (plugin creator)","correct":"const mdxPlugin = require('esbuild-mdx')()"},{"note":"esbuild itself supports both ESM and CJS import styles. The import style must match the module system of your esbuild script.","wrong":"const esbuild = require('esbuild')","symbol":"esbuild","correct":"import * as esbuild from 'esbuild'"}],"quickstart":{"code":"// esbuild.js (CJS)\nconst esbuild = require('esbuild');\nconst mdxPlugin = require('esbuild-mdx')();\n\nesbuild.build({\n  entryPoints: ['src/index.js'],\n  bundle: true,\n  outfile: 'dist/out.js',\n  plugins: [mdxPlugin],\n}).catch(() => process.exit(1));\n\n// Your React component\nimport React from 'react';\nimport ReactDOM from 'react-dom';\nimport MarkdownComponent from './example.md';\n\nfunction App() {\n  return (\n    <div>\n      <MarkdownComponent />\n    </div>\n  );\n}\n\nReactDOM.render(<App />, document.getElementById('root'));","lang":"javascript","description":"Shows how to set up esbuild with esbuild-mdx plugin and import a .md file as a React component."},"warnings":[{"fix":"Update to 0.2.0 and pass options object to the function if needed, e.g., require('esbuild-mdx')({ remarkPlugins: [] })","message":"Version 0.2.0 changed the plugin invocation pattern from requiring options differently. Use require('esbuild-mdx')() with empty call if no options.","severity":"breaking","affected_versions":"<0.2.0"},{"fix":"Use @mdx-js/react@^1.6.22 exactly. Do not upgrade to v2+.","message":"The package relies on @mdx-js/react v1; newer versions of @mdx-js/react (v2+) are incompatible.","severity":"deprecated","affected_versions":">=0.2.0"},{"fix":"Ensure you only use esbuild-mdx in a Node.js build script, not in client-side code.","message":"Because this is an esbuild plugin, it cannot be used in a browser environment directly; it's intended for build-time bundling.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use const mdxPlugin = (await import('esbuild-mdx')).default() in an ESM context.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use require() or dynamic import with .default.","message":"No ESM export is provided; attempting to import { default } from 'esbuild-mdx' will fail with a parse error.","severity":"breaking","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run: npm install @mdx-js/react@^1.6.22","cause":"@mdx-js/react is a peer dependency but not installed.","error":"Error: Plugin esbuild-mdx: Cannot find module '@mdx-js/react'"},{"fix":"Correct: require('esbuild-mdx')()","cause":"Forgetting to invoke the plugin creator function: require('esbuild-mdx') instead of require('esbuild-mdx')()","error":"TypeError: require(...) is not a function"},{"fix":"Run: npm install esbuild-mdx --save-dev","cause":"esbuild-mdx is not installed in node_modules.","error":"Error: Cannot find module 'esbuild-mdx'"},{"fix":"Ensure your esbuild entry points or resolve extensions include .md and .mdx, e.g., resolveExtensions: ['.js', '.md', '.mdx']","cause":"The plugin supports both .md and .mdx files, but esbuild may not resolve .md without proper configuration.","error":"Error: MDX components must be imported with .mdx extension, got .md"},{"fix":"Call require('esbuild-mdx')() with no arguments or an options object: require('esbuild-mdx')({})","cause":"Passing a non-object argument to the plugin creator (e.g., a string)","error":"Error: [plugin esbuild-mdx] Expected value of type 'object' for options"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}