hast-util-from-string

3.0.1 · active · verified Sun Apr 19

hast-util-from-string is a utility package within the unified and rehype ecosystem designed to efficiently set the plain-text value of a HAST (Hypertext Abstract Syntax Tree) node. It mimics the behavior of the DOM's `Node#textContent` setter, effectively replacing all children of a node with a single text node containing the provided string value. The current stable version is 3.0.1. As part of the unified collective, it follows a coordinated release cadence, often aligning major version bumps across related packages, though individual utilities receive minor and patch updates as needed. A key differentiator is its `textContent`-like behavior, contrasting with `hast-util-from-text` which emulates `innerText` and considers rendering specifics like line breaks and table cell separation. The library is ESM-only and fully typed with TypeScript.

Common errors

```
TypeError: require is not a function
```
cause Attempting to import `hast-util-from-string` using CommonJS `require()` syntax in a project after upgrading to v3 or when running in an environment that enforces ESM.

fix Change your import statement from `const { fromString } = require('hast-util-from-string')` to `import { fromString } from 'hast-util-from-string'`.
```
TypeError: Cannot read properties of undefined (reading 'type') (or similar when trying to access properties of the return value)
```
cause After upgrading to `hast-util-from-string` v3, the `fromString` function no longer returns the modified HAST node (it returns `undefined`). Code expecting a return value will fail.

fix Modify your code to retain a reference to the HAST node passed into `fromString`. The function modifies the node in place. For example, `const node = h('p'); fromString(node, 'hello'); // node is now modified`.

Warnings

breaking Starting with `hast-util-from-string` v3 (aligned with the unified ecosystem's v7 major release), the package became ESM-only. CommonJS `require()` statements will no longer work. Additionally, Node.js 16 or newer is now required.
Fix: Migrate your project to use ES modules (`import`/`export`) and ensure you are running Node.js 16 or later. Update your `tsconfig.json` and `package.json` to reflect ESM usage.
breaking In `hast-util-from-string` v3 (part of the unified ecosystem's v7), the `fromString` function no longer returns the modified `node` argument. It now returns `undefined`. You must maintain a reference to the original node if you intend to use it after the function call.
Fix: Ensure you keep a reference to the node passed to `fromString`. Do not rely on the function's return value. Example: `const myNode = h('p'); fromString(myNode, 'text'); console.log(myNode);`
gotcha When working with HTML using rehype utilities, improper handling of user-provided content can lead to Cross-Site Scripting (XSS) vulnerabilities. This package, by setting text content, can mitigate some risks but does not parse HTML itself. Other rehype utilities, especially those dealing with raw HTML, can introduce XSS if not properly sanitized.
Fix: Always use `rehype-sanitize` when processing untrusted HTML content in your rehype pipelines to strip out potentially malicious scripts or attributes.

Install

npm install hast-util-from-string npm
yarn add hast-util-from-string yarn
pnpm add hast-util-from-string pnpm

Imports

fromString
wrong:
```
const fromString = require('hast-util-from-string')
```
correct:
```
import { fromString } from 'hast-util-from-string'
```
This package is ESM-only since v3 and requires Node.js 16+. CommonJS `require` is not supported.
fromString (Deno)
```
import {fromString} from 'https://esm.sh/hast-util-from-string@3'
```
For Deno environments, import directly from esm.sh specifying the major version.

fromString (Browser)

<script type="module"> import {fromString} from 'https://esm.sh/hast-util-from-string@3?bundle' </script>

For browser environments, use esm.sh with the `?bundle` flag.

Quickstart

Demonstrates how to initialize an empty HAST node and how to overwrite an existing node's children with a new plain-text string using `fromString`.

import { h } from 'hastscript';
import { fromString } from 'hast-util-from-string';

// Create an empty paragraph node
const p = h('p');

// Set its plain-text value
fromString(p, 'Alpha');
console.log('Paragraph with new text:', JSON.stringify(p, null, 2));
// Expected output: { type: 'element', tagName: 'p', properties: {}, children: [ { type: 'text', value: 'Alpha' } ] }

// Create a div with existing children
const div = h('div', [h('b', 'Bold'), ' and ', h('i', 'italic'), '.']);
console.log('Original div:', JSON.stringify(div, null, 2));

// Overwrite its content with new plain text
fromString(div, 'Charlie');
console.log('Div with overwritten text:', JSON.stringify(div, null, 2));
// Expected output: { type: 'element', tagName: 'div', properties: {}, children: [ { type: 'text', value: 'Charlie' } ] }

view raw JSON →