kentcdodds/mdx-bundler

The problem

You have a string of MDX and various TS/JS files that it uses and you want to get a bundled version of these files to eval in the browser.

This solution

This is an async function that will compile and bundle your MDX files and their dependencies. It uses MDX v3 and esbuild, so it's VERY fast and supports TypeScript files (for the dependencies of your MDX files).

Your source files could be local, in a remote github repo, in a CMS, or wherever else and it doesn't matter. All mdx-bundler cares about is that you pass it all the files and source code necessary and it will take care of bundling everything for you.

FAQ:

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

# Wahoo

import Demo from './demo'

Here's a **neat** demo:

<Demo />

Table of Contents

• Installation
• Usage
  • Options
  • Returns
  • Types
  • Component Substitution
  • Frontmatter and const
  • Accessing named exports
  • Image Bundling
  • Bundling a file.
  • Custom Components in Downstream Files
  • Known Issues
• Inspiration
• Other Solutions
• Issues
  • 🐛 Bugs
  • 💡 Feature Requests
• Contributors ✨
• LICENSE

Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's dependencies:

npm install --save mdx-bundler esbuild

One of mdx-bundler's dependencies requires a working node-gyp setup to be able to install correctly.

Usage

import {bundleMDX} from 'mdx-bundler'

const mdxSource = `
---
title: Example Post
published: 2021-02-13
description: This is some description
---

# Wahoo

import Demo from './demo'

Here's a **neat** demo:

<Demo />
`.trim()

const result = await bundleMDX({
  source: mdxSource,
  files: {
    './demo.tsx': `
import * as React from 'react'

function Demo() {
  return <div>Neat demo!</div>
}

export default Demo
    `,
  },
})

const {code, frontmatter} = result

From there, you send the code to your client, and then:

import * as React from 'react'
import {getMDXComponent} from 'mdx-bundler/client'

function Post({code, frontmatter}) {
  // it's generally a good idea to memoize this function call to
  // avoid re-creating the component every render.
  const Component = React.useMemo(() => getMDXComponent(code), [code])
  return (
    <>
      <header>
        <h1>{frontmatter.title}</h1>
        <p>{frontmatter.description}</p>
      </header>
      <main>
        <Component />
      </main>
    </>
  )
}

Ultimately, this gets rendered (basically):

<header>
  <h1>This is the title</h1>
  <p>This is some description</p>
</header>
<main>
  <div>
    <h1>Wahoo</h1>

    <p>Here's a <strong>neat</strong> demo:</p>

    <div>Neat demo!</div>
  </div>
</main>

Options

source

The string source of your MDX.

Can not be set if file is set

file

The path to the file on your disk with the MDX in. You will probably want to set cwd as well.

Can not be set if source is set

files

The files config is an object of all the files you're bundling. The key is the path to the file (relative to the MDX source) and the value is the string of the file source code. You could get these from the filesystem or from a remote database. If your MDX doesn't reference other files (or only imports things from node_modules), then you can omit this entirely.

mdxOptions

This allows you to modify the built-in MDX configuration (passed to @mdx-js/esbuild). This can be helpful for specifying your own remarkPlugins/rehypePlugins.

The function is passed the default mdxOptions and the frontmatter.

bundleMDX({
  source: mdxSource,
  mdxOptions(options, frontmatter) {
    // this is the recommended way to add custom remark/rehype plugins:
    // The syntax might look weird, but it protects you in case we add/remove
    // plugins in the future.
    options.remarkPlugins = [...(options.remarkPlugins ?? []), myRemarkPlugin]
    options.rehypePlugins = [...(options.rehypePlugins ?? []), myRehypePlugin]

    return options
  },
})

esbuildOptions

You can customize any of esbuild options with the option esbuildOptions. This takes a function which is passed the default esbuild options and the frontmatter and expects an options object to be returned.

bundleMDX({
  source: mdxSource,
  esbuildOptions(options, frontmatter) {
    options.minify = false
    options.target = [
      'es2020',
      'chrome58',
      'firefox57',
      'safari11',
      'edge16',
      'node12',
    ]

    return options
  },
})

More information on the available options can be found in the esbuild documentation.

It's recommended to use this feature to configure the target to your desired output, otherwise, esbuild defaults to esnext which is to say that it doesn't compile any standardized features so it's possible users of older browsers will experience errors.

globals

This tells esbuild that a given module is externally available. For example, if your MDX file uses the d3 library and you're already using the d3 library in your app then you'll end up shipping d3 to the user twice (once for your app and once for this MDX component). This is wasteful and you'd be better off just telling esbuild to not bundle d3 and you can pass it to the component yourself when you call getMDXComponent.

