replace-in-files

Replace text in one or more files or globs. Works asynchronously with promises.

Installation

1# Using npm
2npm install replace-in-files
3
4# Using yarn
5yarn add replace-in-files

Usage

Specify options

1const replaceInFiles = require('replace-in-files');
2
3const options = {
4  // See more: https://www.npmjs.com/package/globby
5  // Single file or glob
6  files: 'path/to/file',
7  // Multiple files or globs
8  files: [
9    'path/to/file',
10    'path/to/other/file',
11    'path/to/files/*.html',
12    'another/**/*.path',
13  ],
14
15
16  // See more: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace
17  // Replacement
18  from: /foo/g,  // string or regex
19  to: 'bar', // string or fn  (fn: carrying last argument - path to replaced file)
20
21
22  // See more: https://www.npmjs.com/package/glob
23  optionsForFiles: { // default
24    "ignore": [
25      "**/node_modules/**"
26    ]
27  }
28
29
30  // format: `${fileName}-${year}-${month}-${day}_${hour}:${minute}:${second}.{fileExtension}`
31  //            fileName-2017-11-01_21:29:55.js
32  // date of createFile old file or last modificate (if not find create date)
33  saveOldFile: false // default
34
35
36  //Character encoding for reading/writing files
37  encoding: 'utf8',  // default
38
39
40  shouldSkipBinaryFiles: true, // default
41  onlyFindPathsWithoutReplace: false // default
42  returnPaths: true // default
43  returnCountOfMatchesByPaths: true // default
44};

Replacing multiple occurrences

Please note that the value specified in the from parameter is passed straight to the native String replace method. As such, if you pass a string as the from parameter, it will only replace the first occurrence.

To replace multiple occurrences at once, you must use a regular expression for the from parameter with the global flag enabled, e.g. /foo/g.

Asynchronous replacement with promises

1const replaceInFiles = require('replace-in-files');
2
3// ...
4
5replaceInFiles(options)
6  .then(({ changedFiles, countOfMatchesByPaths }) => {
7    console.log('Modified files:', changedFiles);
8    console.log('Count of matches by paths:', countOfMatchesByPaths);
9    console.log('was called with:', options);
10  })
11  .catch(error => {
12    console.error('Error occurred:', error);
13  });

Asynchronous replacement with co yield

1const replaceInFiles = require('replace-in-files');
2const co = require('co');
3
4// ...
5
6co(function* () {
7  const {
8    changedFiles,
9    countOfMatchesByPaths,
10    replaceInFilesOptions
11  } = yield replaceInFiles(options);
12  console.log('Modified files:', changedFiles);
13  console.log('Count of matches by paths:', countOfMatchesByPaths);
14  console.log('was called with:', replaceInFilesOptions);
15}).catch((error) => {
16  console.log('Error occurred:', error);
17});

Asynchronous replacement with async await (node 8+)

1const replaceInFiles = require('replace-in-files');
2
3// ...
4
5async function main() {
6  try {
7    const {
8      changedFiles,
9      countOfMatchesByPaths,
10      replaceInFilesOptions
11    } = await replaceInFiles(options);
12    console.log('Modified files:', changedFiles);
13    console.log('Count of matches by paths:', countOfMatchesByPaths);
14    console.log('was called with:', replaceInFilesOptions);
15  } catch (error) {
16    console.log('Error occurred:', error);
17  }
18}
19
20main();

Sequentially replacement

use .pipe - will be replaced with only files found at first replacement

.pipe supported only: { from, to } (the other options will be received from options in the first replacement)

1const replaceInFiles = require('replace-in-files');
2
3// ...
4
5async function main() {
6  try {
7    const {
8      changedFiles,
9      countOfMatchesByPaths,
10      replaceInFilesOptions
11    } = await replaceInFiles(options)
12      .pipe({ from: 'foo', to: 'bar' })
13      .pipe({ from: 'first', to: 'second' })
14      .pipe({ from: /const/g, to: () => 'var' });
15    console.log('Modified files:', changedFiles);
16    console.log('Count of matches by paths:', countOfMatchesByPaths);
17    console.log('was called with:', replaceInFilesOptions);
18  } catch (error) {
19    console.log('Error occurred:', error);
20  }
21}
22
23main();

Return value

The return value of the library is an object with: countOfMatchesByPaths and paths

For example:

1const replaceInFiles = require('replace-in-files');
2
3const data = replaceInFiles({
4  files: 'path/to/files/*.html',
5  from: 'a',
6  to: 'b',
7});
8
9// data could like:
10{
11  countOfMatchesByPaths: [
12    {
13      'path/to/files/file1.html': 5,
14      'path/to/files/file3.html': 1,
15      'path/to/files/file5.html': 3
16    }
17  ],
18  paths: [
19    'path/to/files/file1.html',
20    'path/to/files/file3.html',
21    'path/to/files/file5.html',
22  ],
23  replaceInFilesOptions: [
24    {
25      files: 'path/to/files/*.html',
26      from: 'a',
27      to: 'b',
28    }
29  ]
30}
31
32// if empty:
33{
34  countOfMatchesByPaths: [
35    {}
36  ],
37  paths: []
38}
39
40// if used 2 .pipe
41{
42  countOfMatchesByPaths: [
43    {
44      'path/to/files/file1.html': 5,
45      'path/to/files/file3.html': 1,
46      'path/to/files/file5.html': 3
47    },
48    {
49      'path/to/files/file5.html': 4
50    },
51    {
52      'path/to/files/file1.html': 2,
53      'path/to/files/file5.html': 4
54    }
55  ],
56  paths: [
57    'path/to/files/file1.html',
58    'path/to/files/file3.html',
59    'path/to/files/file5.html',
60  ],
61  replaceInFilesOptions: [
62    {
63      files: 'path/to/files/*.html',
64      from: 'a',
65      to: 'b',
66    },
67    {
68      from: 'c',
69      to: 'd',
70    },
71    {
72      from: 'e',
73      to: 'f',
74    }
75  ]
76}
77

Version information

Replace in files requires Node 12 or higher. (v.3.0.0 +) potentially still supported earlier node, but in pipeline eslint required node >=12 Replace in files requires Node 8 or higher. (v.2.0.3) - potentially still supported node 6, but in pipeline eslint required node 8 Replace in files requires Node 6 or higher. (v.1.1.4)

License

(MIT License)