Project: mdx-js/mdx

Package: @mdx-js/node-loader@2.2.1

  1. Dependents: 0
  2. Experimental Node loader for MDX
  1. remark 202
  2. markdown 155
  3. mdx 38
  4. node 25
  5. jsx 20
  6. react 15


Build Coverage Downloads Sponsors Backers Chat

Node loader for MDX.

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


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.


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


npm install @mdx-js/node-loader


yarn add @mdx-js/node-loader


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'


…then running that with:

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


<h1>Hello, World!</h1>


💡 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.


Create a Node ESM loader to compile MDX to JS.


options are the same as compile from @mdx-js/mdx. One extra field is supported:


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 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.



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.


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

An Options type is exported, which represents acceptable configuration.


See § Security on our website for information.


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.


MIT © Titus Wormer