Global external configuration options: https://www.npmjs.com/package/@fal-works/esbuild-plugin-global-externals

Here's an example:

// server-side or build-time code that runs in Node:
import {bundleMDX} from 'mdx-bundler'

const mdxSource = `
# This is the title

import leftPad from 'left-pad'

<div>{leftPad("Neat demo!", 12, '!')}</div>
`.trim()

const result = await bundleMDX({
  source: mdxSource,
  // NOTE: this is *only* necessary if you want to share deps between your MDX
  // file bundle and the host app. Otherwise, all deps will just be bundled.
  // So it'll work either way, this is just an optimization to avoid sending
  // multiple copies of the same library to your users.
  globals: {'left-pad': 'myLeftPad'},
})

// server-rendered and/or client-side code that can run in the browser or Node:
import * as React from 'react'
import leftPad from 'left-pad'
import {getMDXComponent} from 'mdx-bundler/client'

function MDXPage({code}: {code: string}) {
  const Component = React.useMemo(
    () => getMDXComponent(result.code, {myLeftPad: leftPad}),
    [result.code, leftPad],
  )
  return (
    <main>
      <Component />
    </main>
  )
}

cwd

Setting cwd (current working directory) to a directory will allow esbuild to resolve imports. This directory could be the directory the mdx content was read from or a directory that off-disk mdx should be run in.

content/pages/demo.tsx

import * as React from 'react'

function Demo() {
  return <div>Neat demo!</div>
}

export default Demo

src/build.ts

import {bundleMDX} from 'mdx-bundler'

const mdxSource = `
---
title: Example Post
published: 2021-02-13
description: This is some description
---

# Wahoo

import Demo from './demo'

Here's a **neat** demo:

<Demo />
`.trim()

const result = await bundleMDX({
  source: mdxSource,
  cwd: '/users/you/site/_content/pages',
})

const {code, frontmatter} = result

grayMatterOptions

This allows you to configure the gray-matter options.

Your function is passed the current gray-matter configuration for you to modify. Return your modified configuration object for gray matter.

bundleMDX({
  grayMatterOptions: options => {
    options.excerpt = true

    return options
  },
})

bundleDirectory & bundlePath

This allows you to set the output directory for the bundle and the public URL to the directory. If one option is set the other must be as well.

The Javascript bundle is not written to this directory and is still returned as a string from bundleMDX.

This feature is best used with tweaks to mdxOptions and esbuildOptions. In the example below .png files are written to the disk and then served from /file/.

This allows you to store assets with your MDX and then have esbuild process them like anything else.

It is recommended that each bundle has its own bundleDirectory so that multiple bundles don't overwrite each others assets.

const {code} = await bundleMDX({
  file: '/path/to/site/content/file.mdx',
  cwd: '/path/to/site/content',
  bundleDirectory: '/path/to/site/public/file',
  bundlePath: '/file/',
  mdxOptions: options => {
    options.remarkPlugins = [remarkMdxImages]

    return options
  },
  esbuildOptions: options => {
    options.loader = {
      ...options.loader,
      '.png': 'file',
    }

    return options
  },
})

Returns

bundleMDX returns a promise for an object with the following properties.

• code - The bundle of your mdx as a string.
• frontmatter - The frontmatter object from gray-matter.
• matter - The whole object returned by gray-matter

Types

mdx-bundler supplies complete typings within its own package.

bundleMDX has a single type parameter which is the type of your frontmatter. It defaults to {[key: string]: any} and must be an object. This is then used to type the returned frontmatter and the frontmatter passed to esbuildOptions and mdxOptions.

const {frontmatter} = bundleMDX<{title: string}>({source})

frontmatter.title // has type string

Component Substitution

MDX Bundler passes on MDX's ability to substitute components through the components prop on the component returned by getMDXComponent.

Here's an example that removes p tags from around images.

import * as React from 'react'
import {getMDXComponent} from 'mdx-bundler/client'

const Paragraph: React.FC = props => {
  if (typeof props.children !== 'string' && props.children.type === 'img') {
    return <>{props.children}</>
  }

  return <p {...props} />
}

function MDXPage({code}: {code: string}) {
  const Component = React.useMemo(() => getMDXComponent(code), [code])

  return (
    <main>
      <Component components={{p: Paragraph}} />
    </main>
  )
}

Frontmatter and const

You can reference frontmatter meta or consts in the mdx content.

---
title: Example Post
---

