Unist Utility to Get Source Code

5.0.0 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import `unist-util-source` using CommonJS `require()` syntax.

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`).
```
TypeError: (0 , _unist_util_source__WEBPACK_IMPORTED_MODULE_0__.source) is not a function
```
cause Trying to use a default import (`import source from '...'`) when `source` is a named export, common in bundlers like Webpack.

fix Use a named import: `import { source } from 'unist-util-source'`.
```
TypeError: The 'file' argument must be an object with 'value' or a string, not 'object'
```
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).

fix Ensure `source` is called with the `VFile` instance as the first argument and the `Node` or `Position` as the second: `source(file, node)`.

Warnings

breaking Version 5.0.0 requires Node.js 16 or newer. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 16 or higher. If unable to upgrade, use `unist-util-source@^4`.
breaking The parameter order for the `source` function changed in v5.0.0 from `source(node, file)` to `source(file, node)`.
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)`.
breaking 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.
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.
breaking The package transitioned to ESM-only starting from v4.0.0. CommonJS `require()` is no longer supported for importing `unist-util-source`.
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`.
gotcha There is no default export. Attempting to `import source from 'unist-util-source'` will result in an error or `source` being `undefined`.
Fix: Always use named imports: `import { source } from 'unist-util-source'`.

Install

npm install unist-util-source npm
yarn add unist-util-source yarn
pnpm add unist-util-source pnpm

Imports

source
wrong:
```
const source = require('unist-util-source')
```
correct:
```
import { source } from 'unist-util-source'
```
The package is ESM-only since v4.0.0, so CommonJS `require` will fail. There is no default export; 'source' is a named export.
source (browser/Deno)
```
import { source } from 'https://esm.sh/unist-util-source@5'
```
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.

Quickstart

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

import { fromMarkdown } from 'mdast-util-from-markdown';
import { read } from 'to-vfile';
import { source } from 'unist-util-source';

async function main() {
  const markdownContent = `> + **[Hello](./example)**\n>   world.`;
  // In a real scenario, you'd read from a file: const file = await read('example.md');
  // For a self-contained example, we'll create a VFile from a string.
  const file = { path: 'example.md', value: markdownContent };
  const tree = fromMarkdown(String(file.value));

  // Navigate to a specific node (e.g., the 'strong' node containing 'Hello')
  // This path depends on the specific Markdown content and parser output.
  // For '> + **[Hello](./example)**\n>   world.', a 'strong' node is deep inside a blockquote, list, listItem, paragraph.
  // This assumes a typical parsing output structure for the example given in docs
  const blockquote = tree.children[0]; // The blockquote node
  const listItem = blockquote.children[0]; // The list item within the blockquote
  const paragraph = listItem.children[0]; // The paragraph within the list item
  const strongNode = paragraph.children[0].children[0].children[0].children[0].children[0];

  if (strongNode) {
    console.log(`Source for strong node: "${source(file, strongNode)}"`);
  } else {
    console.log('Could not find the strong node.');
  }
}

main().catch(console.error);

view raw JSON →