Registry / web-framework / hast-util-from-html-isomorphic

hast-util-from-html-isomorphic

library2.0.0jsnpmunverified

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.

web-framework serialization

npm install hast-util-from-html-isomorphic

github ↗package ↗

INSTALL

IMPORT

SIG · HAST-UTIL-FROM-HTM

hast-util-from-html-isomorphic

web-frameworkjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

fromHtmlIsomorphic

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

✗ const { fromHtmlIsomorphic } = require('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.

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));

Debug

Known issues

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

affects: >=2.0.0

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

affects: >=1.0.0

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

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES module /node_modules/hast-util-from-html-isomorphic/index.js from ... not supported.

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.

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.

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

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/syntax-tree/hast-util-from-html-isomorphic ↗

packagehttps://www.npmjs.com/package/hast-util-from-html-isomorphic ↗