mdx-bundler: Runtime MDX Compilation and Dependency Bundling

mdx-bundler Targets In-Memory MDX With Imported Components

mdx-bundler addresses a specific gap between ordinary MDX compilation and full application bundling. The README describes a situation where an application holds an MDX string plus the TypeScript or JavaScript files used by that content, but still needs one browser-renderable component. The library accepts that in-memory file set and produces the compiled and bundled result needed by the renderer.

This is aimed at applications whose content is not necessarily confined to the local project filesystem. The README names local files, remote GitHub repositories, and CMS content as possible sources. The application remains responsible for retrieving files and passing their source code to mdx-bundler. That separation makes the library relevant to route-driven rendering systems, although the caller still has to implement retrieval and decide when compilation should occur.

MDX itself combines Markdown-style content with JSX components. That matters because content can remain readable while also referring to interactive components imported from another file. A conventional Markdown-to-HTML compiler is insufficient for that case, while a compiler that leaves unresolved imports unresolved moves a bundling problem to the caller. mdx-bundler takes responsibility for both stages.

MDX v3 and esbuild Form the mdx-bundler Pipeline

The project documentation identifies MDX v3 and esbuild as the two central technologies. MDX compilation processes the content syntax, frontmatter constructs, and embedded JSX. Bundling then resolves and incorporates dependencies referenced by that content. The resulting code is represented as a component that can be rendered in the browser, according to the project description.

The README gives this MDX sample as an example that requires dependency bundling:

---
title: Example Post
published: 2021-02-13
description: This is some description
---

# Wahoo

import Demo from './demo'

Here's a **neat** demo:

<Demo />

The important line is `import Demo from './demo'`. The surrounding post references a separate module, so compilation alone does not finish the job. mdx-bundler is designed to bundle that dependency into the output used by the renderer. The README contrasts this with `next-mdx-remote`, which it describes as a compiler rather than a bundler and says cannot handle this example.

This distinction also explains the library's place in frameworks. The README says it can be used with Remix, Gatsby, Next, and CRA, but its implementation should account for whether the surrounding framework supports server-side rendering. Gatsby and CRA may fit build-time integration. Remix and Next are presented as better fits for on-demand compilation because they can process content as requests arrive.

Installing mdx-bundler Through npm on Node.js 18

The README identifies npm as the distribution channel and associates it with Node.js. Its installation section is truncated before the complete consumer setup instructions, so there is no confirmed package-manager command to reproduce. The `package.json` file nevertheless establishes three concrete setup constraints.

First, the published package is named `mdx-bundler`, and its metadata declares `node` `>=18` and `npm` `>=6`. Second, the package is an ES module because `package.json` contains `"type": "module"`. Third, esbuild is not a direct dependency. It appears under `peerDependencies` as `esbuild: "0.*"`, so the consuming application must provide a compatible esbuild release.

The peer dependency is not incidental. The README explains that esbuild runs a service written in Go, that only one instance of that service can run at a time, and that its version must match the npm package used with mdx-bundler. Treating esbuild as a peer dependency leaves the final version choice with the host application rather than silently installing an incompatible copy.

For repository maintenance, `package.json` exposes `npm run build`, `npm run lint`, `npm test`, and `npm run typecheck`. These are contributor scripts, not consumer installation instructions. The distributed package includes `dist` and `client`, while the package entry points to `dist/index.js` and exposes declarations through `dist/index.d.ts`.

A First Runtime Request Starts With Caller-Supplied Files

A concrete first use begins with content already in memory. The MDX example above contains frontmatter, a Markdown heading, formatted text, an imported `Demo` component, and a JSX invocation. In a runtime design, an application route would retrieve that string and the source of `./demo`, then hand the necessary files to mdx-bundler. The README documents this ownership boundary, although its truncated usage section does not provide a confirmed function signature or invocation example.

That missing example matters. An engineer cannot safely infer the exact options object, return fields, file map shape, or client evaluation procedure from the visible README excerpt alone. The project documents several feature areas, including frontmatter and constants, named exports, component substitution, image bundling, downstream custom components, and other JSX runtimes, but their complete option names and handling are not shown.

For a first integration, the documented content shape is more useful than an invented call. The request handler should verify that the imported source is available. It should preserve relative import paths as expected by the bundler, provide any referenced files, and use a JSX runtime supported by MDX. The README says any runtime listed in MDX's getting-started documentation is guaranteed to work. It also identifies libraries with React-compatible APIs as possible choices.

