Unist Utility to Remove Nodes

4.0.0 · active · verified Sun Apr 19

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.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to import an ESM-only package using CommonJS `require()`.

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`).
```
TypeError: (0 , unist_util_remove_1.remove) is not a function
```
cause Incorrect CommonJS require usage, or trying to destructure a non-existent default export.

fix Ensure you are using the correct named import syntax for ESM: `import { remove } from 'unist-util-remove'`.
```
TypeError: Cannot read properties of undefined (reading 'children') at remove
```
cause Passing `null` or `undefined` as the `tree` argument to `remove`.

fix Always ensure the first argument passed to `remove` is a valid unist `Node` object, or handle `null`/`undefined` cases before calling the function.

Warnings

breaking unist-util-remove v4.0.0 and later require Node.js 16 or newer. Older Node.js versions are no longer supported.
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`).
breaking 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.
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'`.
breaking The `remove` function no longer returns the modified tree. It now returns `undefined`. The tree is always mutated in-place.
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.
breaking The `RemoveOptions` TypeScript type was removed in v4.0.0.
Fix: If you were explicitly using `RemoveOptions`, update your type annotations. The `Options` type is now the correct reference for configuration.
breaking 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.
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.
gotcha 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.
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.

Install

npm install unist-util-remove npm
yarn add unist-util-remove yarn
pnpm add unist-util-remove pnpm

Imports

remove
wrong:
```
const remove = require('unist-util-remove')
```
correct:
```
import { remove } from 'unist-util-remove'
```
Since v3.0.0, unist-util-remove is an ESM-only package. CommonJS require() will fail.
remove
wrong:
```
import remove from 'unist-util-remove'
```
correct:
```
import { remove } from 'unist-util-remove'
```
The package provides a named export for `remove`, not a default export.
Options
```
import type { Options } from 'unist-util-remove'
```
TypeScript type for configuration options.

Quickstart

Demonstrates importing `remove` and using it to mutate a unist tree by removing nodes matching a type, including an example of the `cascade` option.

import { u } from 'unist-builder';
import { remove } from 'unist-util-remove';

// Create a sample unist tree
const tree = u('root', [
  u('leaf', '1'),
  u('parent', [
    u('leaf', '2'),
    u('parent', [u('leaf', '3'), u('other', '4')]),
    u('parent', [u('leaf', '5')])
  ]),
  u('leaf', '6'),
  u('emptyParent', [])
]);

console.log('Original Tree:');
console.dir(tree, { depth: undefined });

// Remove all nodes of type `leaf`.
// Note: `remove` mutates the tree in-place and returns undefined since v4.0.0.
remove(tree, 'leaf');

console.log('\nTree after removing all `leaf` nodes:');
console.dir(tree, { depth: undefined });

// Example with `cascade: false` to keep parents if only children were removed
const anotherTree = u('root', [
  u('parent', [
    u('removableChild', 'a'),
    u('keepableChild', 'b')
  ])
]);

console.log('\nOriginal Tree for cascade example:');
console.dir(anotherTree, { depth: undefined });

remove(anotherTree, { cascade: false }, 'removableChild');

console.log('\nTree after removing `removableChild` with cascade: false:');
console.dir(anotherTree, { depth: undefined });

view raw JSON →