export const exampleImage = 'https://example.com/image.jpg'

# {frontmatter.title}

<img src={exampleImage} alt="Image alt text" />

Accessing named exports

You can use getMDXExport instead of getMDXComponent to treat the mdx file as a module instead of just a component. It takes the same arguments that getMDXComponent does.

---
title: Example Post
---

export const toc = [{depth: 1, value: 'The title'}]

# The title

import * as React from 'react'
import {getMDXExport} from 'mdx-bundler/client'

function MDXPage({code}: {code: string}) {
  const mdxExport = getMDXExport(code)
  console.log(mdxExport.toc) // [ { depth: 1, value: 'The title' } ]

  const Component = React.useMemo(() => mdxExport.default, [code])

  return <Component />
}

Image Bundling

With the cwd and the remark plugin remark-mdx-images you can bundle images in your mdx!

There are two loaders in esbuild that can be used here. The easiest is dataurl which outputs the images as inline data urls in the returned code.

import {remarkMdxImages} from 'remark-mdx-images'

const {code} = await bundleMDX({
  source: mdxSource,
  cwd: '/users/you/site/_content/pages',
  mdxOptions: options => {
    options.remarkPlugins = [...(options.remarkPlugins ?? []), remarkMdxImages]

    return options
  },
  esbuildOptions: options => {
    options.loader = {
      ...options.loader,
      '.png': 'dataurl',
    }

    return options
  },
})

The file loader requires a little more configuration to get working. With the file loader your images are copied to the output directory so esbuild needs to be set to write files and needs to know where to put them plus the url of the folder to be used in image sources.

Each call to bundleMDX is isolated from the others. If you set the directory the same for everything bundleMDX will overwrite images without warning. As a result each bundle needs its own output directory.

// For the file `_content/pages/about.mdx`

const {code} = await bundleMDX({
  source: mdxSource,
  cwd: '/users/you/site/_content/pages',
  mdxOptions: options => {
    options.remarkPlugins = [...(options.remarkPlugins ?? []), remarkMdxImages]

    return options
  },
  esbuildOptions: options => {
    // Set the `outdir` to a public location for this bundle.
    options.outdir = '/users/you/site/public/img/about'
    options.loader = {
      ...options.loader,
      // Tell esbuild to use the `file` loader for pngs
      '.png': 'file',
    }
    // Set the public path to /img/about
    options.publicPath = '/img/about'

    // Set write to true so that esbuild will output the files.
    options.write = true

    return options
  },
})

Bundling a file.

If your MDX file is on your disk you can save some time and code by having mdx-bundler read the file for you. Instead of supplying a source string you can set file to the path of the MDX on disk. Set cwd to its folder so that relative imports work.

import {bundleMDX} from 'mdx-bundler'

const {code, frontmatter} = await bundleMDX({
  file: '/users/you/site/content/file.mdx',
  cwd: '/users/you/site/content/',
})

Custom Components in Downstream Files

To make sure custom components are accessible in downstream MDX files, you can use the MDXProvider from @mdx-js/react to pass custom components to your nested imports.

npm install --save @mdx-js/react

const globals = {
  '@mdx-js/react': {
    varName: 'MdxJsReact',
    namedExports: ['useMDXComponents'],
    defaultExport: false,
  },
};
const { code } = bundleMDX({
  source,
  globals,
  mdxOptions(options: Record<string, any>) {
      return {
        ...options,
        providerImportSource: '@mdx-js/react',
      };
  }
});

From there, you send the code to your client, and then:

import { MDXProvider, useMDXComponents } from '@mdx-js/react';
const MDX_GLOBAL_CONFIG = {
  MdxJsReact: {
    useMDXComponents,
  },
};
export const MDXComponent: React.FC<{
  code: string;
  frontmatter: Record<string, any>;
}> = ({ code }) => {
  const Component = useMemo(
    () => getMDXComponent(code, MDX_GLOBAL_CONFIG),
    [code],
  );

  return (
    <MDXProvider components={{ Text: ({ children }) => <p>{children}</p> }}>
      <Component />
    </MDXProvider>
  );
};

Known Issues

Other JSX runtimes

JSX runtimes mentioned here are guaranteed to be supported, however any JSX runtime should work without problem, as long as they export their own jsx runtime. For example, hono is not mentioned here, but as it has react compatible API, it can be used without any issues.

To do so, you will have to pass a configuration object and use JSX Component factory.

