{"id":13288,"library":"hast-util-sanitize","title":"hast-util-sanitize","description":"hast-util-sanitize is a JavaScript utility designed to make HAST (Hypertext Abstract Syntax Tree) nodes safe by removing potentially dangerous user-generated content, primarily to prevent Cross-Site Scripting (XSS) vulnerabilities. Currently at version 5.0.2, the package is actively maintained as part of the unified ecosystem, with a steady release cadence addressing features and breaking changes. It provides a robust, extensible schema, defaulting to GitHub's sanitation rules, allowing developers to customize allowed elements, attributes, and attribute values. This makes it a crucial tool for applications handling untrusted HTML input, either directly or through higher-level wrappers like rehype-sanitize. Its focus on direct HAST manipulation allows for fine-grained control over the sanitization process.","status":"active","version":"5.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-sanitize","tags":["javascript","clean","hast-util","hast","html","safe","sanitize","utility","util","typescript"],"install":[{"cmd":"npm install hast-util-sanitize","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-sanitize","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-sanitize","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package is ESM-only since v5.0.0. CommonJS `require` will fail.","wrong":"const sanitize = require('hast-util-sanitize').sanitize","symbol":"sanitize","correct":"import { sanitize } from 'hast-util-sanitize'"},{"note":"The package is ESM-only since v5.0.0. CommonJS `require` will fail.","wrong":"const defaultSchema = require('hast-util-sanitize').defaultSchema","symbol":"defaultSchema","correct":"import { defaultSchema } from 'hast-util-sanitize'"},{"note":"Importing types is standard TypeScript practice. The `type` keyword is recommended for clarity.","symbol":"Schema (type)","correct":"import type { Schema } from 'hast-util-sanitize'"}],"quickstart":{"code":"import {h} from 'hastscript';\nimport {sanitize} from 'hast-util-sanitize';\nimport {toHtml} from 'hast-util-to-html';\nimport {u} from 'unist-builder';\n\nconst unsafe = h('div', {onmouseover: 'alert(\"alpha\")'}, [\n  h(\n    'a',\n    {href: 'jAva script:alert(\"bravo\")', onclick: 'alert(\"charlie\")'},\n    'delta'\n  ),\n  u('text', '\\n'),\n  h('script', 'alert(\"charlie\")'),\n  u('text', '\\n'),\n  h('img', {src: 'x', onerror: 'alert(\"delta\")'}),\n  u('text', '\\n'),\n  h('iframe', {src: 'javascript:alert(\"echo\")'}),\n  u('text', '\\n'),\n  h('math', h('mi', {'xlink:href': 'data:x,<script>alert(\"foxtrot\")<\\/script>'}))\n]);\n\n// Sanitize the unsafe HAST tree\nconst safe = sanitize(unsafe);\n\nconsole.log('Unsafe HTML:');\nconsole.log(toHtml(unsafe));\nconsole.log('\\nSafe HTML:');\nconsole.log(toHtml(safe));","lang":"javascript","description":"Demonstrates sanitizing a HAST tree containing various XSS attack vectors using the default GitHub-style schema, showing the transformation from unsafe to safe HTML."},"warnings":[{"fix":"Migrate your project to use ES modules (`import`/`export`) or ensure you are in an environment that transpiles ESM correctly. Update your Node.js version to 16+.","message":"Version 5.0.0 changed the package to be ESM-only and requires Node.js 16 or higher. Direct CommonJS `require()` statements will no longer work.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always use the public API paths, typically `hast-util-sanitize` for named exports, and avoid relying on internal file structures.","message":"With version 5.0.0, the package now uses the `exports` field in `package.json`. This means direct imports of internal paths (e.g., `hast-util-sanitize/lib/some-internal-module`) are no longer supported and will lead to errors.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your TypeScript configuration is compatible, and review any custom type declarations that might now conflict with the official types.","message":"Version 3.0.0 introduced TypeScript types. While beneficial, this was a potentially breaking change if your project or its dependents relied on implicit type behavior or conflicting type definitions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If `rel` or `target` attributes are essential for specific elements (e.g., `a` tags), you must explicitly add them back to your custom schema by extending `defaultSchema`.","message":"In version 5.0.1, the default schema was updated to remove `rel` and `target` attributes from certain elements, which might affect link behavior if you were implicitly relying on these attributes being preserved by default.","severity":"gotcha","affected_versions":">=5.0.1"},{"fix":"Thoroughly review any modifications made to `defaultSchema` or entirely custom schemas to ensure they do not permit dangerous elements, attributes, or protocols.","message":"While `hast-util-sanitize` provides robust XSS protection with its default (GitHub-like) schema, custom schemas can reintroduce vulnerabilities if not carefully constructed. Always audit your custom schema against known attack vectors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Refactor your code to use `import { sanitize } from 'hast-util-sanitize';` in an ES module context (e.g., by setting `\"type\": \"module\"` in your `package.json` or using `.mjs` files). If stuck in CommonJS, consider dynamic import: `const { sanitize } = await import('hast-util-sanitize');`.","cause":"Attempting to `require()` hast-util-sanitize in a CommonJS module or environment when the package is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/hast-util-sanitize/index.js from /path/to/your/file.js not supported. hast-util-sanitize is an ES module file as it is a .js file whose nearest parent package.json contains \"type\": \"module\" and which has no 'exports' field. Instead, change the require of index.js in /path/to/your/file.js to a dynamic import() which is available in all CommonJS modules."},{"fix":"Always import symbols directly from the main package entry point: `import { someExport } from 'hast-util-sanitize';`. Do not rely on deep imports into `lib/` or other internal directories.","cause":"Attempting to import from an internal, non-public path within the package, which is disallowed due to the `exports` field in `package.json` since v5.0.0.","error":"Cannot find module 'hast-util-sanitize/lib/some-internal-api' or similar path."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}