{"id":11014,"library":"hast-util-to-dom","title":"hast to DOM Transformer","description":"This package, `hast-util-to-dom`, serves as a utility for converting a `hast` (HTML Abstract Syntax Tree) into a browser-native DOM tree or a simulated DOM environment like `jsdom`. The current stable version is 4.0.1. The project generally follows Node.js maintenance cycles for compatibility, dropping support for unmaintained Node.js versions with major releases. It has a steady release cadence, with version 4.0.0 released recently to update dependencies and enforce modern JavaScript environments. Key differentiators include its tight integration within the unified ecosystem, providing a direct transformation path for HTML ASTs to DOM nodes. It supports client-side rendering directly into the browser's DOM, and also works in server-side contexts with DOM implementations like `jsdom`. It complements `hast-util-from-dom`, which performs the inverse operation, turning DOM trees into hast. Furthermore, `hast-util-to-dom` is utilized internally by `rehype-dom-stringify` for DOM-based HTML serialization. It is important to note that the library transitioned to being ESM-only since version 3.0.0 and requires Node.js 16 or newer as of version 4.0.0, which are significant compatibility considerations for integrators.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-to-dom","tags":["javascript","dom","hast-util","hast","html","rehype","unist","utility","util","typescript"],"install":[{"cmd":"npm install hast-util-to-dom","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-to-dom","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-to-dom","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only since v3.0.0. Named import is required, there is no default export.","wrong":"const toDom = require('hast-util-to-dom')","symbol":"toDom","correct":"import { toDom } from 'hast-util-to-dom'"},{"note":"This is a TypeScript type. Use `import type` for type-only imports to avoid bundling issues.","wrong":"import { AfterTransform } from 'hast-util-to-dom'","symbol":"AfterTransform","correct":"import type { AfterTransform } from 'hast-util-to-dom'"},{"note":"This is a TypeScript type. Use `import type` for type-only imports to avoid bundling issues.","wrong":"import { Options } from 'hast-util-to-dom'","symbol":"Options","correct":"import type { Options } from 'hast-util-to-dom'"}],"quickstart":{"code":"import { JSDOM } from 'jsdom';\nimport { h } from 'hastscript';\nimport { toDom } from 'hast-util-to-dom';\n\n// Create a JSDOM environment to simulate a browser DOM\nconst dom = new JSDOM();\nconst document = dom.window.document;\n\n// Construct a hast tree using hastscript (a helper for creating HAST nodes)\nconst hastTree = h('main', [\n  h('h1', 'Welcome to the DOM!'),\n  h('p', [\n    h('strong', 'Hello'),\n    ', world! This paragraph was created from a HAST node.'\n  ]),\n  h('ul', [\n    h('li', 'Item 1'),\n    h('li', 'Item 2')\n  ])\n]);\n\n// Convert the hast tree into a DOM node. Pass the JSDOM document as an option.\nconst domNode = toDom(hastTree, { document });\n\n// Append the generated DOM node to the JSDOM document body\ndocument.body.append(domNode);\n\n// You can now inspect or serialize the resulting DOM structure\nconsole.log('Serialized DOM:', dom.serialize());\n\n// Example of using the `afterTransform` hook option\nconst treeWithHook = h('div', [h('span', 'This span will be marked')]);\nconst domNodeWithHook = toDom(treeWithHook, {\n  document,\n  afterTransform(hastNode, domNode) {\n    if (hastNode.type === 'element' && hastNode.tagName === 'span') {\n      // Add a data attribute to the DOM span element\n      (domNode as HTMLElement).dataset.transformed = 'true';\n    }\n  }\n});\ndocument.body.append(domNodeWithHook);\nconsole.log('Serialized DOM with hook:', dom.serialize());","lang":"typescript","description":"Demonstrates converting a `hast` tree to a DOM tree using `toDom` with `jsdom` for a Node.js environment. It also shows how to use the `afterTransform` option."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 16 or higher, or pin your `hast-util-to-dom` dependency to `<4.0.0`.","message":"Version 4.0.0 dropped support for Node.js versions prior to 16. Ensure your environment meets this minimum requirement.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your import statements to use ES Modules (`import ... from 'hast-util-to-dom'`). Configure your project for ESM if necessary (e.g., `\"type\": \"module\"` in `package.json`).","message":"The package transitioned to ESM-only starting with version 3.0.0. CommonJS `require()` statements will no longer work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure all imports strictly use the public API paths (e.g., `import { toDom } from 'hast-util-to-dom'`).","message":"Version 4.0.0 introduced the `exports` field in `package.json`. Avoid using private or undocumented import paths, as they may no longer be accessible or stable.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your input `hast` trees represent valid HTML structures. If you need to handle non-HTML doctypes, you may need to use an older version or a different utility.","message":"Version 3.0.0 removed support for transforming non-HTML doctypes. The utility is now strictly for HTML-based hast trees.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Implement robust input sanitization and validation before creating `hast` trees from untrusted data. Use trusted `hast` processing libraries like `rehype-sanitize`.","message":"As with any utility that transforms arbitrary input into DOM, care must be taken to prevent Cross-Site Scripting (XSS) vulnerabilities if the `hast` input is derived from untrusted sources. Sanitize input appropriately.","severity":"gotcha","affected_versions":">=2.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change your import statement from `const toDom = require('hast-util-to-dom')` to `import { toDom } from 'hast-util-to-dom'`. Ensure your project is configured for ES Modules.","cause":"Attempting to import an ESM-only package using CommonJS `require()` syntax.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... hast-util-to-dom/index.js from ... not supported."},{"fix":"Verify that you are using the correct named import: `import { toDom } from 'hast-util-to-dom'`.","cause":"Incorrectly trying to access `toDom` as a default export or from an unexpected path when it is a named export.","error":"TypeError: (0, hast_util_to_dom_1.toDom) is not a function"}],"ecosystem":"npm"}