TypeScript icon, indicating that this package has built-in type declarations

1.2.1 • Public • Published



Find and replace strings, regex patterns, or template outputs in text files (CLI tool designed for use in npm scripts)

License:MIT npm Build

replacer-util searches for text to substitute with a replacement string or with values from your project's package.json file, such as the project version number.  LiquidJS powers the templates outputs and enables replacer-util to act as a static site generator complete with filter formatters and render tags for including partials. 


A) Setup

Install package for node:

$ npm install --save-dev replacer-util

B) Usage

1. npm scripts

Run replacer from the "scripts" section of your package.json file.


  • The first parameter is the source folder or file.
  • The second parameter is the target folder.

Example package.json scripts:

   "scripts": {
      "build-web": "replacer src/web --ext=.html --pkg dist/website",
      "poetry": "replacer poems --find=human --replacement=robot dystopian-poems"

2. Command-line npx

Example terminal commands:

$ npm install --save-dev replacer-util
$ npx replacer src/web ext=.html docs/api-manual

You can also install replacer-util globally (--global) and then run it anywhere directly from the terminal.

3. CLI flags

Command-line flags:

Flag Description Value
--cd Change working directory before starting search. string
--concat Merge all files into one file in the target folder. string
--content String to be used instead of the input file contents. string
--exclude Skip files containing the string in their path. string
--ext Filter files by file extension, such as .js.
Use a comma to specify multiple extensions.
--find Text to search for in the source input files. string
--header Prepend a line of text to each file. string
--pkg Load package.json and make it available as pkg. N/A
--no-source-map Remove any sourceMappingURL comment directives. N/A
--note Place to add a comment only for humans. string
--quiet Suppress informational messages. N/A
--regex Pattern to search for in the source input files. string
--rename New output filename. string
--replacement Text to insert into the target output files. string
--summary Only print out the single line summary message. N/A

To avoid issues on the command line, problematic characters can be "escaped" with safe strings as listed below.

Escape characters:

Character Safe stand-in string
' {{apos}}
! {{bang}}
} {{close-curly}}
= {{equals}}
> {{gt}}
< {{lt}}
{ {{open-curly}}
| {{pipe}}
" {{quote}}
; {{semi}}

4. Example CLI usage


  • replacer src --pkg build
    Recursively copy all the files in the src folder to the build folder using the data in package.json to update the template outputs.

  • replacer src/docs --find=Referer --replacement=Referrer fixed
    Fix spelling error in markdown files.

  • replacer web '--find=cat dog' '--replacement= cat{{pipe}}dog ' target
    replacer web --find=cat\ dog --replacement=\ cat{{pipe}}dog\ target
    replacer web --find=cat{{space}}dog --replacement={{space}}cat{{pipe}}dog{{space}} target
    Replace all occurances of the string 'cat dog' with ' cat|dog ' (note the 3 different ways to "escape" a space character).

  • replacer src --ext=.js --pkg --concat=bundle.js build
    Merge all JS files into build/bundle.js.

  • replacer app/widgets --ext=.less --pkg --content=@import{{space}}{{quote}}{{file.dir}}/{{}}{{quote}}{{semi}} --concat=widgets.less app/style
    Create a single LESS file that imports the LESS files of every widget component.

  • replacer src --pkg --summary build
    Display the summary but not the individual files copied.

  • replacer src --regex=/^--/gm --replacement=🥕🥕🥕 build
    Find double dashes at the start of lines and replace them with 3 carrots.  Note the gm regex options.

  • replacer build/my-app.js --rename=my-app.browser.js build
    Copy my-app.js to my-app.browser.js without making and changes.

  • replacer src/web --ext=.html --rename=index.html dist/website
    Rename all HTML files, such as src/web/about/about.html, to index.html while preserving the folder stucture.

  • replacer --cd=spec/fixtures source --find=insect --replacement=A.I. --pkg target
    Remove all insects. See: source/mock1.html and target/mock1.html

  • replacer node_modules/chart.js/dist/chart.umd.js --no-source-map build/1-pre/libs
    Removes the //# line at the bottom of the Chart.js distribution file.

5. Template outputs and filter formatters

When the --pkg flag is used, values from your project's package.json are available as variables for LiquidJS template outputs.  Formatting, such as appling upcase, is done with LiquidJS filter formattersPath information is also available in the file object (which also includes the supplemental path field).

For example, a TypeScript file with the lines:

const msg1: string = 'The current release of {{ | upcase}} is v{{pkg.version}}.';
const msg2: string = 'This file is: {{file.base}}';

will be transformed into something like:

const msg1: string = 'The current release of MY-COOL-NPM-PACKAGE is v1.2.3.';
const msg2: string = 'This file is: my-app.ts';

6. SemVer

Your project's dependancies declared in package.json can be used to automatically keep your CDN links up-to-date.

Three special filter formatters are available to support Semantic Versioning (SemVer):

  • version
  • major-version
  • minor-version

For example, if your project declares a dependency of ^3.1.2 for fetch-json, the line:

<script src={{pkg.dependencies.fetch-json|minor-version}}/dist/fetch-json.min.js></script>

will be transformed into:

<script src=></script>

Note: Some package names contain one or more of the characters @, /, and ., and these 3 characters are not supported for replacement.  Use - in the package name instead.

For example, CDN links for the packages "@fortawesome/fontawesome-free" and "highlight.js" can be created with:

<link rel=stylesheet href={{pkg.devDependencies.-fortawesome-fontawesome-free|version}}/css/all.min.css>
<script src={{pkg.devDependencies.highlight-js|version}}/build/highlight.min.js></script>

C) Application Code

Even though replacer-util is primarily intended for build scripts, the package can be used programmatically in ESM and TypeScript projects.


import { replacer } from 'replacer-util';

const options = { extensions: ['.html', '.js'], pkg: true };
const results = replacer.transform('src/web', 'docs/api-manual', options);
console.log('Number of files copied:', results.count);

See the TypeScript Declarations at the top of replacer.ts for documentation.

CLI Build Tools for package.json

  • 🎋 add-dist-headerPrepend a one-line banner comment (with license notice) to distribution files
  • 📄 copy-file-utilCopy or rename a file with optional package version number
  • 📂 copy-folder-utilRecursively copy files from one folder to another folder
  • 🪺 recursive-execRun a command on each file in a folder and its subfolders
  • 🔍 replacer-utilFind and replace strings or template outputs in text files
  • 🔢 rev-web-assetsRevision web asset filenames with cache busting content hash fingerprints
  • 🚆 run-scripts-utilOrganize npm scripts into named groups of easy to manage commands
  • 🚦 w3c-html-validatorCheck the markup validity of HTML files using the W3C validator

Feel free to submit questions at:

MIT License

Package Sidebar


DownloadsWeekly Downloads






Unpacked Size

26.6 kB

Total Files


Last publish


  • dpilafian