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

Give your MDX and JS strings to this function, and it will give you back a single string of the bundled code.

Table of Contents

• Installation
• Usage
• Compilation target
• Rollup options
• 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

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(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 {MDXProvider} from '@mdx-js/react'
import {getMDXComponent} from 'mdx-bundler/client'

function Post({code, frontmatter}) {
  const Component = getMDXComponent(code)
  return (
    <MDXProvider>
      <header>
        <h1>{frontmatter.title}</h1>
        <p>{frontmatter.description}</p>
      </header>
      <main>
        <Component />
      </main>
    </MDXProvider>
  )
}

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>

Compilation target

We use rollup to bundle your MDX and its dependencies and babel to compile things. We're using @babel/preset-env and you can configure this using the standard browserlist configuration. learn more.

Rollup options

You can customize the rollup configuration used with the rollup options:

const result = await bundleMDX(mdxSource, {
  files: {
    /* ... */
  },
  rollup: {
    getInputOptions,
    getOutputOptions,
  },
})

Each of these is a function that receives the default options and should return the options you want used.

This should allow you to customize the external and global configuration for rollup. For example, if your MDX file uses the d3 library and your app exposes window.d3 you could configure rollup to externalize that and replace all references with the global d3 to avoid double-bundling d3. When you call getMDXComponent, you'll pass d3 as a second argument: getMDXComponent(code, {d3: window.d3})

Check the tests for an example.

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 💻 📖 🚇 ⚠️

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

LICENSE

MIT