Registry / web-framework / mdx-bundler

mdx-bundler

JSON →
library10.1.1jsnpmunverified

mdx-bundler is a high-performance library designed to compile and bundle MDX files along with their JavaScript/TypeScript dependencies, making it ideal for rendering dynamic content. The current stable version is 10.1.1. It maintains an active release cadence, with several minor and patch releases annually addressing bugs and introducing features, demonstrating ongoing development. A key differentiator is its use of esbuild, which enables extremely fast bundling, setting it apart from other MDX solutions. Unlike `next-mdx-remote`, `mdx-bundler` actively bundles file imports specified within MDX content, allowing for complex interactive components to be defined in separate files and imported directly. This capability makes it powerful for both build-time and on-demand, runtime content processing, offering scalability where each new MDX page does not necessarily increase build times.

npm install mdx-bundler
INSTALL
IMPORT
SIG · MDX-BUNDLER
M
mdx-bundler
web-frameworkjavascriptv10.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

bundleMDX
import { bundleMDX } from 'mdx-bundler'
const { bundleMDX } = require('mdx-bundler')
mdx-bundler is an ES Module. Use named import syntax. CommonJS `require` is not supported directly without ESM interoperability setup.
getMDXComponent
import { getMDXComponent } from 'mdx-bundler'
This utility function takes the bundled code string and returns a React component that can render the MDX content.
MDXRemoteSerializeResult
import type { MDXRemoteSerializeResult } from 'mdx-bundler'
This TypeScript type describes the shape of the object returned by `bundleMDX`, including the `code` and `frontmatter`.

This quickstart demonstrates how to bundle MDX content with local dependencies, extract frontmatter, and render the resulting MDX component using `mdx-bundler` with server-side React rendering.

import { bundleMDX, getMDXComponent } from 'mdx-bundler'; import * as React from 'react'; import { renderToString } from 'react-dom/server'; // Example MDX content with an import const mdxSource = ` --- title: My Awesome Post published: 2023-10-26 --- # Hello from MDX! import CustomComponent from './my-component'; This is some content. <CustomComponent text="World" /> Here's a list: - Item 1 - Item 2 `; // Example dependency file for the MDX const myComponentSource = ` import * as React from 'react'; export default function CustomComponent({ text }) { return <p>Hello, {text}!</p>; } `; async function processAndRenderMdx() { // Required for esbuild to find its binary in some environments, especially Windows if (process.platform === 'win32') { process.env.ESBUILD_BINARY_PATH = './node_modules/esbuild/esbuild.exe'; } else { process.env.ESBUILD_BINARY_PATH = './node_modules/esbuild/bin/esbuild'; } const { code, frontmatter } = await bundleMDX({ source: mdxSource, files: { './my-component.tsx': myComponentSource, }, // You can customize MDX options (remark/rehype plugins) here mdxOptions(options) { options.remarkPlugins = [...(options.remarkPlugins ?? [])]; options.rehypePlugins = [...(options.rehypePlugins ?? [])]; return options; }, }); // Dynamically import and execute the bundled code // This is typically done in a React component or server-side rendering setup const Component = getMDXComponent(code); // Example of server-side rendering using react-dom/server const html = renderToString( <Component components={{ // You can pass components here if they are not imported in MDX or for custom rendering // e.g., p: (props) => <p style={{ color: 'blue' }} {...props} /> }} /> ); console.log('Frontmatter:', frontmatter); console.log('Rendered HTML (first 200 chars):', html.substring(0, 200) + '...'); } processAndRenderMdx().catch(console.error);
Debug
Known issues
breakingmdx-bundler v10.0.0 and above requires Node.js version 18 or greater. Older Node.js versions are no longer supported.
fix
Upgrade your Node.js environment to version 18 or newer.
affects: >=10.0.0
breakingVersion 10.0.0 introduced significant upgrades to all unified and MDX-related dependencies. This may necessitate updating your remark and rehype plugins to their latest versions for compatibility.
fix
Review and update all custom remark and rehype plugins to ensure they are compatible with MDX v3 and the latest unified ecosystem versions.
affects: >=10.0.0
gotchaesbuild is a peer dependency and must be installed separately in your project. Failure to do so will result in runtime errors.
fix
Install esbuild as a direct dependency: `npm install esbuild` or `yarn add esbuild`.
affects: >=1.0.0
gotchaIn certain environments (e.g., Windows, specific CI setups), esbuild might not correctly locate its native binary. You may need to explicitly set the ESBUILD_BINARY_PATH environment variable.
fix
Before calling `bundleMDX`, set `process.env.ESBUILD_BINARY_PATH` to the absolute path of the esbuild executable (e.g., `./node_modules/esbuild/esbuild.exe` for Windows or `./node_modules/esbuild/bin/esbuild` for Unix-like systems).
affects: >=1.0.0
gotchamdx-bundler is an ES Module. While it handles dynamic ESM imports internally, applications consuming it should use ES Module `import` syntax. Using CommonJS `require()` directly can lead to errors.
fix
Ensure your consuming code uses `import { bundleMDX } from 'mdx-bundler';` and that your project is configured for ES Modules (e.g., `"type": "module"` in `package.json` or `.mjs` file extension).
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'esbuild'
The 'esbuild' package is a peer dependency and was not installed in your project.
fix
Install esbuild locally: `npm install esbuild` or `yarn add esbuild`.
ReferenceError: require is not defined in ES module scope
You are attempting to use CommonJS `require()` for `mdx-bundler`, but it is an ES Module.
fix
Convert your consuming file to an ES Module by using `import { bundleMDX } from 'mdx-bundler';` and ensure your `package.json` has `"type": "module"` or the file ends with `.mjs`.
Error: [esbuild] Failed to load NAPI module. This usually indicates that the 'esbuild' package was installed incorrectly.
esbuild's native binaries were not found or correctly linked for your environment.
fix
Explicitly set `process.env.ESBUILD_BINARY_PATH` to the correct path for your platform, e.g., `./node_modules/esbuild/esbuild.exe` for Windows or `./node_modules/esbuild/bin/esbuild` for Linux/macOS, before calling `bundleMDX`.
TypeError: options.mdxOptions is not a function
The `mdxOptions` parameter was passed an incorrect type, or there's a compatibility issue with MDX plugins.
fix
Ensure `mdxOptions` is a function with the signature `(options: MDXOptions) => MDXOptions` and that all remark/rehype plugins are compatible with MDX v3 and the unified dependencies used by mdx-bundler v10+.
Upgrade
Version history
10.1.1latest on npm
Audit
Dependencies
esbuildrequiredRequired for fast bundling of MDX and its dependencies. It's a peer dependency and must be installed separately.
Agent activity
10 hits · last 30 days
node
10
Resources
mdx-bundler — npm install mdx-bundler · libregistry