Replace In File

Common errors

• TypeError: replaceInFile is not a function

  cause Attempting to use CommonJS `require` syntax or an incorrect named import with a package that is ESM-first or where the symbol is not directly exported as a default.
  fix Ensure your project is configured for ESM (`"type": "module"` in `package.json` or `.mjs` file extension) and use `import { replaceInFile } from 'replace-in-file';`

• Error: No files found matching 'path/to/non-existent-file.txt'

  cause The `files` option specifies a glob pattern or file path that does not match any existing files or is incorrectly formatted.
  fix Verify the file paths and glob patterns specified in the `files` option. Ensure the target files exist and the pattern correctly resolves to them.

• Error: The "from" option must be a string, RegExp, or array of strings/RegExps.

  cause An invalid data type was provided for the `from` option, which expects a string, a regular expression, or an array containing these types.
  fix Check the `from` option in your configuration. It must be a `string`, a `RegExp` object, or an `Array` of `string`s or `RegExp`s.

Warnings

• breaking The return value of `replaceInFile` and `replaceInFileSync` changed from an array of changed file paths to a detailed results array, where each object indicates if a file was processed and whether it changed, including match/replacement counts if enabled.
  Fix: Update existing code to process the new results array. To get an array of changed files, use `results.filter(r => r.hasChanged).map(r => r.file)`.
• breaking Support for Node.js versions 4 and 5 was dropped. The package now requires Node.js >=18.
  Fix: Upgrade your Node.js environment to version 18 or newer to ensure compatibility.
• gotcha When passing a config file path to the CLI, absolute paths now behave as such. Previously, undocumented behavior might have treated them as relative or appended them to the current working directory.
  Fix: If experiencing issues with CLI config paths, change absolute paths to relative paths by removing any leading slashes, or ensure absolute paths are correctly specified relative to the root.
• deprecated The `silent` option was deprecated in favor of `verbose` for clearer control over output. While `silent` might still work, `verbose` offers more explicit control.
  Fix: Prefer using the `verbose` option (set to `false` for no output) instead of `silent`.

Install

• npm install replace-in-file npm
• yarn add replace-in-file yarn
• pnpm add replace-in-file pnpm

Imports

• replaceInFile
  wrong:

  const replaceInFile = require('replace-in-file')

  correct:

  import { replaceInFile } from 'replace-in-file'

  The package is primarily designed for ESM consumption; ensure your project is configured for ESM (e.g., `type: 'module'` in package.json or using `.mjs` extension). Node.js >=18 is required.
• replaceInFileSync
  wrong:

  const { replaceInFileSync } = require('replace-in-file')

  correct:

  import { replaceInFileSync } from 'replace-in-file'

  Similar to `replaceInFile`, prefer ESM imports. CommonJS `require` can be used for older Node.js versions, but modern usage favors `import`.

Quickstart

Demonstrates asynchronous text replacement in a file using a regular expression, including file creation and cleanup.

import { replaceInFile } from 'replace-in-file';
import * as path from 'path';
import * as fs from 'fs';

// Create a dummy file for the example
const dummyFilePath = path.resolve(__dirname, 'temp-example.txt');
fs.writeFileSync(dummyFilePath, 'Hello foo world! Foo bar. This is foo again.');

async function runReplacement() {
  const options = {
    files: dummyFilePath,
    from: /foo/g,
    to: 'bar',
    countMatches: true // Show matches and replacements info
  };

  try {
    console.log(`Initial content of ${path.basename(dummyFilePath)}:`);
    console.log(fs.readFileSync(dummyFilePath, 'utf8'));

    const results = await replaceInFile(options);
    console.log('\nReplacement results:', results);
    // Expected output similar to:
    // [
    //   {
    //     file: '/path/to/temp-example.txt',
    //     hasChanged: true,
    //     numMatches: 3,
    //     numReplacements: 3
    //   }
    // ]

    console.log(`\nContent after replacement in ${path.basename(dummyFilePath)}:`);
    console.log(fs.readFileSync(dummyFilePath, 'utf8')); // Should be "Hello bar world! Bar bar. This is bar again."

  } catch (error) {
    console.error('Error occurred:', error);
  } finally {
    // Clean up the dummy file
    fs.unlinkSync(dummyFilePath);
    console.log(`\nCleaned up ${path.basename(dummyFilePath)}`);
  }
}

runReplacement();