{"id":12295,"library":"unist-util-mdx-define","title":"MDX Export Definition Utility","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/remcohaszing/unist-util-mdx-define","tags":["javascript"],"install":[{"cmd":"npm install unist-util-mdx-define","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-mdx-define","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-mdx-define","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is designed for ESM environments and `import` syntax is the standard.","wrong":"const { define } = require('unist-util-mdx-define')","symbol":"define","correct":"import { define } from 'unist-util-mdx-define'"},{"note":"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.","symbol":"Plugin","correct":"import { type Plugin } from 'unified'"},{"note":"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.","symbol":"mdast.Root","correct":"import type * as mdast from 'mdast'"}],"quickstart":{"code":"import { compile } from '@mdx-js/mdx'\nimport type * as estree from 'estree'\nimport type * as hast from 'hast'\nimport type * as mdast from 'mdast'\nimport { type Plugin } from 'unified'\nimport { define } from 'unist-util-mdx-define'\n\nconst yourRemarkMdxPlugin: Plugin<[], mdast.Root> = () => (ast, file) => {\n  define(ast, file, { remarkVariable: { type: 'Literal', value: 'Hello remark plugin!' } })\n}\n\nconst yourRehypeMdxPlugin: Plugin<[], hast.Root> = () => (ast, file) => {\n  define(ast, file, { rehypeVariable: { type: 'Literal', value: 'Hello rehype plugin!' } })\n}\n\nconst yourRecmaMdxPlugin: Plugin<[], estree.Program> = () => (ast, file) => {\n  define(ast, file, { recmaVariable: { type: 'Literal', value: 'Hello recma plugin!' } })\n}\n\nasync function runExample() {\n  const { value } = await compile('{remarkVariable} {rehypeVariable} {recmaVariable}', {\n    remarkPlugins: [yourRemarkMdxPlugin],\n    rehypePlugins: [yourRehypeMdxPlugin],\n    recmaPlugins: [yourRecmaMdxPlugin]\n  })\n  console.log(value)\n}\n\nrunExample()","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Choose a different variable name that does not conflict with MDX's internal keywords or exported symbols.","cause":"Attempting to define a variable with a name reserved by MDX internals.","error":"Error: Cannot define variable 'exports' because it conflicts with an MDX internal."},{"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.","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.","error":"ReferenceError: myVariable is not defined"}],"ecosystem":"npm"}