The application can compile on demand or during a build. Those are different operating models. Request-time compilation suits content that changes independently of the deployed application. Build-time compilation produces assets through a conventional deployment and may be simpler for a static Gatsby or CRA site.

Runtime Caching Matters When mdx-bundler Runs Per Request

The README recommends cache headers when on-demand bundling is used. This matters in the project's architecture because repeated compilation moves the same work onto the server request path. Caching the compiled output can avoid unnecessary rebundling, according to the documentation.

The library also presents request-time processing as a way to avoid rebuilding and redeploying an entire site after a typo in one MDX page. In that model, adding content does not automatically become another page in the application's build graph. The route handles the current content instead. This is the practical advantage over build-time-oriented webpack or Rollup MDX plugins when the content collection changes frequently.

That model has boundaries. It does not remove the need to retrieve files, determine dependencies, compile code, or deliver the resulting component. It also does not let mdx-bundler discover a CMS record by itself. The README assigns retrieval to the caller. A production route still needs decisions about cache invalidation, response format, and the relationship between edited source files and previously generated output. The README mentions cache headers but does not document cache-key design or invalidation.

Run-time processing can also move work onto the serving path. The documentation says the package is fast, but it publishes no benchmark or service-level guarantee in the README. Capacity planning must therefore be based on the host application's request pattern rather than an unstated performance target.

Version Alignment Defines mdx-bundler Upgrade Work

The repository is not archived, and its last push was on 2026-05-13. The latest listed release is `v10.1.1`, dated 2025-03-05, following `v10.1.0` on 2025-02-07 and `v10.0.3` on 2024-08-16. This shows repository changes after the latest published release, but the README does not explain whether those changes are included in a new package.

The main technical constraint during upgrades is the relationship between mdx-bundler, MDX, and esbuild. The package metadata depends on `@mdx-js/esbuild` `^3.0.0`, consistent with the README's MDX v3 description. Its peer range is `esbuild: "0.*"`, while the README explains that the esbuild service and npm package need identical versions. An upgrade review should therefore inspect the installed esbuild version rather than treating mdx-bundler as independent of that external compatibility constraint.

The package uses `gray-matter`, `remark-frontmatter`, and `remark-mdx-frontmatter` for MDX-related processing. Its plugin list also includes external handling and node resolution. Changes in these dependencies may affect imports, globals, frontmatter, or module resolution even if the public call to mdx-bundler remains unchanged.

The repository publishes only `dist` and `client` in the npm package. Consumers receive built output and a client directory rather than the repository's `src` tree. Upgrade checks should cover both the server-side call and the browser-side evaluation path if the client output is used. The project uses the MIT license, and its `package.json` records that identifier for the distributed package.

Webpack, Rollup, and Compiler-Only Tools Solve Different Problems

The most direct alternative described by the README is the use of MDX plugins for webpack or Rollup. Those tools are intended to run at build time, after which the application deploys the built files. Every MDX page enters that build, so a content change requires another build and deployment. They fit situations where MDX is versioned with the application and assets are produced before deployment.

mdx-bundler can also run at build time, but its distinct use is compiling content after retrieval. It does not require the source files to be present in the local filesystem. The caller can load them from a CMS or another repository into memory first. This makes it relevant when application code and editorial content have separate release cycles.

`next-mdx-remote` provides another useful comparison. The README describes it as an MDX compiler, while mdx-bundler is both compiler and bundler. The sample importing `Demo` from `./demo` is the dividing case: the README says the compiler-only tool cannot handle it, while mdx-bundler is intended to bundle that dependency.

The choice is operational. Use webpack or Rollup when prebuilding deployable assets is the established application model. Use mdx-bundler when content must be compiled on demand and its imports included. Use a compiler-only integration when dependency bundling is unnecessary or handled elsewhere.

Editorial conclusion

Application developers should consider mdx-bundler when MDX comes from a CMS, repository, or request handler and must retain its component imports. Static-site builders should first compare its runtime compilation model with a conventional webpack or Rollup build. Before adoption, verify the published API for the intended MDX v3 version, confirm that the application supplies esbuild at a compatible version, and test rendering with the JSX runtime and component substitution rules used by the project.

Frequently asked questions

Official sources

1. Issues
2. kentcdodds/mdx-bundler on GitHub
3. License: MIT
4. README
5. Releases