Registry / serialization / unist-util-mdx-define

unist-util-mdx-define

library1.1.2jsnpmunverified

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.

serialization

npm install unist-util-mdx-define

github ↗package ↗

INSTALL

IMPORT

SIG · UNIST-UTIL-MDX-DEF

unist-util-mdx-define

serializationjavascriptv1.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

define

✓ import { define } from 'unist-util-mdx-define'

✗ const { define } = require('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.

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()

Debug

Known issues

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

affects: >=1.1.0

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

affects: >=1.0.0

gotchaVersion 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`).

affects: >=1.1.0

Errors

Common errors & fixes

Error: Cannot define variable 'exports' because it conflicts with an MDX internal.

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

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.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/remcohaszing/unist-util-mdx-define ↗

packagehttps://www.npmjs.com/package/unist-util-mdx-define ↗