{"id":15117,"library":"hast-util-whitespace","title":"hast-util-whitespace: Inter-Element Whitespace Check","description":"This package provides a highly specialized utility within the HAST (HTML Abstract Syntax Tree) ecosystem, designed to determine if a given node or string constitutes \"inter-element whitespace\" as defined by HTML specifications. Currently at stable version 3.0.0, the package adheres to the unified collective's release cadence, which typically involves major version bumps for breaking changes and Node.js compatibility updates. Its key differentiator is its precise adherence to HTML's definition of inter-element whitespace, making it crucial for tools that need to correctly manipulate or process HTML ASTs while preserving semantic meaning. It is ESM-only and ships with TypeScript types.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/hast-util-whitespace","tags":["javascript","unist","hast","hast-util","util","utility","html","inter","element","typescript"],"install":[{"cmd":"npm install hast-util-whitespace","lang":"bash","label":"npm"},{"cmd":"yarn add hast-util-whitespace","lang":"bash","label":"yarn"},{"cmd":"pnpm add hast-util-whitespace","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is ESM-only since v2 and has no default export. For v3, Node.js 16+ is required for full compatibility with its `exports` map.","wrong":"const { whitespace } = require('hast-util-whitespace')","symbol":"whitespace","correct":"import { whitespace } from 'hast-util-whitespace'"}],"quickstart":{"code":"import { whitespace } from 'hast-util-whitespace';\nimport type { Text, Element } from 'hast';\n\n// Example 1: An element node is not inter-element whitespace\nconst elementNode: Element = {\n  type: 'element',\n  tagName: 'div',\n  properties: {},\n  children: []\n};\nconsole.log('Is elementNode whitespace?', whitespace(elementNode)); // => false\n\n// Example 2: A text node containing only inter-element whitespace characters\nconst whitespaceTextNode: Text = {\n  type: 'text',\n  value: '\\t  \\n'\n};\nconsole.log('Is whitespaceTextNode whitespace?', whitespace(whitespaceTextNode)); // => true\n\n// Example 3: A text node containing both whitespace and non-whitespace\nconst mixedTextNode: Text = {\n  type: 'text',\n  value: '  text\\f'\n};\nconsole.log('Is mixedTextNode whitespace?', whitespace(mixedTextNode)); // => false\n\n// Example 4: A string containing only inter-element whitespace characters\nconsole.log('Is \"\\t  \\n\" whitespace?', whitespace('\\t  \\n')); // => true\n\n// Example 5: A string containing non-whitespace characters\nconsole.log('Is \"hello\" whitespace?', whitespace('hello')); // => false","lang":"typescript","description":"Demonstrates how to use the `whitespace` function to identify inter-element whitespace in both HAST text nodes and raw strings, showcasing various input types."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. If this is not possible, you must remain on `hast-util-whitespace@^2`.","message":"Version 3.0.0 of `hast-util-whitespace` requires Node.js version 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure you are importing only the public `whitespace` function. Avoid direct imports from subpaths or undocumented files within the package.","message":"Version 3.0.0 changed to use the `exports` field in `package.json`, which implies that internal/private APIs should not be accessed directly. Only documented public exports should be used.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure that the `thing` argument passed to `whitespace` is either a string or a `hast` Node (typically a `Text` node). Review any code that might pass `null`, `undefined`, or other non-string/non-node values.","message":"As of version 3.0.0, the `whitespace` function strictly validates its input, only accepting valid HAST `Node` objects (specifically `Text` nodes) or strings. Passing other types will result in a `TypeError`.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Refactor your codebase to use ECMAScript Modules (ESM) `import` statements. If your project is strictly CommonJS, you must remain on `hast-util-whitespace@^1`.","message":"Version 2.0.0 transitioned to being an ESM-only package. It no longer supports CommonJS `require()` syntax.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Familiarize yourself with the HTML specification's definition of 'inter-element whitespace' to ensure this utility aligns with your intended use case. For general whitespace checks, you might need custom logic or other utilities.","message":"This utility is highly niche, specifically checking for 'inter-element whitespace' as defined by HTML specifications, not general whitespace. Misunderstanding this specific definition can lead to unexpected results when trying to identify all whitespace in an HTML tree.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ESM by setting `\"type\": \"module\"` in your `package.json` or by using `.mjs` file extensions. Also, make sure your Node.js version meets the package requirements (16+ for v3).","cause":"Trying to import an ESM-only TypeScript package directly in a CommonJS context or an incorrectly configured Node.js environment.","error":"TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension \".ts\" for .../hast-util-whitespace/index.ts"},{"fix":"Switch to using `import` statements for `hast-util-whitespace`: `import { whitespace } from 'hast-util-whitespace';`. Ensure your project supports ESM.","cause":"Attempting to use `require()` to import `hast-util-whitespace`, which is an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../hast-util-whitespace/index.js from ... not supported."},{"fix":"Verify that the value you are passing to `whitespace` is either a string or a HAST `Text` node. Version 3.0.0 introduced stricter validation.","cause":"An invalid type (e.g., `null`, `undefined`, a number, or an element node that isn't a `Text` node) was passed to the `whitespace` function.","error":"TypeError: The 'thing' argument must be a string or a hast Node"},{"fix":"Ensure you are running Node.js 16+ for `hast-util-whitespace@3`. Also, confirm that you are using the correct named import `{ whitespace }` as there is no default export.","cause":"This error can occur if you're using an older Node.js version that doesn't fully support the `exports` field in `package.json` correctly or if you're trying to import a non-existent named export.","error":"SyntaxError: Named export 'whitespace' not found. The requested module 'hast-util-whitespace' does not provide an export named 'whitespace'"}],"ecosystem":"npm"}