{"id":12302,"library":"unist-util-source","title":"Unist Utility to Get Source Code","description":"unist-util-source is a focused utility in the unified ecosystem designed to extract the original source code corresponding to a `unist` node or a specific position within a `VFile`. It is currently stable at version 5.0.0 and follows the unified collective's release cadence, which typically aligns major versions with Node.js LTS releases. Key differentiators include its tight integration with the `unist` specification and `vfile` for reliable positional data, its minimal API surface, and its commitment to modern JavaScript practices like being ESM-only and fully typed with TypeScript. It serves as a foundational building block for tools that need to represent parts of a parsed document back in their original textual form, such as linters, code formatters, or rich text editors displaying snippets.","status":"active","version":"5.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-source","tags":["javascript","unist","unist-util","util","utility","node","position","source","typescript"],"install":[{"cmd":"npm install unist-util-source","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-source","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-source","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"The primary API function `source` expects a VFile instance as its first argument to operate on.","package":"vfile","optional":false},{"reason":"Crucial for type compatibility and ensuring the `unist` nodes passed to `source` are correctly typed. Consumers should keep this in sync with their `unist` version.","package":"@types/unist","optional":false}],"imports":[{"note":"The package is ESM-only since v4.0.0, so CommonJS `require` will fail. There is no default export; 'source' is a named export.","wrong":"const source = require('unist-util-source')","symbol":"source","correct":"import { source } from 'unist-util-source'"},{"note":"For browser or Deno environments, it's recommended to use a CDN like esm.sh. The version should be pinned to prevent unexpected breaking changes.","symbol":"source (browser/Deno)","correct":"import { source } from 'https://esm.sh/unist-util-source@5'"}],"quickstart":{"code":"import { fromMarkdown } from 'mdast-util-from-markdown';\nimport { read } from 'to-vfile';\nimport { source } from 'unist-util-source';\n\nasync function main() {\n  const markdownContent = `> + **[Hello](./example)**\\n>   world.`;\n  // In a real scenario, you'd read from a file: const file = await read('example.md');\n  // For a self-contained example, we'll create a VFile from a string.\n  const file = { path: 'example.md', value: markdownContent };\n  const tree = fromMarkdown(String(file.value));\n\n  // Navigate to a specific node (e.g., the 'strong' node containing 'Hello')\n  // This path depends on the specific Markdown content and parser output.\n  // For '> + **[Hello](./example)**\\n>   world.', a 'strong' node is deep inside a blockquote, list, listItem, paragraph.\n  // This assumes a typical parsing output structure for the example given in docs\n  const blockquote = tree.children[0]; // The blockquote node\n  const listItem = blockquote.children[0]; // The list item within the blockquote\n  const paragraph = listItem.children[0]; // The paragraph within the list item\n  const strongNode = paragraph.children[0].children[0].children[0].children[0].children[0];\n\n  if (strongNode) {\n    console.log(`Source for strong node: \"${source(file, strongNode)}\"`);\n  } else {\n    console.log('Could not find the strong node.');\n  }\n}\n\nmain().catch(console.error);","lang":"typescript","description":"Demonstrates how to read a Markdown string, parse it into a unist tree using `mdast-util-from-markdown`, and then extract the source code for a specific `strong` node using `unist-util-source`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher. If unable to upgrade, use `unist-util-source@^4`.","message":"Version 5.0.0 requires Node.js 16 or newer. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update all calls to `source` to pass the `VFile` instance as the first argument and the `Node` or `Position` as the second: `source(file, node)`.","message":"The parameter order for the `source` function changed in v5.0.0 from `source(node, file)` to `source(file, node)`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Update consumers of `source`'s return value to explicitly handle `undefined` checks. For example, `const text = source(file, node) ?? ''` if an empty string is desired for missing source.","message":"Since v5.0.0, `source` now returns `undefined` if no source can be found for a given node or position, instead of an empty string.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Migrate your project to use ES modules (`import`). Ensure your `package.json` specifies `\"type\": \"module\"` or use `.mjs` file extensions. If sticking to CommonJS, you must use `unist-util-source@^3`.","message":"The package transitioned to ESM-only starting from v4.0.0. CommonJS `require()` is no longer supported for importing `unist-util-source`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Always use named imports: `import { source } from 'unist-util-source'`.","message":"There is no default export. Attempting to `import source from 'unist-util-source'` will result in an error or `source` being `undefined`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Switch to ES module `import { source } from 'unist-util-source'` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to import `unist-util-source` using CommonJS `require()` syntax.","error":"ERR_REQUIRE_ESM"},{"fix":"Use a named import: `import { source } from 'unist-util-source'`.","cause":"Trying to use a default import (`import source from '...'`) when `source` is a named export, common in bundlers like Webpack.","error":"TypeError: (0 , _unist_util_source__WEBPACK_IMPORTED_MODULE_0__.source) is not a function"},{"fix":"Ensure `source` is called with the `VFile` instance as the first argument and the `Node` or `Position` as the second: `source(file, node)`.","cause":"Incorrect parameter order when calling `source`, specifically passing the `node` as the first argument instead of the `file` (a breaking change in v5.0.0).","error":"TypeError: The 'file' argument must be an object with 'value' or a string, not 'object'"}],"ecosystem":"npm"}