hast to ESTree (JSX) Transformer

3.1.3 · active · verified Sun Apr 19

hast-util-to-estree is a utility package within the unified/syntax-tree ecosystem designed to transform a HTML Abstract Syntax Tree (hast) into an ECMAScript Abstract Syntax Tree (estree) with JSX extensions. This is particularly useful for embedding HTML content as JSX within JavaScript, such as in MDX. The current stable version is 3.1.3, with releases occurring regularly, often involving minor updates to dependencies or new options, indicating active maintenance. Key differentiators include its specific focus on the hast-to-estree transformation, robust handling of JSX, support for embedded MDX nodes, and its adherence to the unist specification, making it a reliable component in pipelines involving content transformation and compilation.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require('hast-util-to-estree')` in a CommonJS context after version 3.0.0, which is ESM-only.

fix Change your import statement to `import { toEstree } from 'hast-util-to-estree'` and ensure your Node.js project or file is configured for ES Modules.
```
ReferenceError: toEstree is not defined
```
cause Incorrectly importing `toEstree` using a default import or a misspelled named import.

fix Ensure you are using a named import: `import { toEstree } from 'hast-util-to-estree'`.
```
TypeError: toEstree is not a function
```
cause Potentially an incorrect default import being treated as a function, or a version mismatch where `toEstree` isn't properly exported.

fix Verify that you are using the correct named import: `import { toEstree } from 'hast-util-to-estree'`. Check your package version for any breaking changes related to exports.

Warnings

breaking Version 3.0.0 changed the minimum required Node.js version to 16. Older Node.js environments will encounter errors.
Fix: Upgrade your Node.js environment to version 16 or newer. Use `nvm` or `volta` for managing Node.js versions.
breaking Since version 3.0.0, the package is ESM-only and uses the `exports` field in `package.json`. This means `require()` statements will fail, and specific import paths might change.
Fix: Migrate your codebase to use ES Modules `import` syntax. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
breaking Version 3.0.0 updated its dependency on `@types/hast`. If your project explicitly depends on `@types/hast`, you may need to update your version as well to avoid type conflicts.
Fix: Update your `@types/hast` dependency to a compatible version (typically the latest stable release) in your `package.json`.
gotcha Comments are attached to neighboring nodes and as a `comments` array on the program node. Some compilers (e.g., Babel) might require `program.comments = undefined` for correct processing.
Fix: If experiencing issues with comment handling in down-stream compilers, explicitly remove the `comments` array from the program node: `estree.comments = undefined;`.
gotcha JSX frameworks often have different conventions for attributes (e.g., `class` vs `className`, `background-color` vs `backgroundColor`). This utility generates standard JSX, which might need further processing for specific frameworks.
Fix: Utilize options like `elementAttributeNameCase` or `stylePropertyNameCase` during transformation, or apply a post-processing step if your target framework requires specific attribute naming conventions.

Install

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

Imports

toEstree

wrong:

const { toEstree } = require('hast-util-to-estree')

correct:

import { toEstree } from 'hast-util-to-estree'

ESM-only since v3.0.0; CommonJS require() will fail.

defaultHandlers
wrong:
```
const { defaultHandlers } = require('hast-util-to-estree')
```
correct:
```
import { defaultHandlers } from 'hast-util-to-estree'
```
ESM-only since v3.0.0. Provides default transformation logic for various hast nodes.
ElementAttributeNameCase
```
import type { ElementAttributeNameCase } from 'hast-util-to-estree'
```
This is a TypeScript type import used for configuring the casing of element attribute names (e.g., 'react' for camelCase or 'html' for original casing).

Quickstart

Demonstrates transforming a raw HTML string into an ESTree (JavaScript AST) with JSX nodes, then rendering it to a JSX-compatible string using companion utilities.

import { read } from 'to-vfile'
import { fromHtml } from 'hast-util-from-html'
import { toEstree } from 'hast-util-to-estree'
import { toJs, jsx } from 'estree-util-to-js'

async function transformHtmlToJsx() {
  const htmlContent = `
<!doctype html>
<html lang=en>
<title>Example Page</title>
<h1>Hello, hast-util-to-estree!</h1>
<p style="color:red">This is a styled paragraph.</p>
</html>
  `

  // Convert HTML string to a hast tree
  const hast = fromHtml(htmlContent)

  // Convert hast tree to an estree (with JSX nodes)
  const estree = toEstree(hast)

  // Convert estree to a JavaScript string (with JSX syntax)
  const jsxOutput = toJs(estree, { handlers: jsx }).value

  console.log(jsxOutput)
}

transformHtmlToJsx().catch(console.error)

view raw JSON →