hast-util-from-dom

5.0.1 · active · verified Sun Apr 19

hast-util-from-dom is a utility package designed to convert a DOM tree (either from a browser's native DOM or headless environments like JSDOM) into a HAST (Hypertext Abstract Syntax Tree) HTML syntax tree. It is part of the unified ecosystem for processing text. The current stable version is 5.0.1, which is ESM-only and requires Node.js 16 or newer. It typically follows the release cadence of the wider unified ecosystem. Key differentiators include its small size, primary suitability for browser environments, and its explicit choice *not* to provide positional information, which distinguishes it from more comprehensive parsing solutions. It serves as the inverse to `hast-util-to-dom` and is wrapped by `rehype-dom-parse` for HTML parsing with DOM APIs. While efficient for its purpose, users should be aware that it might yield varying results in different or older browsers.

Common errors

```
TypeError: require is not a function
```
cause Attempting to use `require()` to import `hast-util-from-dom` in an ES module context or Node.js >=16 with `type: "module"` set.

fix Change your import statement to `import { fromDom } from 'hast-util-from-dom';`. Ensure your environment supports ES modules.
```
Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'hast-util-from-dom' imported from ...
```
cause This usually indicates a problem with module resolution in Node.js 16+ due to `hast-util-from-dom` using the `exports` field.

fix Ensure your Node.js project is configured correctly for ES modules, typically by using `.mjs` files or setting `"type": "module"` in your `package.json`. If you are in a CJS context, you might need to use dynamic `import()` or adjust your module resolver configuration.
```
Argument of type 'null' is not assignable to parameter of type 'DomNode'.
```
cause You are passing `null` or `undefined` to the `fromDom` function, which expects a valid DOM node.

fix Add a check to ensure the DOM node you are passing is not `null` or `undefined` before calling `fromDom`, e.g., `const element = document.querySelector('some-selector'); if (element) { fromDom(element); }`

Warnings

breaking Version 5.0.0 changed the package to be ESM-only and requires Node.js 16+. Old CommonJS `require()` statements will no longer work.
Fix: Migrate your project to use ES modules (`import`/`export`) or use a tool like `esm.sh` for browser environments. Ensure your Node.js version is 16 or newer.
breaking Version 5.0.0 updated `@types/hast` and utilities, requiring users to update their own dependencies and potentially adjust type usages.
Fix: Update your `@types/hast` and other `@types/*` dependencies to their latest versions to ensure compatibility with `hast-util-from-dom@5`.
breaking Version 5.0.0 removed undocumented support for passing no node to `fromDom`. It now strictly requires valid input.
Fix: Always pass a valid DOM node (`DomNode`) to the `fromDom` function. Ensure the input is not `null` or `undefined`.
breaking Version 4.0.0 removed support for non-HTML doctypes, focusing solely on HTML transformations.
Fix: Ensure that the input DOM tree corresponds to a valid HTML document. If you need to handle non-HTML doctypes, consider older versions or alternative parsers.
gotcha This utility does not provide positional information (line, column numbers) for the generated HAST nodes. If you require source mapping or detailed error reporting based on position, this utility is not suitable.
Fix: If positional information is critical, consider using `rehype-parse` which typically generates full positional data.
gotcha Results can vary in different (especially older) browser environments due to inconsistencies in DOM API implementations. While designed for browser use, testing across target browsers is recommended.
Fix: Thoroughly test the output of `hast-util-from-dom` in all targeted browser environments, particularly if supporting legacy browsers.

Install

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

Imports

fromDom
wrong:
```
const fromDom = require('hast-util-from-dom')
```
correct:
```
import { fromDom } from 'hast-util-from-dom'
```
Package is ESM-only since v5.0.0. CommonJS `require()` is not supported.
Options
wrong:
```
import { Options } from 'hast-util-from-dom'
```
correct:
```
import type { Options } from 'hast-util-from-dom'
```
This is a TypeScript type for configuring the `fromDom` function. Use `import type`.

AfterTransform

wrong:

import { AfterTransform } from 'hast-util-from-dom'

correct:

import type { AfterTransform } from 'hast-util-from-dom'

This is a TypeScript type for the callback hook. Use `import type`.

Quickstart

Demonstrates converting a DOM element (from JSDOM in Node.js) into a HAST tree.

import { fromDom } from 'hast-util-from-dom';
import { JSDOM } from 'jsdom';

const htmlContent = `
  <!doctype html>
  <title>Example</title>
  <body>
    <main>
      <h1>Hi</h1>
      <p><em>Hello</em>, world!</p>
    </main>
  </body>
`;

const dom = new JSDOM(htmlContent);
const document = dom.window.document;

// Select an element from the simulated DOM
const mainElement = document.querySelector('main');

if (mainElement) {
  // Transform the DOM element into a hast tree
  const hast = fromDom(mainElement);

  // Log the resulting hast tree structure
  console.log(JSON.stringify(hast, null, 2));
} else {
  console.error('Main element not found in the DOM.');
}

view raw JSON →