Isomorphic HTML to HAST Tree Converter

2.0.0 · active · verified Sun Apr 19

hast-util-from-html-isomorphic is a utility package for the hast ecosystem that efficiently converts HTML strings into a hast (HTML Abstract Syntax Tree) tree. Designed for isomorphic applications, it intelligently uses hast-util-from-dom in browser environments, leveraging native DOM parsing APIs for a significantly smaller bundle size, and falls back to hast-util-from-html in Node.js. This approach prioritizes minimal client-side footprint, making it ideal for web components, static site generators, or libraries that need to process HTML both server-side and client-side without a large parser overhead. A key characteristic is that it does not preserve positional information (line, column, offset) from the original HTML string, a deliberate trade-off for its performance and size benefits. The current stable version is 2.0.0, which updated its @types/hast dependency. This package is part of the syntax-tree unified ecosystem and generally sees updates as underlying dependencies or major features warrant, rather than on a strict time-based cadence.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES module /node_modules/hast-util-from-html-isomorphic/index.js from ... not supported.
```
cause Attempting to import an ESM-only package using CommonJS `require()` syntax.

fix Change `const { fromHtmlIsomorphic } = require(...)` to `import { fromHtmlIsomorphic } from '...'`. Ensure your Node.js environment and project configuration support ESM.
```
TS2345: Argument of type 'string' is not assignable to parameter of type 'TrustedHTML' or similar type conflict related to 'hast' types.
```
cause Type definitions mismatch after a major version update (e.g., 2.0.0), often due to outdated `@types/hast` or `hast` packages.

fix Update your project's `hast` and `@types/hast` packages to their latest compatible versions. For example, `npm update hast @types/hast`.
```
TypeError: Cannot read properties of undefined (reading 'position') or similar when accessing positional data.
```
cause The generated HAST tree nodes explicitly lack positional information (`node.position` will be undefined) by design, for bundle size optimization.

fix This is expected behavior. If you require positional information, you must use `hast-util-from-html` instead of `hast-util-from-html-isomorphic`.

Warnings

breaking Version 2.0.0 updated its internal dependency on `@types/hast`. If your project uses an older version of `@types/hast` or `hast` itself, you may encounter type conflicts or unexpected behavior. Update your project's `hast` and `@types/hast` dependencies to their latest compatible versions.
Fix: Run `npm install hast@latest @types/hast@latest` or `yarn add hast@latest @types/hast@latest` in your project.
gotcha This package is ESM-only. Attempting to use `require()` to import `hast-util-from-html-isomorphic` in a CommonJS environment will result in a runtime error.
Fix: Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use dynamic `import()` within CommonJS files. Always use `import ... from 'hast-util-from-html-isomorphic'`.
gotcha The HAST trees generated by `fromHtmlIsomorphic` do not contain positional information (line, column, offset). This is a deliberate design choice to achieve a smaller bundle size, particularly beneficial in browser environments.
Fix: If positional information is critical for your use case (e.g., linting, detailed error reporting), use `hast-util-from-html` instead, which provides this data but has a larger bundle size.

Install

npm install hast-util-from-html-isomorphic npm
yarn add hast-util-from-html-isomorphic yarn
pnpm add hast-util-from-html-isomorphic pnpm

Imports

fromHtmlIsomorphic

wrong:

const { fromHtmlIsomorphic } = require('hast-util-from-html-isomorphic')

correct:

import { fromHtmlIsomorphic } from 'hast-util-from-html-isomorphic'

This package is ESM-only since v1; CommonJS require() is not supported.

Options
```
import type { Options } from 'hast-util-from-html-isomorphic'
```
Import for the TypeScript type definition of the options object.
Root
```
import type { Root } from 'hast'
```
The return type 'Root' for the HAST tree comes from the 'hast' package, a peer dependency.

Quickstart

Demonstrates parsing HTML strings into HAST trees, showing the difference between parsing as a document (default) and as a fragment, highlighting the common usage patterns.

import { fromHtmlIsomorphic } from 'hast-util-from-html-isomorphic';
import type { Root } from 'hast';

// Example 1: Parsing a simple HTML fragment
// When `fragment: true`, it parses only the content within the `<body>` or directly as children of `root`.
const fragmentHtml = '<h1>Hello, world!</h1><p>This is a paragraph.</p>';
const fragmentTree: Root = fromHtmlIsomorphic(fragmentHtml, { fragment: true });

console.log('--- Parsed as Fragment ---');
console.log(JSON.stringify(fragmentTree, null, 2));

// Example 2: Parsing a full HTML document
// By default (or with `fragment: false`), it expects a complete document structure.
// Unopened `html`, `head`, and `body` elements will be implicitly added.
const documentHtml = '<title>My Doc</title><body><h1>Document Title</h1><p>More content.</p></body>';
const documentTree: Root = fromHtmlIsomorphic(documentHtml);

console.log('\n--- Parsed as Document ---');
console.log(JSON.stringify(documentTree, null, 2));

view raw JSON →