{"id":13291,"library":"hast-util-truncate","title":"HAST Tree Truncation Utility","description":"hast-util-truncate is a focused utility within the unified (unist/hast/mdast) ecosystem, designed to truncate a HAST (HTML Abstract Syntax Tree) to a specified number of characters while meticulously preserving its underlying structure. The package, currently stable at version 2.0.0, follows the syntax-tree's measured release cadence, with major versions often introducing changes related to Node.js environment requirements or shifts in JavaScript module standards. Its key differentiator lies in operating directly on the AST, enabling intelligent truncation that respects HTML semantics and avoids breaking tags, unlike naive string-based approaches. It offers configurable options for the truncation size, the ellipsis character, and a `maxCharacterStrip` mechanism to ensure word breaks occur gracefully, preventing awkward partial words at the truncation point. This makes it ideal for generating accurate excerpts, summaries, or SEO descriptions from rich HTML content for applications like blogs, content management systems, or search result snippets.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-truncate","tags":["javascript","unist","hast","hast-util","util","utility","html","truncate","excerpt","typescript"],"install":[{"cmd":"npm install hast-util-truncate","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-truncate","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-truncate","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only since v2.0.0, requiring Node.js 16+.","wrong":"const { truncate } = require('hast-util-truncate')","symbol":"truncate","correct":"import { truncate } from 'hast-util-truncate'"},{"note":"Type import for configuration options.","symbol":"Options","correct":"import type { Options } from 'hast-util-truncate'"},{"note":"There is no default export; all exports are named.","wrong":"import hastUtilTruncate from 'hast-util-truncate'","symbol":"hast-util-truncate as a whole","correct":"import * as hastUtilTruncate from 'hast-util-truncate'"}],"quickstart":{"code":"import { h } from 'hastscript';\nimport { truncate } from 'hast-util-truncate';\n\nconst tree = h('p', [\n  'Lorem ipsum dolor sit amet, ',\n  h('em', 'consectetur'),\n  'adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud'\n]);\n\n// Truncate to a default size (140 chars) with a custom ellipsis\nconst truncatedTree = truncate(tree, { ellipsis: '…' });\n\nconsole.log(JSON.stringify(truncatedTree, null, 2));","lang":"typescript","description":"This example demonstrates how to import and use the `truncate` function to process a HAST paragraph node, limiting its text content to the default character count while appending a custom ellipsis."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or a later LTS release.","message":"hast-util-truncate now requires Node.js 16 or higher due to updated build targets and features.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Migrate your project to use ESM `import` statements. If running in Node.js, ensure `type: 'module'` is set in your `package.json` or use `.mjs` file extensions.","message":"The package is now ESM-only (ECMAScript Modules). CommonJS `require()` is no longer supported for importing `hast-util-truncate`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always import symbols directly from the main package entry point: `import { symbol } from 'hast-util-truncate'`.","message":"The package now uses the `exports` field in `package.json`. Direct imports to internal paths (e.g., `hast-util-truncate/lib/*`) are no longer supported and will lead to import errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update `@types/hast` to its latest compatible version (e.g., `npm install @types/hast@latest`).","message":"The `@types/hast` dependency needs to be updated when migrating to `hast-util-truncate` v2.0.0 to ensure type compatibility with internal utility updates.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { truncate } = require('hast-util-truncate')` to `import { truncate } from 'hast-util-truncate'`. Ensure your project runs in an ESM context (e.g., Node.js 16+ with `\"type\": \"module\"` in `package.json`).","cause":"Attempting to import hast-util-truncate (an ESM-only package) using CommonJS `require()`.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... hast-util-truncate.js not supported."},{"fix":"Ensure you are using `import { truncate } from 'hast-util-truncate'` as there is no default export. Also, verify Node.js version and ESM context.","cause":"Incorrect import statement or attempting to access a default export when only named exports exist.","error":"TypeError: truncate is not a function"},{"fix":"For Node.js projects, add `\"type\": \"module\"` to your `package.json` or rename your file to `.mjs`. Ensure your Node.js version is 16 or newer.","cause":"Using ESM `import` syntax in a file that is treated as a CommonJS module (e.g., `.js` file without `\"type\": \"module\"` in `package.json` or in an older Node.js environment).","error":"SyntaxError: Cannot use import statement outside a module"}],"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}