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.
Give your MDX and JS strings to this function, and it will give you back a single string of the bundled code.
- Installation
- Usage
- Compilation target
- Rollup options
- Inspiration
- Other Solutions
- Issues
- Contributors β¨
- LICENSE
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
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}) {
// 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 (
<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>
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.
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.
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})
. 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(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.
rollup: {
getInputOptions(options) {
// Tell rollup that `left-pad` should *not* be bundled.
// By default `options.external` is: ['react', 'react-dom']
// so we'll add 'left-pad' to tell rollup to not bundle it with our MDX code
options.external = [...(options.external as Array<string>), 'left-pad']
return options
},
getOutputOptions(options) {
// Tell rollup that it should replace the left-pad import with a global variable.
// By default `options.globals` is: {react: 'React', 'react-dom': 'ReactDOM'}
// so we'll add 'left-pad': 'myLeftPad' to tell it what the global variable name is
options.globals = {...options.globals, 'left-pad': 'myLeftPad'}
return options
},
},
})
// 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 {MDXProvider} from '@mdx-js/react'
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>
<MDXProvider>
<Component />
</MDXProvider>
</main>
)
}
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.
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.
Looking to contribute? Look for the Good First Issue label.
Please file an issue for bugs, missing documentation, or unexpected behavior.
Please file an issue to suggest new features. Vote on feature requests by adding a π. This helps maintainers prioritize what to work on.
Thanks goes to these people (emoji key):
Kent C. Dodds π» π π |
benwis π |
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT