vue-mdx-bundler

Compile and bundle your MDX files and their dependencies. FAST.

---

WIP we'll update this readme

this is a fork of react version of mdx-bundler by kentcdodds.com thanks Kent 🙏

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 esbuild, so it's VERY fast and supports TypeScript files (for the dependencies of your MDX files). It also uses xdm which is a more modern and powerful MDX compiler with fewer bugs and more features (and no extra runtime requirements).

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:

"What's so cool about MDX?"

MDX enables you to combine terse markdown syntax for your content with the power of React components. For content-heavy sites, writing the content with straight-up HTML can be annoyingly verbose. Often people solve this using a WSYWIG editor, but too often those fall short in mapping the writer's intent to HTML. Many people prefer using markdown to express their content source and have that parsed into HTML to be rendered.

The problem with using Markdown for your content is if you want to have some interactivity embedded into your content, you're pretty limited. You either need to insert an element that JavaScript targets (which is annoyingly indirect), or you can use an iframe or something.

As previously stated, MDX enables you to combine terse markdown syntax for your content with the power of React components. So you can import a React component and render it within the markdown itself. It's the best of both worlds.

"How is this different from next-mdx-remote?"

mdx-bundler actually bundles dependencies of your MDX files. For example, this won't work with next-mdx-remote, but it will with mdx-bundler:

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

# Wahoo

import Demo from './demo'

Here's a **neat** demo:

<Demo />

next-mdx-remote chokes on that import because it's not a bundler, it's just a compiler. mdx-bundler is an MDX compiler and bundler. That's the difference.

"How is this different from the mdx plugins for webpack or rollup?"

Those tools are intended to be run "at build time" and then you deploy the built version of your files. This means if you have some content in MDX and want to make a typo change, you have to rebuild and redeploy the whole site. This also means that every MDX page you add to your site will increase your build-times, so it doesn't scale all that well.

mdx-bundler can definitely be used at build-time, but it's more powerfully used as a runtime bundler. A common use case is to have a route for your MDX content and when that request comes in, you load the MDX content and hand that off to mdx-bundler for bundling. This means that mdx-bundler is infinitely scalable. Your build won't be any longer regardless of how much MDX content you have. Also, mdx-bundler is quite fast, but to make this on-demand bundling even faster, you can use appropriate cache headers to avoid unnecessary re-bundling.

Webpack/rollup/etc also require that all your MDX files are on the local filesystem to work. If you want to store your MDX content in a separate repo or CMS, you're kinda out of luck or have to do some build-time gymnastics to get the files in place for the build.

With mdx-bundler, it doesn't matter where your MDX content comes from, you can bundle files from anywhere, you're just responsible for getting the content into memory and then you hand that off to mdx-bundler for bundling.

"Does this work with Nuxt/Vite/Gridsome/VueCLI/etc?"

Totally. It works with any of those tools. Depending on whether your meta-framework supports server-side rendering, you'll implement it differently. You might decide to go with a built-time approach (for Vite/Gridsome/VueCLI), but as mentioned, the true power of mdx-bundler comes in the form of on-demand bundling. So it's best suited for SSR frameworks like Nuxt/Vite.

"Why does this use XDM instead of @mdx-js?"

It has more features, fewer bugs, and no runtime!

Docs

• vue-mdx-bundler docs

Plugins

• vite-plugin-mdx-vue docs

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

LICENSE

MIT