hast-util-find-and-replace

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to import `hast-util-find-and-replace` using `require()` syntax in a CommonJS context, but the package is ESM-only.
  fix Convert your consuming file or project to use ES modules by setting `"type": "module"` in `package.json` or by using `.mjs` file extensions, and update `require()` calls to `import` statements.

• TypeError: (0 , _hast_util_find_and_replace__WEBPACK_IMPORTED_MODULE_0__.findAndReplace) is not a function

  cause This error typically indicates an incorrect import statement, where `findAndReplace` is being treated as a default import when it is a named export.
  fix Ensure you are using a named import: `import { findAndReplace } from 'hast-util-find-and-replace'`.

• TypeError: The 'list' argument must be a tuple or a list of tuples

  cause In `hast-util-find-and-replace` v5.x, the `list` argument for `findAndReplace` must be an array of `[find, replace]` tuples or a single `[find, replace]` tuple. Passing an object is deprecated and no longer supported.
  fix Refactor the `list` argument. Instead of `{ 'pattern': 'replacement' }`, use `[['pattern', 'replacement']]` or `['pattern', 'replacement']`.

Warnings

• breaking The package transitioned to ESM-only and requires Node.js 16 or newer for version 5.x. Older Node.js versions or CommonJS environments are not supported.
  Fix: Ensure your project is configured for ESM (e.g., `type: "module"` in `package.json` or `.mjs` file extension) and running Node.js 16 or newer. Update `require()` statements to `import` statements.
• breaking The API for `findAndReplace` changed to accept only a tuple `[Find, Replace]` or a list of tuples `[[Find, Replace], ...]`. Directly passing an object for `list` is no longer supported.
  Fix: Rewrite the `list` argument from an object structure (e.g., `{ 'foo': 'bar' }`) to an array of tuples (e.g., `[['foo', 'bar']]`) or a single tuple `['foo', 'bar']`.
• breaking The `findAndReplace` function now yields `undefined` (returns nothing). It mutates the provided `tree` node directly. If you need to keep a reference to the modified tree, you must pass the original tree object and expect it to be modified in place.
  Fix: Retain a reference to the `tree` object passed to `findAndReplace` as it is modified in place; do not expect a return value.
• gotcha The utility only finds patterns within `Text` nodes and processes complete matches. It does not handle partial matches that span across multiple HAST nodes (e.g., a word broken by an HTML tag).
  Fix: Structure your HAST tree such that text to be replaced is contained entirely within individual `Text` nodes. For multi-node replacements, custom traversal and manipulation logic might be required.
• gotcha By default, `findAndReplace` ignores content within `<math>`, `<script>`, `<style>`, `<svg>`, and `<title>` elements to prevent unintended modifications to code or metadata. This default can be overridden.
  Fix: If you need to replace text within these ignored tags, provide a custom `ignore` array in the options (e.g., `options: { ignore: [] }` to disable all ignores, or `options: { ignore: ['math', 'script'] }` for a partial override).

Install

• npm install hast-util-find-and-replace npm
• yarn add hast-util-find-and-replace yarn
• pnpm add hast-util-find-and-replace pnpm

Imports

• findAndReplace
  wrong:

  const findAndReplace = require('hast-util-find-and-replace')

  correct:

  import { findAndReplace } from 'hast-util-find-and-replace'

  Package is ESM-only since v4 and requires Node.js 16+ for v5. Use `import` syntax.
• defaultIgnore
  wrong:

  import defaultIgnore from 'hast-util-find-and-replace'

  correct:

  import { defaultIgnore } from 'hast-util-find-and-replace'

  This is a named export, not a default export.
• FindAndReplaceList

  import type { FindAndReplaceList } from 'hast-util-find-and-replace'

  Import types separately for type-checking without runtime implications.

Quickstart

This example demonstrates how to import `findAndReplace` and use it to modify a HAST tree. It shows various replacement patterns, including strings, regular expressions, and functions that generate new HAST nodes, and how to pass options like `ignore`.

import { h } from 'hastscript';
import { findAndReplace } from 'hast-util-find-and-replace';
import { inspect } from 'unist-util-inspect'; // For visualizing the tree

const tree = h('p', [
  'Some ',
  h('em', 'emphasis'),
  ', ',
  h('strong', 'importance'),
  ', and ',
  h('code', 'code'),
  '.'
]);

// Apply find and replace operations
findAndReplace(
  tree,
  [
    [/and/gi, 'or'], // Replace 'and' with 'or' (case-insensitive)
    [/emphasis/gi, 'em'], // Replace 'emphasis' with 'em'
    [/importance/gi, 'strong'], // Replace 'importance' with 'strong'
    [
      /code/gi,
      function ($0) {
        return h('a', {href: '//example.com#' + $0}, $0) // Replace 'code' with a link
      }
    ],
    ['Some', (match, node, index, parent) => {
      // Example of custom replacement logic, accessing node context
      console.log(`Found "${match}" at index ${index} in parent:`, parent.type);
      return 'Any'; // Replace "Some" with "Any"
    }]
  ],
  {
    ignore: ['code'] // Also ignore 'code' tags in addition to defaults like script/style
  }
);

console.log(inspect(tree));