Skip to navigation
2-3 minutes read

@mdx-js/node-loader

Node.js hooks (also knows as loaders) for MDX.

Contents

What is this?

This package contains Node.js hooks to add support for importing MDX files. Node Customization Hooks are currently a release candidate.

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 (Next.js) or build system (Vite) which comes with a bundler, you can instead another integration: see § Integrations.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

Shell
npm install @mdx-js/node-loader

Use

Say we have an MDX document, example.mdx:

MDX
export function Thing() {
  return <>World!</>
}

# Hello, <Thing />

…and our module example.js looks as follows:

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

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

…then running with:

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

…yields:

HTML
<h1>Hello, World!</h1>

Note: if you use Node 18 and lower, then you can ignore the following warning:

Plain text
(node:20718) ExperimentalWarning: Custom ESM Loaders is an experimental feature and might change at any > time
(Use `node --trace-warnings ...` to show where the warning was created)

Note: if you use Node 20 and higher, then you get the following warning:

Plain text
(node:20908) ExperimentalWarning: `--experimental-loader` may be removed in the future; instead use > `register()`:
--import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from > "node:url"; register("%40mdx-js/node-loader", pathToFileURL("./"));'

You can solve that by adding a register.js file:

TypeScript
import {register} from 'node:module'

register('@mdx-js/node-loader', import.meta.url)

…and running node --import ./register.js example.js instead.

API

This package export the identifiers createLoader and load. There is no default export.

createLoader(options?)

Create Node.js hooks to handle markdown and MDX.

Parameters
  • options (Options, optional) — configuration
Returns

Node.js hooks ({load}).

load

Load file: URLs to MD(X) files.

See load in Node.js docs for more info.

Options

Configuration (TypeScript type).

Options are the same as CompileOptions from @mdx-js/mdx exception that the development option is supported based on whether you run Node with --conditions development. You cannot pass it manually.

Types

This package is fully typed with TypeScript. It exports the additional type Options. See § Types on our website for information.

Compatibility

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, @mdx-js/node-loader@^3, compatible with Node.js 16.

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