{"id":11013,"library":"hast-util-raw","title":"HAST Utility to Reparse Raw HTML Nodes","description":"This package, `hast-util-raw`, provides a utility for re-parsing HAST (Hypertext Abstract Syntax Tree) documents, specifically targeting 'raw' nodes which contain unprocessed HTML strings. Leveraging the `parse5` HTML parser, it transforms these raw HTML strings into a proper HAST syntax tree, crucial for applications that require a fully-formed, inspectable, and transformable tree rather than mere HTML serialization. This is particularly vital when working with markdown that includes embedded HTML (often enabled via `allowDangerousHtml: true` in converters like `mdast-util-to-hast`), where the initial conversion preserves the HTML as raw strings. The utility ensures that all original data and positional information from the source HTML are meticulously retained during the reparsing process. Currently in stable version 9.1.0, the library maintains an active release cadence, frequently delivering bug fixes and minor features, with major versions introducing breaking changes, often related to Node.js version support or API enhancements. Its core differentiator lies in enabling robust processing of mixed markdown/HTML content by integrating raw HTML into the HAST ecosystem as manipulable nodes, supporting various output formats beyond simple HTML, such as React or MDX.","status":"active","version":"9.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-raw","tags":["javascript","hast-util","hast","html","unist","utility","util","parse","raw","typescript"],"install":[{"cmd":"npm install hast-util-raw","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-raw","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-raw","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core HTML parser used to transform raw HTML strings into HAST nodes.","package":"parse5"}],"imports":[{"note":"The package is ESM-only since v9.0.0. Use `import` syntax.","wrong":"const raw = require('hast-util-raw')","symbol":"raw","correct":"import { raw } from 'hast-util-raw'"},{"note":"Type import for configuration options such as `file`, `passThrough`, and `tagfilter`.","symbol":"Options","correct":"import type { Options } from 'hast-util-raw'"}],"quickstart":{"code":"import { h } from 'hastscript';\nimport { raw } from 'hast-util-raw';\n\n// A HAST tree typically containing a 'raw' node.\n// In real-world scenarios, this 'treeWithRaw' often comes from a markdown-to-hast\n// converter like `mdast-util-to-hast` with `allowDangerousHtml: true`.\nconst treeWithRaw = {\n  type: 'root',\n  children: [\n    h('header', [h('h1', 'Document Title')]),\n    // This 'raw' node contains unparsed HTML string.\n    // hast-util-raw will parse this string into proper HAST elements.\n    {\n      type: 'raw',\n      value: '<p>This is <em>some</em> <strong>raw</strong> HTML content.</p><p>Another paragraph.</p>'\n    },\n    h('footer', [h('p', 'End of document.')])\n  ]\n};\n\n// The `raw` function processes the tree, converting 'raw' nodes to full HAST elements.\nconst reformattedTree = raw(treeWithRaw);\n\nconsole.log(JSON.stringify(reformattedTree, null, 2));\n","lang":"typescript","description":"Demonstrates processing a HAST tree containing a `type: 'raw'` node with an HTML string, converting it into a fully structured HAST tree with parsed elements."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or later.","message":"Version 9.0.0 introduced a breaking change requiring Node.js 16 or higher. Earlier versions supported Node.js 14.14+ (v8.0.0) or Node.js 12 (pre-v8.0.0).","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Ensure your project uses native ES Modules. Update import paths to use the documented public API. If you need the `Raw` type, import it from `mdast-util-to-hast`.","message":"Since v9.0.0, the package is ESM-only and utilizes the `exports` field in `package.json`. Direct imports of internal/private APIs are no longer supported. The `Raw` type was also removed and should now be imported from `mdast-util-to-hast` if needed.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Update calls to `raw(tree, { file })` instead of `raw(tree, file)`.","message":"In version 8.0.0, the `file` parameter, if previously passed directly to the `raw` function, was changed to be an option within an object: `{ file: file }`.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Always sanitize untrusted input before passing it to `hast-util-raw` or related utilities that enable dangerous HTML. Avoid `allowDangerousHtml: true` or `passThrough` with untrusted sources.","message":"When `allowDangerousHtml: true` is used with related utilities (like `mdast-util-to-hast`) or when `passThrough` options are configured, `hast-util-raw` can process untrusted HTML. This can lead to cross-site scripting (XSS) vulnerabilities if the input is not sanitized or trusted.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If specific tags are unexpectedly filtered, review the GFM tagfilter rules and consider setting `tagfilter: false` in the options if you explicitly need to process these tags and trust their content.","message":"The `tagfilter` option, added in v9.1.0, disallows irregular tags in `raw` nodes according to GFM tagfilter rules. If you rely on specific 'irregular' tags (e.g., `iframe`, `style`, `textarea`) being processed as regular elements, this option might filter them out.","severity":"gotcha","affected_versions":">=9.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { raw } = require('hast-util-raw')` to `import { raw } from 'hast-util-raw'`.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module context for `hast-util-raw`.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Ensure SVG element tags are consistently lowercase. This issue was specifically addressed in version 9.0.3, so upgrading may resolve it.","cause":"Parsing issues with non-lowercase SVG element tags, which could lead to incorrect HTML structure.","error":"SVG elements (e.g., `<svg><path/></svg>`) are not closing correctly or are malformed in the output."},{"fix":"Ensure that the HTML content within `raw` nodes is well-formed. This issue received a fix for certain cases in version 9.0.4, so upgrading might help, but manual correction of malformed input is often required.","cause":"The `raw` input contained unfinished or severely malformed HTML that `parse5` could not recover from.","error":"Error: parse5 could not complete parsing due to malformed HTML"}],"ecosystem":"npm"}