{"id":12300,"library":"unist-util-remove","title":"Unist Utility to Remove Nodes","description":"unist-util-remove is a utility package within the unified ecosystem designed to modify unist (Universal Syntax Tree) structures by removing nodes that pass a given test. Unlike `unist-util-filter`, this utility mutates the tree in-place, which can offer significant performance benefits on large documents. The current stable version is 4.0.0, which notably introduced a requirement for Node.js 16+, transitioned to being an ESM-only package, and altered the return type of the `remove` function from the modified tree to `undefined`. The package maintains compatibility with actively maintained Node.js versions and receives updates for bug fixes, performance improvements, and minor enhancements. Major version releases typically align with Node.js LTS updates or significant architectural shifts within the unified ecosystem, such as the move to ESM.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-remove","tags":["javascript","unist","unist-util","util","utility","ast","tree","node","cascade","typescript"],"install":[{"cmd":"npm install unist-util-remove","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-remove","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-remove","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v3.0.0, unist-util-remove is an ESM-only package. CommonJS require() will fail.","wrong":"const remove = require('unist-util-remove')","symbol":"remove","correct":"import { remove } from 'unist-util-remove'"},{"note":"The package provides a named export for `remove`, not a default export.","wrong":"import remove from 'unist-util-remove'","symbol":"remove","correct":"import { remove } from 'unist-util-remove'"},{"note":"TypeScript type for configuration options.","symbol":"Options","correct":"import type { Options } from 'unist-util-remove'"}],"quickstart":{"code":"import { u } from 'unist-builder';\nimport { remove } from 'unist-util-remove';\n\n// Create a sample unist tree\nconst tree = u('root', [\n  u('leaf', '1'),\n  u('parent', [\n    u('leaf', '2'),\n    u('parent', [u('leaf', '3'), u('other', '4')]),\n    u('parent', [u('leaf', '5')])\n  ]),\n  u('leaf', '6'),\n  u('emptyParent', [])\n]);\n\nconsole.log('Original Tree:');\nconsole.dir(tree, { depth: undefined });\n\n// Remove all nodes of type `leaf`.\n// Note: `remove` mutates the tree in-place and returns undefined since v4.0.0.\nremove(tree, 'leaf');\n\nconsole.log('\\nTree after removing all `leaf` nodes:');\nconsole.dir(tree, { depth: undefined });\n\n// Example with `cascade: false` to keep parents if only children were removed\nconst anotherTree = u('root', [\n  u('parent', [\n    u('removableChild', 'a'),\n    u('keepableChild', 'b')\n  ])\n]);\n\nconsole.log('\\nOriginal Tree for cascade example:');\nconsole.dir(anotherTree, { depth: undefined });\n\nremove(anotherTree, { cascade: false }, 'removableChild');\n\nconsole.log('\\nTree after removing `removableChild` with cascade: false:');\nconsole.dir(anotherTree, { depth: undefined });","lang":"typescript","description":"Demonstrates importing `remove` and using it to mutate a unist tree by removing nodes matching a type, including an example of the `cascade` option."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or higher, or pin to an older major version of unist-util-remove (e.g., `unist-util-remove@^3`).","message":"unist-util-remove v4.0.0 and later require Node.js 16 or newer. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Migrate your project to ESM by setting `\"type\": \"module\"` in your `package.json` or by using dynamic `import()` for this package. Use `import { remove } from 'unist-util-remove'`.","message":"As of v3.0.0, unist-util-remove is an ECMAScript Module (ESM) only package. Attempting to `require()` it in a CommonJS context will result in an error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove any code that expects `remove` to return the tree. The `tree` object passed to `remove` is modified directly. If you need to test if the root `tree` itself should be removed, do so explicitly with `unist-util-is` before calling `remove` on its children.","message":"The `remove` function no longer returns the modified tree. It now returns `undefined`. The tree is always mutated in-place.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"If you were explicitly using `RemoveOptions`, update your type annotations. The `Options` type is now the correct reference for configuration.","message":"The `RemoveOptions` TypeScript type was removed in v4.0.0.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your project's types are updated and compatible with `unist-util-is@^4`. If you use `unist-util-is` directly, update it to the latest version.","message":"The `unist-util-is` dependency was updated in v2.0.0, which could be a breaking change for TypeScript users if `unist-util-is` itself was used indirectly in a way that exposed its internal types.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Pass `{ cascade: false }` as the second argument to `remove` if you want to prevent parents from being removed when their children are filtered out.","message":"The `cascade` option (default `true`) will remove parent nodes if all their children are removed. If you wish to keep parent nodes even if they become childless, set `cascade` to `false` in the options.","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":"Change your import statement to `import { remove } from 'unist-util-remove'` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to import an ESM-only package using CommonJS `require()`.","error":"ERR_REQUIRE_ESM"},{"fix":"Ensure you are using the correct named import syntax for ESM: `import { remove } from 'unist-util-remove'`.","cause":"Incorrect CommonJS require usage, or trying to destructure a non-existent default export.","error":"TypeError: (0 , unist_util_remove_1.remove) is not a function"},{"fix":"Always ensure the first argument passed to `remove` is a valid unist `Node` object, or handle `null`/`undefined` cases before calling the function.","cause":"Passing `null` or `undefined` as the `tree` argument to `remove`.","error":"TypeError: Cannot read properties of undefined (reading 'children') at remove"}],"ecosystem":"npm"}