const getMDX = (source) => {
  return bundleMDX({
    source,
    jsxConfig: {
      jsxLib: {
        varName: 'HonoJSX',
        package: 'hono/jsx',
      },
      jsxDom: {
        varName: 'HonoDOM',
        package: 'hono/jsx/dom',
      },
      jsxRuntime: {
        varName: '_jsx_runtime',
        package: 'hono/jsx/jsx-runtime',
      },
    }
  });
}

// ...

import { getMDXComponent } from "mdx-bundler/client/jsx";

import * as HonoJSX from "hono/jsx";
import * as HonoDOM from "hono/jsx/dom";
import * as _jsx_runtime from "hono/jsx/jsx-runtime";
const jsxConfig = {
  HonoJSX,
  HonoDOM,
  _jsx_runtime
};

export const MDXComponent: React.FC<{
  code: string;
}> = ({ code }) => {
  const Component = useMemo(
    () => getMDXComponent(code, jsxConfig),
    [code],
  );

  return (
    <Component components={{ Text: ({ children }) => <p>{children}</p> }} />
  );
};

To use it with others, adjust jsxConfig passed to bundler.

const jsxConfig = {
  jsxLib: {
    varName: 'HonoJSX',
    package: 'hono/jsx',
  },
  jsxDom: {
    varName: 'HonoDOM',
    package: 'hono/jsx/dom',
  },
  jsxRuntime: {
    varName: '_jsx_runtime',
    package: 'hono/jsx/jsx-runtime',
  },
}

and to getMDXComponent

const jsxConfig = { HonoJSX, HonoDOM, _jsx_runtime };

Cloudflare Workers

We'd love for this to work in cloudflare workers. Unfortunately cloudflare workers have two limitations that prevent mdx-bundler from working in that environment:

1. Workers can't run binaries. bundleMDX uses esbuild (a binary) to bundle your MDX code.
2. Workers can't run eval or similar. getMDXComponent evaluates the bundled code using new Function.

One workaround to this is to put your mdx-bundler related code in a different environment and call that environment from within the Cloudflare worker. IMO, this defeats the purpose of using Cloudflare workers. Another potential workaround is to use WASM from within the worker. There is esbuild-wasm but there are some issues with that package explained at that link. Then there's wasm-jseval, but I couldn't get that to run code that was output from mdx-bundler without error.

If someone would like to dig into this, that would be stellar, but unfortunately it's unlikely I'll ever work on it.

Next.JS esbuild ENOENT

esbuild relies on __dirname to work out where is executable is, Next.JS and Webpack can sometimes break this and esbuild needs to be told manually where to look.

Adding the following code before your bundleMDX will point esbuild directly at the correct executable for your platform.

import path from 'path'

if (process.platform === 'win32') {
  process.env.ESBUILD_BINARY_PATH = path.join(
    process.cwd(),
    'node_modules',
    'esbuild',
    'esbuild.exe',
  )
} else {
  process.env.ESBUILD_BINARY_PATH = path.join(
    process.cwd(),
    'node_modules',
    'esbuild',
    'bin',
    'esbuild',
  )
}

More information on this issue can be found in this article.

Inspiration

As I was rewriting kentcdodds.com to remix, I decided I wanted to keep my blog posts as MDX, but I didn't want to have to compile them all at build time or be required to redeploy every time I fix a typo. So I made this which allows my server to compile on demand.

Other Solutions

There's next-mdx-remote but it's more of an mdx-compiler than a bundler (can't bundle your mdx for dependencies). Also it's focused on Next.js whereas this is meta-framework agnostic.

Issues

Looking to contribute? Look for the Good First Issue label.

🐛 Bugs

Please file an issue for bugs, missing documentation, or unexpected behavior.

See Bugs

💡 Feature Requests

Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on.

See Feature Requests

Contributors ✨

Thanks goes to these people (emoji key):

Kent C. Dodds 💻 📖 🚇 ⚠️	benwis 🐛 👀	Adam Laycock 💻 ⚠️ 🤔 👀 📖	Titus 🤔 👀 💻	Christian Murphy 🤔	Pedro Duarte 📖	Erik Rasmussen 📖
Omar Syx 🐛	Gaël Haméon 📖	Gabriel Loiácono 💻 ⚠️	Spencer Miskoviak 📖	Casper 💻	Apostolos Christodoulou 📖	Yordis Prieto 💻
xoumi 💻	Yasin 💻	Mohammed 'Mo' Mulazada 📖	Can Rau 📖	Hosenur Rahaman 📖	Maciek Sitkowski 📖	Priyang 💻 📖
Mosaad 📖	stefanprobst 💻 ⚠️	Vlad Moroz 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

LICENSE

MIT