Skip to navigation
2-3 minutes read

@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?

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:

Shell
npm install @mdx-js/node-loader

yarn:

Shell
yarn add @mdx-js/node-loader

Use

Say we have an MDX document, example.mdx:

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

# Hello, <Thing />

…and our module example.js looks as follows:

JavaScript
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:

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

…yields:

HTML
<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. One extra field is supported:

options.fixRuntimeWithoutExportMap

Fix broken export maps (boolean, default: true).

Several JSX runtimes, notably React below 18 and Emotion below 11.10.0, don’t have a proper export map set up. Export maps are needed to map xxx/jsx-runtime.js to an actual file in ESM. This option fixes React et al by turning those into xxx/jsx-runtime.js.

👉 Note: If you are using recent React, or other proper packages, you have to turn this field off. See the example below on how to configure your loader. Pass fixRuntimeWithoutExportMap: false in options to it.

Example

my-loader.js:

JavaScript
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