Registry / serialization / unist-util-source

unist-util-source

JSON →
library5.0.0jsnpmunverified

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.

npm install unist-util-source
INSTALL
IMPORT
SIG · UNIST-UTIL-SOURCE
U
unist-util-source
serializationjavascriptv5.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

source
import { source } from 'unist-util-source'
const source = require('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.

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);
Debug
Known issues
breakingVersion 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`.
affects: >=5.0.0
breakingThe 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)`.
affects: >=5.0.0
breakingSince 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.
affects: >=5.0.0
breakingThe 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`.
affects: >=4.0.0
gotchaThere 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'`.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
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
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'
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)`.
Upgrade
Version history
5.0.0latest on npm
Audit
Dependencies
vfilerequiredThe primary API function `source` expects a VFile instance as its first argument to operate on.
@types/unistrequiredCrucial for type compatibility and ensuring the `unist` nodes passed to `source` are correctly typed. Consumers should keep this in sync with their `unist` version.
Agent activity
7 hits · last 30 days
node
6
OpenAI (training)
1
Resources
unist-util-source — npm install unist-util-source · libregistry