Compile and bundle your MDX files and their dependencies. FAST.
\n
\n\n---\n\n\n[![Build Status][build-badge]][build]\n[![Code Coverage][coverage-badge]][coverage]\n[![version][version-badge]][package]\n[![downloads][downloads-badge]][npmtrends]\n[![MIT License][license-badge]][license]\n[![PRs Welcome][prs-badge]][prs]\n[![Code of Conduct][coc-badge]][coc]\n\n\n> *WIP* we'll update this readme\n> \n> this is a fork of react version of [mdx-bundler](https://github.com/kentcdodds/mdx-bundler) by [kentcdodds.com](https://kentcdodds.com) thanks Kent ð\n## The problem\n\nYou have a string of MDX and various TS/JS files that it uses and you want to\nget a bundled version of these files to eval in the browser.\n\n## This solution\n\nThis is an async function that will compile and bundle your MDX files and their\ndependencies. It uses [esbuild](https://esbuild.github.io/), so it's VERY fast\nand supports TypeScript files (for the dependencies of your MDX files). It also\nuses [xdm](https://github.com/wooorm/xdm) which is a more modern and powerful\nMDX compiler with fewer bugs and more features (and no extra runtime\nrequirements).\n\nYour source files could be local, in a remote github repo, in a CMS, or wherever\nelse and it doesn't matter. All `mdx-bundler` cares about is that you pass it\nall the files and source code necessary and it will take care of bundling\neverything for you.\n\n### FAQ:\n\n\n \n \n \"What's so cool about MDX?\"\n \n \n\n[MDX](https://mdxjs.com/) enables you to combine terse markdown syntax for your\ncontent with the power of React components. For content-heavy sites, writing the\ncontent with straight-up HTML can be annoyingly verbose. Often people solve this\nusing a WSYWIG editor, but too often those fall short in mapping the writer's\nintent to HTML. Many people prefer using markdown to express their content\nsource and have that parsed into HTML to be rendered.\n\nThe problem with using Markdown for your content is if you want to have some\ninteractivity embedded into your content, you're pretty limited. You either need\nto insert an element that JavaScript targets (which is annoyingly indirect), or\nyou can use an `iframe` or something.\n\nAs previously stated, [MDX](https://mdxjs.com/) enables you to combine terse\nmarkdown syntax for your content with the power of React components. So you can\nimport a React component and render it within the markdown itself. It's the best\nof both worlds.\n\n\n\n\n \n \n \"How is this different from next-mdx-remote?\"\n \n \n\n`mdx-bundler` actually bundles dependencies of your MDX files. For example, this\nwon't work with `next-mdx-remote`, but it will with `mdx-bundler`:\n\n```md\n---\ntitle: Example Post\npublished: 2021-02-13\ndescription: This is some description\n---\n\n# Wahoo\n\nimport Demo from './demo'\n\nHere's a **neat** demo:\n\n\n```\n\n`next-mdx-remote` chokes on that import because it's not a bundler, it's just a\ncompiler. `mdx-bundler` is an MDX compiler and bundler. That's the difference.\n\n\n\n\n \n \n \"How is this different from the mdx plugins for webpack or rollup?\"\n \n \n\nThose tools are intended to be run \"at build time\" and then you deploy the built\nversion of your files. This means if you have some content in MDX and want to\nmake a typo change, you have to rebuild and redeploy the whole site. This also\nmeans that every MDX page you add to your site will increase your build-times,\nso it doesn't scale all that well.\n\n`mdx-bundler` can definitely be used at build-time, but it's more powerfully\nused as a runtime bundler. A common use case is to have a route for your MDX\ncontent and when that request comes in, you load the MDX content and hand that\noff to `mdx-bundler` for bundling. This means that `mdx-bundler` is infinitely\nscalable. Your build won't be any longer regardless of how much MDX content you\nhave. Also, `mdx-bundler` is quite fast, but to make this on-demand bundling\neven faster, you can use appropriate cache headers to avoid unnecessary\nre-bundling.\n\nWebpack/rollup/etc also require that all your MDX files are on the local\nfilesystem to work. If you want to store your MDX content in a separate repo or\nCMS, you're kinda out of luck or have to do some build-time gymnastics to get\nthe files in place for the build.\n\nWith `mdx-bundler`, it doesn't matter where your MDX content comes from, you can\nbundle files from anywhere, you're just responsible for getting the content into\nmemory and then you hand that off to `mdx-bundler` for bundling.\n\n\n\n\n \n \n \"Does this work with Nuxt/Vite/Gridsome/VueCli/etc?\"\n \n \n\nTotally. It works with any of those tools. Depending on whether your\nmeta-framework supports server-side rendering, you'll implement it differently.\nYou might decide to go with a built-time approach (for Gatsby/CRA), but as\nmentioned, the true power of `mdx-bundler` comes in the form of on-demand\nbundling. So it's best suited for SSR frameworks like Remix/Next.\n\n\n\n\n \n \n \"Why the dodo bird emoji? ðĶĪ\"\n \n \n\nWhy not?\n\n\n\n\n \n \n \"Why does this use XDM instead of @mdx-js?\"\n \n \n\nIt has more features, fewer bugs, and no runtime!\n\n\n\n## Table of Contents\n\n\n\n\n- [The problem](#the-problem)\n- [This solution](#this-solution)\n - [FAQ:](#faq)\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n- [Usage](#usage)\n - [Options](#options)\n - [files](#files)\n - [xdmOptions](#xdmoptions)\n - [esbuildOptions](#esbuildoptions)\n - [globals](#globals)\n - [Component Substitution](#component-substitution)\n- [Issues](#issues)\n - [ð Bugs](#-bugs)\n - [ðĄ Feature Requests](#-feature-requests)\n- [LICENSE](#license)\n\n\n\n## Installation\n\nThis module is distributed via [npm][npm] which is bundled with [node][node] and\nshould be installed as one of your project's `dependencies`:\n\n```\nyarn add vue-mdx-bundler\n```\n\n```\nnpm install --save vue-mdx-bundler\n```\n\n## Usage\n\n```typescript\nimport {bundleMDX} from 'mdx-bundler'\n\nconst mdxSource = `\n---\ntitle: Example Post\npublished: 2021-02-13\ndescription: This is some description\n---\n\n# Wahoo\n\nimport Demo from './demo'\n\nHere's a **neat** demo:\n\n\n`.trim()\n\nconst result = await bundleMDX(mdxSource, {\n files: {\n './demo.tsx': `\nimport * as React from 'react'\n\nfunction Demo() {\n return
Neat demo!
\n}\n\nexport default Demo\n `,\n },\n})\n\nconst {code, frontmatter} = result\n```\n\nFrom there, you send the `code` to your client, and then:\n\n```jsx\ntodo\n```\n\nUltimately, this gets rendered (basically):\n\n```html\n\n
This is the title
\n
This is some description
\n\n\n
\n
Wahoo
\n\n
Here's a neat demo:
\n\n
Neat demo!
\n
\n\n```\n\n### Options\n\n#### files\n\nThe `files` config is an object of all the files you're bundling. The key is the\npath to the file (relative to the MDX source) and the value is the string of the\nfile source code. You could get these from the filesystem or from a remote\ndatabase. If your MDX doesn't reference other files (or only imports things from\n`node_modules`), then you can omit this entirely.\n\n#### xdmOptions\n\nThis allows you to modify the built-in xdm configuration (passed to\nxdm.compile). This can be helpful for specifying your own\nremarkPlugins/rehypePlugins.\n\n```ts\nbundleMDX(mdxString, {\n xdmOptions(input, options) {\n // this is the recommended way to add custom remark/rehype plugins:\n // The syntax might look weird, but it protects you in case we add/remove\n // plugins in the future.\n options.remarkPlugins = [...(options.remarkPlugins ?? []), myRemarkPlugin]\n options.rehypePlugins = [...(options.rehypePlugins ?? []), myRehypePlugin]\n\n return options\n },\n})\n```\n\n#### esbuildOptions\n\nYou can customize any of esbuild options with the option `esbuildOptions`. This\ntakes a function which is passed the default esbuild options and expects an\noptions object to be returned.\n\n```typescript\nbundleMDX(mdxSource, {\n esbuildOptions(options) {\n options.minify = false\n options.target = [\n 'es2020',\n 'chrome58',\n 'firefox57',\n 'safari11',\n 'edge16',\n 'node12',\n ]\n\n return options\n },\n})\n```\n\nMore information on the available options can be found in the\n[esbuild documentation](https://esbuild.github.io/api/#build-api).\n\nIt's recommended to use this feature to configure the `target` to your desired\noutput, otherwise, esbuild defaults to `esnext` which is to say that it doesn't\ncompile any standardized features so it's possible users of older browsers will\nexperience errors.\n\n#### globals\n\nThis tells esbuild that a given module is externally available. For example, if\nyour MDX file uses the d3 library and you're already using the d3 library in\nyour app then you'll end up shipping `d3` to the user twice (once for your app\nand once for this MDX component). This is wasteful and you'd be better off just\ntelling esbuild to _not_ bundle `d3` and you can pass it to the component\nyourself when you call `getMDXComponent`.\n\nHere's an example:\n\n```tsx\n// server-side or build-time code that runs in Node:\nimport {bundleMDX} from 'mdx-bundler'\n\nconst mdxSource = `\n# This is the title\n\nimport leftPad from 'left-pad'\n\n
{leftPad(\"Neat demo!\", 12, '!')}
\n`.trim()\n\nconst result = await bundleMDX(mdxSource, {\n // NOTE: this is *only* necessary if you want to share deps between your MDX\n // file bundle and the host app. Otherwise, all deps will just be bundled.\n // So it'll work either way, this is just an optimization to avoid sending\n // multiple copies of the same library to your users.\n globals: {'left-pad': 'myLeftPad'},\n})\n```\n\n```tsx\n// server-rendered and/or client-side code that can run in the browser or Node:\ntodo\n```\n\n### Component Substitution\n\nMDX Bundler passes on\n[XDM's ability to substitute components](https://github.com/wooorm/xdm#mdx-content)\nthrough the `components` prop on the component returned by `getMDXComponent`.\n\nHere's an example that removes _p_ tags from around images.\n\n```tsx\nimport * as React from 'react'\ntodo\n\n \n```\n\n\n## Issues\n\n_Looking to contribute? Look for the [Good First Issue][good-first-issue]\nlabel._\n\n### ð Bugs\n\nPlease file an issue for bugs, missing documentation, or unexpected behavior.\n\n[**See Bugs**][bugs]\n\n### ðĄ Feature Requests\n\nPlease file an issue to suggest new features. Vote on feature requests by adding\na ð. This helps maintainers prioritize what to work on.\n\n[**See Feature Requests**][requests]\n\n\n\n## LICENSE\n\nMIT\n\n\n[npm]: https://www.npmjs.com\n[node]: https://nodejs.org\n[build-badge]: https://img.shields.io/github/workflow/status/koca/vue-mdx-bundler/validate?logo=github&style=flat-square\n[build]: https://github.com/koca/vue-mdx-bundler/actions?query=workflow%3Avalidate\n[coverage-badge]: https://img.shields.io/codecov/c/github/koca/vue-mdx-bundler.svg?style=flat-square\n[coverage]: https://codecov.io/github/koca/vue-mdx-bundler\n[version-badge]: https://img.shields.io/npm/v/vue-mdx-bundler.svg?style=flat-square\n[package]: https://www.npmjs.com/package/vue-mdx-bundler\n[downloads-badge]: https://img.shields.io/npm/dm/vue-mdx-bundler.svg?style=flat-square\n[npmtrends]: https://www.npmtrends.com/vue-mdx-bundler\n[license-badge]: https://img.shields.io/npm/l/vue-mdx-bundler.svg?style=flat-square\n[license]: https://github.com/koca/vue-mdx-bundler/blob/main/LICENSE\n[prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[prs]: https://makeapullrequest.com\n[coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square\n[coc]: https://github.com/koca/vue-mdx-bundler/blob/main/CODE_OF_CONDUCT.md\n[emojis]: https://github.com/all-contributors/all-contributors#emoji-key\n[all-contributors]: https://github.com/all-contributors/all-contributors\n[all-contributors-badge]: https://img.shields.io/github/all-contributors/koca/vue-mdx-bundler?color=orange&style=flat-square\n[bugs]: https://github.com/koca/vue-mdx-bundler/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3Abug\n[requests]: https://github.com/koca/vue-mdx-bundler/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement\n[good-first-issue]: https://github.com/koca/vue-mdx-bundler/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement+label%3A%22good+first+issue%22\n\n\n\n\n","readmeFilename":"README.md"}