MDX Export Definition Utility

1.1.2 · active · verified Sun Apr 19

unist-util-mdx-define is a utility for the Unist ecosystem designed to simplify the process of defining exports within an MDX Abstract Syntax Tree (AST). It abstracts away the complexities of AST manipulation, allowing developers to easily expose variables from remark (mdast), rehype (hast), or recma (estree/esast) plugins. As of the current stable version 1.1.2, the package maintains a steady release cadence for minor and patch updates, focusing on robustness and compatibility within the `unified` and `MDX.js` ecosystems. Its key differentiator is its ability to uniformly inject export declarations across different stages of the MDX compilation pipeline (mdast, hast, estree), ensuring that variables defined at any stage are correctly available in the final MDX module without requiring manual AST traversal or complex insertion logic.

Common errors

```
Error: Cannot define variable 'exports' because it conflicts with an MDX internal.
```
cause Attempting to define a variable with a name reserved by MDX internals.

fix Choose a different variable name that does not conflict with MDX's internal keywords or exported symbols.
```
ReferenceError: myVariable is not defined
```
cause Trying to use a variable defined via `unist-util-mdx-define` in generated JavaScript code within the same plugin context, rather than in user-written MDX expressions.

fix Variables defined by `unist-util-mdx-define` are intended for use by user-defined MDX expressions. If you need to pass data between plugin stages, consider `file.data` or defining variables at a later stage (like recma) if internal generated code needs access.

Warnings

breaking As of v1.1.0, attempting to define a variable with a name that conflicts with MDX internal identifiers will now throw an error. Previously, this might have resulted in silent failures or unexpected behavior.
Fix: Ensure that the variable names you define do not clash with reserved MDX keywords or internal identifiers. Check your `define` calls for potential conflicts.
gotcha When using `unist-util-mdx-define` with mdast (remark) or hast (rehype) ASTs, the variable declarations are prepended to the root. While this ensures user-defined MDX expressions can use these variables, generated expressions within the same plugin are not guaranteed to be able to reference other variables defined by `unist-util-mdx-define`.
Fix: If your generated expressions require access to other defined variables, consider restructuring your plugin logic or defining variables at a later stage (e.g., recma) where the module scope is more fully resolved.
gotcha Version 1.1.0 introduced improved handling for invalid identifier names. While this prevents errors, ensure that the keys in the object passed to `define` conform to valid JavaScript identifier rules to avoid unexpected behavior or unaccessible variables.
Fix: Use valid JavaScript identifier names for all keys in the object passed as the third argument to the `define` function (e.g., `myVariable`, not `my-variable` or `1variable`).

Install

npm install unist-util-mdx-define npm
yarn add unist-util-mdx-define yarn
pnpm add unist-util-mdx-define pnpm

Imports

define
wrong:
```
const { define } = require('unist-util-mdx-define')
```
correct:
```
import { define } from 'unist-util-mdx-define'
```
This package is designed for ESM environments and `import` syntax is the standard.
Plugin
```
import { type Plugin } from 'unified'
```
While `Plugin` is not exported by `unist-util-mdx-define`, it is a common related import from `unified` when using this utility in plugins, especially for TypeScript users.
mdast.Root
```
import type * as mdast from 'mdast'
```
The utility works with various AST types; importing the correct type for your plugin's AST is crucial. This is a common pattern for mdast-based plugins.

Quickstart

This example demonstrates how to use `unist-util-mdx-define` within `remark`, `rehype`, and `recma` MDX plugins to export variables, which are then accessible in the MDX content.

import { compile } from '@mdx-js/mdx'
import type * as estree from 'estree'
import type * as hast from 'hast'
import type * as mdast from 'mdast'
import { type Plugin } from 'unified'
import { define } from 'unist-util-mdx-define'

const yourRemarkMdxPlugin: Plugin<[], mdast.Root> = () => (ast, file) => {
  define(ast, file, { remarkVariable: { type: 'Literal', value: 'Hello remark plugin!' } })
}

const yourRehypeMdxPlugin: Plugin<[], hast.Root> = () => (ast, file) => {
  define(ast, file, { rehypeVariable: { type: 'Literal', value: 'Hello rehype plugin!' } })
}

const yourRecmaMdxPlugin: Plugin<[], estree.Program> = () => (ast, file) => {
  define(ast, file, { recmaVariable: { type: 'Literal', value: 'Hello recma plugin!' } })
}

async function runExample() {
  const { value } = await compile('{remarkVariable} {rehypeVariable} {recmaVariable}', {
    remarkPlugins: [yourRemarkMdxPlugin],
    rehypePlugins: [yourRehypeMdxPlugin],
    recmaPlugins: [yourRecmaMdxPlugin]
  })
  console.log(value)
}

runExample()

view raw JSON →