{"id":12296,"library":"unist-util-modify-children","title":"Unist Utility to Modify Children","description":"unist-util-modify-children is a utility within the unist (Universal Syntax Tree) ecosystem designed to create a reusable function for directly modifying the children of a parent node in an AST. The current stable version is 4.0.0, which notably moved to ESM-only and requires Node.js 16+. Releases generally follow semantic versioning, with major versions introducing breaking changes like environment requirements or module system shifts. A key differentiator and strong recommendation from its maintainers is that most users should probably use `unist-util-visit` instead, as `unist-util-modify-children` is intended for very specific, advanced scenarios where direct, in-place manipulation of child arrays is explicitly required and other traversal utilities are insufficient.","status":"maintenance","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/unist-util-modify-children","tags":["javascript","unist","unist-util","util","utility","tree","ast","modify","children","typescript"],"install":[{"cmd":"npm install unist-util-modify-children","lang":"bash","label":"npm"},{"cmd":"yarn add unist-util-modify-children","lang":"bash","label":"yarn"},{"cmd":"pnpm add unist-util-modify-children","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides TypeScript type definitions for Unist nodes, essential for type-safe usage and was updated as a breaking change in v4.","package":"@types/unist","optional":false}],"imports":[{"note":"The package is ESM-only since v3.0.0 and requires Node.js 16+ since v4.0.0, making CommonJS `require` calls invalid.","wrong":"const { modifyChildren } = require('unist-util-modify-children')","symbol":"modifyChildren","correct":"import { modifyChildren } from 'unist-util-modify-children'"},{"note":"TypeScript type for the callback function passed to `modifyChildren`. Use `import type` for type-only imports to avoid bundling issues.","symbol":"Modifier","correct":"import type { Modifier } from 'unist-util-modify-children'"},{"note":"TypeScript type for the function returned by `modifyChildren`. Use `import type` for type-only imports.","symbol":"Modify","correct":"import type { Modify } from 'unist-util-modify-children'"}],"quickstart":{"code":"import u from 'unist-builder';\nimport { modifyChildren } from 'unist-util-modify-children';\n\n// Create a sample Unist tree\nconst tree = u('root', [\n  u('leaf', '1'),\n  u('parent', [u('leaf', '2')]),\n  u('leaf', '3')\n]);\n\n// Define a modifier function that replaces a 'parent' node with a 'subtree' node\nconst modify = modifyChildren(function (node, index, parent) {\n  if (node.type === 'parent') {\n    // Replace the 'parent' node with a new 'subtree' node containing its children\n    parent.children.splice(index, 1, { type: 'subtree', children: node.children });\n    // Return the new index to continue iteration from after the splice\n    return index + 1;\n  }\n});\n\n// Apply the modification to the tree\nmodify(tree);\n\n// Output the modified tree structure\nconsole.dir(tree, { depth: undefined });\n\n/*\nYields:\n{\n  type: 'root',\n  children: [\n    { type: 'leaf', value: '1' },\n    { type: 'subtree', children: [{ type: 'leaf', value: '2' }] },\n    { type: 'leaf', value: '3' }\n  ]\n}\n*/","lang":"typescript","description":"This quickstart demonstrates how to initialize `unist-util-modify-children` with a custom modifier function and apply it to a Unist tree to replace a specific type of parent node with a new structure."},"warnings":[{"fix":"Consider `import { visit } from 'unist-util-visit'` for general tree operations.","message":"The maintainers strongly recommend using `unist-util-visit` for most tree traversal and modification tasks. `unist-util-modify-children` is primarily for very specific cases requiring direct child array manipulation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 16 or newer. Use an older package version (e.g., `unist-util-modify-children@3`) if you must support older Node.js.","message":"Version 4.0.0 changed to require Node.js 16 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update your import statements to use ES modules syntax (e.g., `import { modifyChildren } from 'unist-util-modify-children'`). Ensure your project is configured for ESM.","message":"The package transitioned to ESM-only starting from version 3.0.0. CommonJS `require()` statements will no longer work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update your project's `@types/unist` dependency to the latest compatible version or match the version used by `unist-util-modify-children`.","message":"Version 4.0.0 updated its internal `@types/unist` dependency. If your project or its dependencies rely on specific `unist` types, you may need to update your own `@types/unist` version to avoid type conflicts.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Review your TypeScript configuration and code to ensure compatibility with the official types. Update your `tsconfig.json` if necessary.","message":"Version 2.0.0 introduced TypeScript types. If you or your dependents were using TypeScript and relying on implicit typings or custom declarations, this change could potentially break your build due to new type strictness or conflicting declarations.","severity":"breaking","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 { modifyChildren } = require('unist-util-modify-children')` to `import { modifyChildren } from 'unist-util-modify-children'`. Ensure your project's `package.json` has `\"type\": \"module\"` or uses `.mjs` file extensions for ESM files.","cause":"Attempting to import `unist-util-modify-children` using CommonJS `require()` syntax in a Node.js environment.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/unist-util-modify-children/index.js from ... not supported."},{"fix":"Verify the import statement is `import { modifyChildren } from 'unist-util-modify-children'` and that your environment supports ESM. Also ensure the package is correctly installed.","cause":"This typically occurs when trying to call `modifyChildren` after an incorrect import (e.g., attempting a default import or a malformed named import) or if `require` was used and failed silently.","error":"TypeError: modifyChildren is not a function"},{"fix":"For TypeScript types, ensure you use `import type { Modifier } from 'unist-util-modify-children'` to explicitly import it as a type, especially in modern TypeScript environments. If using an older TypeScript version or Babel, ensure correct transpilation settings.","cause":"Attempting to import a TypeScript type as a value export, or incorrectly importing a type in an environment that doesn't support `import type`.","error":"SyntaxError: Named export 'Modifier' not found. The requested module 'unist-util-modify-children' does not provide an export named 'Modifier'."}],"ecosystem":"npm"}