{"id":10997,"library":"hast-util-from-html-isomorphic","title":"Isomorphic HTML to HAST Tree Converter","description":"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.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-from-html-isomorphic","tags":["javascript","unist","hast","hast-util","util","utility","html","parse","dom","typescript"],"install":[{"cmd":"npm install hast-util-from-html-isomorphic","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-from-html-isomorphic","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-from-html-isomorphic","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v1; CommonJS require() is not supported.","wrong":"const { fromHtmlIsomorphic } = require('hast-util-from-html-isomorphic')","symbol":"fromHtmlIsomorphic","correct":"import { fromHtmlIsomorphic } from 'hast-util-from-html-isomorphic'"},{"note":"Import for the TypeScript type definition of the options object.","symbol":"Options","correct":"import type { Options } from 'hast-util-from-html-isomorphic'"},{"note":"The return type 'Root' for the HAST tree comes from the 'hast' package, a peer dependency.","symbol":"Root","correct":"import type { Root } from 'hast'"}],"quickstart":{"code":"import { fromHtmlIsomorphic } from 'hast-util-from-html-isomorphic';\nimport type { Root } from 'hast';\n\n// Example 1: Parsing a simple HTML fragment\n// When `fragment: true`, it parses only the content within the `` or directly as children of `root`.\nconst fragmentHtml = '

Hello, world!

This is a paragraph.

';\nconst fragmentTree: Root = fromHtmlIsomorphic(fragmentHtml, { fragment: true });\n\nconsole.log('--- Parsed as Fragment ---');\nconsole.log(JSON.stringify(fragmentTree, null, 2));\n\n// Example 2: Parsing a full HTML document\n// By default (or with `fragment: false`), it expects a complete document structure.\n// Unopened `html`, `head`, and `body` elements will be implicitly added.\nconst documentHtml = 'My Doc

Document Title

More content.

';\nconst documentTree: Root = fromHtmlIsomorphic(documentHtml);\n\nconsole.log('\\n--- Parsed as Document ---');\nconsole.log(JSON.stringify(documentTree, null, 2));\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Run `npm install hast@latest @types/hast@latest` or `yarn add hast@latest @types/hast@latest` in your project.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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'`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { fromHtmlIsomorphic } = require(...)` to `import { fromHtmlIsomorphic } from '...'`. Ensure your Node.js environment and project configuration support ESM.","cause":"Attempting to import an ESM-only package using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: require() of ES module /node_modules/hast-util-from-html-isomorphic/index.js from ... not supported."},{"fix":"Update your project's `hast` and `@types/hast` packages to their latest compatible versions. For example, `npm update hast @types/hast`.","cause":"Type definitions mismatch after a major version update (e.g., 2.0.0), often due to outdated `@types/hast` or `hast` packages.","error":"TS2345: Argument of type 'string' is not assignable to parameter of type 'TrustedHTML' or similar type conflict related to 'hast' types."},{"fix":"This is expected behavior. If you require positional information, you must use `hast-util-from-html` instead of `hast-util-from-html-isomorphic`.","cause":"The generated HAST tree nodes explicitly lack positional information (`node.position` will be undefined) by design, for bundle size optimization.","error":"TypeError: Cannot read properties of undefined (reading 'position') or similar when accessing positional data."}],"ecosystem":"npm"}