@mdx-js/esbuild

@mdx-js/esbuild

esbuild plugin for MDX.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • mdx(options?)
• Types
• Security
• Contribute
• License

What is this?

This package is an esbuild plugin to support MDX.

When should I use this?

This integration is useful if you’re using esbuild (or another tool that uses esbuild).

If you want to evaluate MDX code then the lower-level compiler (@mdx-js/mdx) can be used. to support nonstandard JSX runtime (such as Vue), @mdx-js/mdx can also be used, or our webpack loader (@mdx-js/loader) or Rollup plugin (@mdx-js/rollup).

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install @mdx-js/esbuild

yarn:

yarn add @mdx-js/esbuild

Use

Do something like this with the esbuild API:

import esbuild from 'esbuild'
import mdx from '@mdx-js/esbuild'

await esbuild.build({
  entryPoints: ['index.mdx'],
  outfile: 'output.js',
  format: 'esm',
  plugins: [mdx({/* Options… */})]
})

API

This package exports a function as the default export that returns an esbuild plugin.

mdx(options?)

Create an esbuild plugin to compile MDX to JS.

esbuild takes care of turning modern JavaScript features into syntax that works wherever you want it to. With other integrations you might need to use Babel for this, but with esbuild that’s not needed. See esbuild’s docs for more info.

options

options are the same as compile from @mdx-js/mdx with the addition of:

options.allowDangerousRemoteMdx

⚠️ Security: this includes remote code in your bundle. Make sure you trust it! See § Security for more info.

💡 Experiment: this is an experimental feature that might not work well and might change in minor releases.

Whether to allow importing from http: and https: URLs (boolean, default: false).

When passing allowDangerousRemoteMdx, MD(X) and JS files can be imported from http: and https: urls. Take this index.mdx file:

import Readme from 'https://raw.githubusercontent.com/mdx-js/mdx/main/readme.md'

Here’s the readme:

<Readme />

And a module build.js:

import esbuild from 'esbuild'
import mdx from '@mdx-js/esbuild'

await esbuild.build({
  entryPoints: ['index.mdx'],
  outfile: 'output.js',
  format: 'esm',
  plugins: [mdx({allowDangerousRemoteMdx: true, /* Other options… */})]
})

Running that (node build.js) and evaluating output.js (depends on how you evaluate React stuff) would give:

<p>Here’s the readme:</p>
<h1>MDX: Markdown for the component era 🚀</h1>
{/* … */}
<p><a href="https://github.com/mdx-js/mdx/blob/main/license">MIT</a> © …</p>

Types

This package is fully typed with TypeScript. See § Types on our website for information.

An Options type is exported, which represents acceptable configuration.

Security

See § Security on our website for information.

Contribute

See § Contribute on our website for ways to get started. See § Support for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer