{"id":11286,"library":"mdast-util-find-and-replace","title":"mdast Find and Replace Utility","description":"mdast-util-find-and-replace is a utility within the unifiedjs ecosystem designed to find patterns (strings or regular expressions) within the text nodes of an mdast (Markdown Abstract Syntax Tree) and replace them with new mdast nodes. The current stable version is 3.0.2. It typically receives updates for bug fixes and minor enhancements, with major versions introducing breaking changes less frequently, as seen with the transition to v3.0.0. Key differentiators include its tight integration with the mdast specification, its ability to produce complex node structures as replacements, and its focus on efficient, preorder traversal. It's particularly useful for transforming markdown content programmatically, such as converting specific text patterns into links, mentions, or other AST elements.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-find-and-replace","tags":["javascript","find","markdown","mdast-util","mdast","unist","utility","util","replace","typescript"],"install":[{"cmd":"npm install mdast-util-find-and-replace","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-find-and-replace","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-find-and-replace","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"mdast-util-find-and-replace is ESM-only since version 3.0.0, requiring Node.js 16+.","wrong":"const { findAndReplace } = require('mdast-util-find-and-replace')","symbol":"findAndReplace","correct":"import { findAndReplace } from 'mdast-util-find-and-replace'"},{"note":"TypeScript type for a single find-and-replace pair.","symbol":"FindAndReplaceTuple","correct":"import type { FindAndReplaceTuple } from 'mdast-util-find-and-replace'"},{"note":"TypeScript type for a function that returns replacement nodes.","symbol":"ReplaceFunction","correct":"import type { ReplaceFunction } from 'mdast-util-find-and-replace'"}],"quickstart":{"code":"import {findAndReplace} from 'mdast-util-find-and-replace';\nimport {u} from 'unist-builder';\nimport {inspect} from 'unist-util-inspect';\n\nconst tree = u('paragraph', [\n  u('text', 'Some '),\n  u('emphasis', [u('text', 'emphasis')]),\n  u('text', ' and '),\n  u('strong', [u('text', 'importance')]),\n  u('text', '.')\n]);\n\nfindAndReplace(tree, [\n  [/and/gi, 'or'],\n  [/emphasis/gi, 'em'],\n  [/importance/gi, 'strong'],\n  [\n    /Some/g,\n    function ($0) {\n      return u('link', {url: '//example.com#' + $0}, [u('text', $0)]);\n    }\n  ]\n]);\n\nconsole.log(inspect(tree));","lang":"typescript","description":"This example demonstrates how to import `findAndReplace`, construct an mdast tree using `unist-builder`, and then apply multiple find-and-replace operations, including string, regex, and function-based replacements, before inspecting the modified tree."},"warnings":[{"fix":"Update your `list` argument: `find, replace` becomes `[find, replace]`, and `{find: replace, …}` becomes `[[find, replace], …]`.","message":"Version 3.0.0 changed the API to accept find-and-replace pairs only as `[find, replace]` tuples or an `Array<[find, replace]>`. The old `{find: replace}` object syntax is no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your Node.js environment is at least version 16.0.0. Update your runtime if necessary.","message":"Version 3.0.0 requires Node.js 16 or higher due to a shift to modern JavaScript features and module resolution.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Remove any code that expects a return value from `findAndReplace`. The `tree` object passed as the first argument is modified directly.","message":"Starting with version 3.0.0, `findAndReplace` now returns `undefined` instead of the modified tree. The function modifies the tree in place.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Migrate your project to use ES modules (`import`/`export`) or use dynamic `import()` if you must `require` ESM packages from CommonJS. Alternatively, stick to `mdast-util-find-and-replace` v2 for CommonJS compatibility.","message":"The package is ESM-only since v3.0.0, which means it can only be `import`ed and cannot be `require`d in CommonJS modules. This might cause issues in older Node.js projects or mixed environments.","severity":"gotcha","affected_versions":">=3.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 { findAndReplace } = require('mdast-util-find-and-replace')` to `import { findAndReplace } from 'mdast-util-find-and-replace'` and ensure your project is configured for ES modules (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to `require()` `mdast-util-find-and-replace` in a CommonJS module after upgrading to v3.x.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module [path] from [path] not supported. Instead change the require of index.js to a dynamic import() which is also supported."},{"fix":"Convert your replacement object to an array of tuples: `[[/pattern/g, 'replacement'], ['string', function(){...}]]`.","cause":"Using the old `{ find: replace }` object format for replacement rules after upgrading to v3.x.","error":"TypeError: `list` must be a list of tuples or a tuple. Got `object`."}],"ecosystem":"npm"}