{"id":11285,"library":"mdast-util-definitions","title":"mdast-util-definitions","description":"mdast-util-definitions is a small, focused utility within the unified ecosystem designed to efficiently locate definition nodes within an mdast (Markdown Abstract Syntax Tree) based on their `identifier`. Currently at stable version 6.0.0, the package primarily sees updates related to Node.js version compatibility, ESM adoption, and type improvements, consistent with the unified collective's release cadence. A key differentiator is its ability to find definitions regardless of their position in the tree (even after references), its robustness against prototype pollution, and its adherence to CommonMark precedence rules (favoring earlier definitions in case of duplicates). Since version 5.0.0, it is an ESM-only package, requiring Node.js 16+ from version 6.0.0. It provides TypeScript types for enhanced developer experience.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-definitions","tags":["javascript","unist","mdast","mdast-util","util","utility","markdown","tree","node","typescript"],"install":[{"cmd":"npm install mdast-util-definitions","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-definitions","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-definitions","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v5.0.0. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error. There is no default export.","wrong":"const definitions = require('mdast-util-definitions')","symbol":"definitions","correct":"import { definitions } from 'mdast-util-definitions'"},{"note":"This is a TypeScript type for the function returned by `definitions(tree)`.","symbol":"GetDefinition","correct":"import type { GetDefinition } from 'mdast-util-definitions'"},{"note":"The package explicitly states there is no default export. Use named imports only.","wrong":"import definitions from 'mdast-util-definitions'","symbol":"Default export","correct":"/* No default export available */"}],"quickstart":{"code":"import {definitions} from 'mdast-util-definitions'\nimport {fromMarkdown} from 'mdast-util-from-markdown'\n\nconst markdownInput = `\n[example]: https://example.com \"Example\"\n[another]: /path/to/another \"Another Link\"\n\nThis is some text with a reference to [example].\nAnd another one to [another].\n\nA non-existent [foo] reference.\n`\n\nconst tree = fromMarkdown(markdownInput)\n\nconst getDefinition = definitions(tree)\n\nconsole.log('Definition for \"example\":', getDefinition('example'))\n// Expected: {type: 'definition', title: 'Example', url: 'https://example.com', identifier: 'example', label: 'example', ...}\n\nconsole.log('Definition for \"another\":', getDefinition('another'))\n// Expected: {type: 'definition', title: 'Another Link', url: '/path/to/another', identifier: 'another', label: 'another', ...}\n\nconsole.log('Definition for \"foo\":', getDefinition('foo'))\n// Expected: undefined\n\n// To illustrate how one might access all definitions, though 'definitions' returns a getter function\nconst allDefinitions = {}\ntree.children.forEach(node => {\n  if (node.type === 'definition') {\n    allDefinitions[node.identifier] = node\n  }\n})\nconsole.log('All definitions found in tree:', allDefinitions)","lang":"javascript","description":"Demonstrates how to use `mdast-util-definitions` to find definition nodes by identifier in an mdast tree generated from Markdown input."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or later.","message":"Version 6.0.0 changed to require Node.js 16 or newer. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Migrate your codebase to use ES Modules (ESM) with `import` statements. Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","message":"Since version 5.0.0, this package is ESM-only. CommonJS `require()` statements are no longer supported and will result in an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update your code to check for `undefined` instead of `null` when expecting a potentially missing definition.","message":"As of v6.0.0, `definitions(tree)('identifier')` now returns `undefined` when a definition is not found, instead of `null`.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Always use the public API through `import { definitions } from 'mdast-util-definitions'` and avoid internal paths.","message":"Version 6.0.0 changed to use `export` map, preventing direct imports of private APIs (e.g., `mdast-util-definitions/index.js`).","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Ensure your project's `@types/mdast` dependency is up-to-date and compatible with `mdast-util-definitions@6`.","message":"Type definitions were added in v3.0.0, and updated in v5.1.0 to use `mdast` types, then again in v6.0.0 with `@types/mdast`. This might cause type conflicts if your project uses older or incompatible `@types/mdast` versions.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Convert your project or specific file to ESM and use `import { definitions } from 'mdast-util-definitions'`.","cause":"Attempting to `require()` this package in a CommonJS environment, but it is ESM-only since v5.0.0.","error":"ERR_REQUIRE_ESM"},{"fix":"Update your code to check for `undefined` instead of `null`.","cause":"Your code is expecting `definitions(tree)('identifier')` to return `null` when a definition is not found, but it now returns `undefined` since v6.0.0.","error":"TypeError: Cannot read properties of null (reading '...')"},{"fix":"Use a named import: `import { definitions } from 'mdast-util-definitions'`.","cause":"Attempting to use a default import, e.g., `import definitions from 'mdast-util-definitions'`, when there is no default export.","error":"SyntaxError: The requested module 'mdast-util-definitions' does not provide an export named 'default'"},{"fix":"Remember to call `definitions(tree)` first, which returns another function (a getter). Then call the returned getter with your identifier: `const getDefinition = definitions(tree); getDefinition('my-id');`","cause":"This error can occur if you're trying to call `definitions()` directly without first passing the `tree` to it, or if there was a problem with the import.","error":"TypeError: definitions is not a function"}],"ecosystem":"npm"}