@mdx-js/node-loader

Node loader for MDX.

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

Contents

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

What is this?

This package is a Node ESM loader to support MDX. ESM loaders are an experimental feature in Node, slated to change. They let projects “hijack” imports to do all sorts of fancy things, in this case it let’s you import MD(X) files.

When should I use this?

This integration is useful if you’re using Node and want to import MDX files from the file system.

If you’re using a bundler (webpack, Rollup, esbuild), or a site builder (Gatsby, Next.js) or build system (Vite, WMR) which comes with a bundler, you’re better off using another integration: see § Integrations.

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/node-loader

yarn:

yarn add @mdx-js/node-loader

Use

Say we have an MDX document, example.mdx:

export const Thing = () => <>World!</>

# Hello, <Thing />

…and our module example.js looks as follows:

import {renderToStaticMarkup} from 'react-dom/server'
import React from 'react'
import Content from './example.mdx'

console.log(renderToStaticMarkup(React.createElement(Content)))

…then running that with:

node --experimental-loader=@mdx-js/node-loader example.js

…yields:

<h1>Hello, World!</h1>

API

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

This package exports a Node ESM loader. It also exports the following identifier: createLoader.

createLoader(options?)

Create a Node ESM loader to compile MDX to JS.

options

options are the same as compile from @mdx-js/mdx.

Example

my-loader.js:

import {createLoader} from '@mdx-js/node-loader'

// Load is for Node 17+, the rest for 12-16.
const {load, getFormat, transformSource} = createLoader(/* Options… */)

export {load, getFormat, transformSource}

This example can then be used with node --experimental-loader=my-loader.js.

Node itself does not yet support multiple loaders but it is possible to combine multiple loaders with @node-loader/core.

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