hast to DOM Transformer

4.0.1 · active · verified Sun Apr 19

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.

Common errors

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

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.
```
TypeError: (0, hast_util_to_dom_1.toDom) is not a function
```
cause Incorrectly trying to access `toDom` as a default export or from an unexpected path when it is a named export.

fix Verify that you are using the correct named import: `import { toDom } from 'hast-util-to-dom'`.

Warnings

breaking Version 4.0.0 dropped support for Node.js versions prior to 16. Ensure your environment meets this minimum requirement.
Fix: Upgrade your Node.js runtime to version 16 or higher, or pin your `hast-util-to-dom` dependency to `<4.0.0`.
breaking The package transitioned to ESM-only starting with version 3.0.0. CommonJS `require()` statements will no longer work.
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`).
breaking 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.
Fix: Ensure all imports strictly use the public API paths (e.g., `import { toDom } from 'hast-util-to-dom'`).
breaking Version 3.0.0 removed support for transforming non-HTML doctypes. The utility is now strictly for HTML-based hast trees.
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.
gotcha 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.
Fix: Implement robust input sanitization and validation before creating `hast` trees from untrusted data. Use trusted `hast` processing libraries like `rehype-sanitize`.

Install

npm install hast-util-to-dom npm
yarn add hast-util-to-dom yarn
pnpm add hast-util-to-dom pnpm

Imports

toDom
wrong:
```
const toDom = require('hast-util-to-dom')
```
correct:
```
import { toDom } from 'hast-util-to-dom'
```
Package is ESM-only since v3.0.0. Named import is required, there is no default export.
AfterTransform
wrong:
```
import { AfterTransform } from 'hast-util-to-dom'
```
correct:
```
import type { AfterTransform } from 'hast-util-to-dom'
```
This is a TypeScript type. Use `import type` for type-only imports to avoid bundling issues.
Options
wrong:
```
import { Options } from 'hast-util-to-dom'
```
correct:
```
import type { Options } from 'hast-util-to-dom'
```
This is a TypeScript type. Use `import type` for type-only imports to avoid bundling issues.

Quickstart

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.

import { JSDOM } from 'jsdom';
import { h } from 'hastscript';
import { toDom } from 'hast-util-to-dom';

// Create a JSDOM environment to simulate a browser DOM
const dom = new JSDOM();
const document = dom.window.document;

// Construct a hast tree using hastscript (a helper for creating HAST nodes)
const hastTree = h('main', [
  h('h1', 'Welcome to the DOM!'),
  h('p', [
    h('strong', 'Hello'),
    ', world! This paragraph was created from a HAST node.'
  ]),
  h('ul', [
    h('li', 'Item 1'),
    h('li', 'Item 2')
  ])
]);

// Convert the hast tree into a DOM node. Pass the JSDOM document as an option.
const domNode = toDom(hastTree, { document });

// Append the generated DOM node to the JSDOM document body
document.body.append(domNode);

// You can now inspect or serialize the resulting DOM structure
console.log('Serialized DOM:', dom.serialize());

// Example of using the `afterTransform` hook option
const treeWithHook = h('div', [h('span', 'This span will be marked')]);
const domNodeWithHook = toDom(treeWithHook, {
  document,
  afterTransform(hastNode, domNode) {
    if (hastNode.type === 'element' && hastNode.tagName === 'span') {
      // Add a data attribute to the DOM span element
      (domNode as HTMLElement).dataset.transformed = 'true';
    }
  }
});
document.body.append(domNodeWithHook);
console.log('Serialized DOM with hook:', dom.serialize());

view raw JSON →