{"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,"search_vec":"'/loader':72 '/react':87 '0.2.0':33 '2021':35 '3':41 'altern':67 'app':28 'base':64 'bundler':66 'cadenc':40 'compar':60 'compon':20 'content':25 'current':29 'depend':78 'differenti':44 'direct':46 'dom':82 'driven':24 'enabl':21 'esbuild':2,5,11,48,75 'esbuild-mdx':1,4 'file':17 'integr':45 'javascript':88 'js':71,86 'key':43 'lightweight':59 'low':38 'markdown':23 'markdown-driven':22 'md':14 'mdx':3,6,16,56,65,70,85 'mdx-js':69,84 'minimum':76 'option':53 'pass':54 'peer':77 'plugin':9,50 'react':19,27,79,81 'react-dom':80 'releas':34,39,42 'resolv':13 'stabl':30 'support':52 'system':51 'version':31 'webpack':63 'webpack-bas':62","created_at":"2026-05-01T13:44:02.631282+00:00","updated_at":"2026-05-01T13:44:02.631282+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zaydek/esbuild-mdx","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/esbuild-mdx","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}