{"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,"search_vec":"'5.0.0':44 'align':55 'api':80 'back':117 'block':105 'build':104 'cadenc':52 'code':6,25,126 'collect':49 'commit':84 'correspond':26 'current':40 'data':77 'design':19 'differenti':63 'display':132 'document':116 'ecosystem':18 'editor':131 'esm':92 'esm-on':91 'extract':21 'focus':13 'follow':46 'form':122 'formatt':127 'foundat':103 'fulli':95 'get':4 'includ':64 'integr':67 'javascript':87,134 'key':62 'like':89 'linter':125 'lts':60 'major':56 'minim':79 'modern':86 'need':109 'node':30,141 'node.js':59 'origin':23,120 'pars':115 'part':112 'posit':34,76,142 'practic':88 'releas':51,61 'reliabl':75 'repres':111 'rich':129 'serv':100 'snippet':133 'sourc':5,10,24,143 'specif':33,71 'stabl':41 'surfac':81 'text':130 'textual':121 'tight':66 'tool':107 'type':96 'typescript':98,144 'typic':54 'unifi':17,48 'unist':1,8,29,70,135,137 'unist-util':136 'unist-util-sourc':7 'util':2,9,14,138,139,140 'version':43,57 'vfile':37,73 'within':35","created_at":"2026-04-19T13:42:28.123157+00:00","updated_at":"2026-04-19T13:42:28.123157+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/syntax-tree/unist-util-source","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/unist-util-source","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}