hast-util-to-parse5

8.0.1 · active · verified Sun Apr 19

hast-util-to-parse5 is a utility within the unified (syntax-tree) ecosystem designed to convert a HAST (Hypertext Abstract Syntax Tree) into a parse5 AST (Abstract Syntax Tree). It is currently at version 8.0.1 and receives updates as part of the broader unified collective, with major versions typically introducing significant changes and minor/patch versions addressing features and fixes. This package differentiates itself by avoiding the use of parse5 adapters, which the developers state reduces code weight and fragility. It is primarily used when there's a specific need to generate a parse5 AST from an existing HAST tree, though its inverse, `hast-util-from-parse5`, is often more commonly employed. The library is ESM-only and requires Node.js 16 or newer since its 8.x release line. Users should be aware of potential cross-site scripting (XSS) risks if the input HAST tree is not properly sanitized, as highlighted in its security considerations.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import `hast-util-to-parse5` in a CommonJS environment, but the package is ESM-only.

fix Change `const { toParse5 } = require('hast-util-to-parse5')` to `import { toParse5 } from 'hast-util-to-parse5'` and ensure your project is configured for ES modules (e.g., `"type": "module"` in `package.json`).
```
Argument of type 'string' is not assignable to parameter of type 'Options | undefined'.
```
cause Passing the `space` option directly as a string to `toParse5` after version 8.0.0.

fix Wrap the `space` option in an object: `toParse5(tree, { space: 'html' })`.

Warnings

breaking Version 8.0.0 removed direct support for passing the `space` option as a string. It must now be passed within an `options` object as `{ space: 'html' }` or `{ space: 'svg' }`.
Fix: Change `toParse5(tree, 'html')` to `toParse5(tree, { space: 'html' })`.
breaking Version 8.0.0 changed to require Node.js 16 or later. Older Node.js versions are no longer supported.
Fix: Update your Node.js environment to version 16 or newer. Alternatively, pin your `hast-util-to-parse5` dependency to `<8.0.0`.
breaking Version 8.0.0 updated its internal `@types/hast` dependency. If your project uses `@types/hast` directly, ensure you also update it to maintain compatibility.
Fix: Run `npm update @types/hast` or `yarn upgrade @types/hast`.
breaking Version 7.0.0 switched to being an ESM-only package. CommonJS `require()` is no longer supported.
Fix: Migrate your project to use ES modules (`import`/`export`) or use a dynamic `import()` statement. For TypeScript, ensure `"module": "Node16"` or `"ESNext"` is set in `tsconfig.json`.
breaking Version 7.0.0 removed support for transforming non-HTML doctypes.
Fix: Ensure that your input `hast` tree represents an HTML document. If you need to handle non-HTML doctypes, you may need to use an older version or a different utility.
gotcha The package uses the `exports` field in its `package.json`. Directly accessing internal paths (e.g., `hast-util-to-parse5/lib/index.js`) is not supported and may break in future versions.
Fix: Always import from the package root: `import { toParse5 } from 'hast-util-to-parse5'`.
gotcha Using `hast-util-to-parse5` with an untrusted HAST tree can lead to a cross-site scripting (XSS) attack if the resulting parse5 AST is later serialized and rendered without proper sanitization.
Fix: Always sanitize or validate the input HAST tree if it originates from untrusted sources, for example, using a tool like `hast-util-sanitize`.

Install

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

Imports

toParse5

wrong:

const toParse5 = require('hast-util-to-parse5')

correct:

import { toParse5 } from 'hast-util-to-parse5'

Package is ESM-only since v7.0.0. Use `import` statements.

Options

wrong:

import { Options } from 'hast-util-to-parse5'

correct:

import type { Options } from 'hast-util-to-parse5'

This symbol is a TypeScript type, not a runtime value. Use `import type`.

Space
wrong:
```
import { Space } from 'hast-util-to-parse5'
```
correct:
```
import type { Space } from 'hast-util-to-parse5'
```
This symbol is a TypeScript type, not a runtime value. Use `import type`.

Quickstart

This example demonstrates how to convert a complex HAST (Hypertext Abstract Syntax Tree) to a parse5 AST using `toParse5` and specify the `space` option.

import { toParse5 } from 'hast-util-to-parse5';
import type { Element, Text, Root } from 'hast';

const hastTree: Root = {
  type: 'root',
  children: [
    {
      type: 'element',
      tagName: 'html',
      properties: { lang: 'en' },
      children: [
        {
          type: 'element',
          tagName: 'head',
          properties: {},
          children: [
            { type: 'element', tagName: 'title', properties: {}, children: [{ type: 'text', value: 'Hello' }] as Text[] }
          ]
        } as Element,
        {
          type: 'element',
          tagName: 'body',
          properties: {},
          children: [
            { type: 'element', tagName: 'h1', properties: {}, children: [{ type: 'text', value: 'World!' }] as Text[] },
            { type: 'element', tagName: 'p', properties: {}, children: [{ type: 'text', value: 'This is a paragraph.' }] as Text[] }
          ]
        } as Element
      ]
    } as Element
  ]
};

// Convert the hast tree to a parse5 AST
const parse5Tree = toParse5(hastTree, { space: 'html' });

console.log(JSON.stringify(parse5Tree, null, 2));

/* Example of what the output parse5Tree might look like (truncated):
{
  "nodeName": "html",
  "tagName": "html",
  "attrs": [
    {
      "name": "lang",
      "value": "en"
    }
  ],
  "namespaceURI": "http://www.w3.org/1999/xhtml",
  "childNodes": [
    {
      "nodeName": "head",
      "tagName": "head",
      // ... more child nodes ...
    },
    {
      "nodeName": "body",
      "tagName": "body",
      // ... more child nodes ...
    }
  ]
}
*/

view raw JSON →