{"id":26660118,"url":"https://github.com/frsource/frs-replace","last_synced_at":"2026-05-18T06:14:59.325Z","repository":{"id":33142520,"uuid":"152633038","full_name":"FRSOURCE/frs-replace","owner":"FRSOURCE","description":"The fastest way to replace any text/file/piped stream content. Shipped with both NodeJS API \u0026 CLI out of the box!","archived":false,"fork":false,"pushed_at":"2024-04-30T09:22:10.000Z","size":837,"stargazers_count":2,"open_issues_count":5,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-01T11:06:16.569Z","etag":null,"topics":["cli","command-line-interface","fast","frs-replace","javascript","nodejs","performance","pipe","pipes","regex","regexp","regular-expression","replace","replacement","stream","streams"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FRSOURCE.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-11T17:53:52.000Z","updated_at":"2024-05-03T23:30:42.627Z","dependencies_parsed_at":"2023-12-09T01:38:19.213Z","dependency_job_id":"e72c1fe0-6f67-4f03-a74c-f55361c820c7","html_url":"https://github.com/FRSOURCE/frs-replace","commit_stats":{"total_commits":172,"total_committers":11,"mean_commits":"15.636363636363637","dds":0.6802325581395349,"last_synced_commit":"53d4487149e8c2dea7991290f04d07231a5383f8"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Ffrs-replace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Ffrs-replace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Ffrs-replace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Ffrs-replace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FRSOURCE","download_url":"https://codeload.github.com/FRSOURCE/frs-replace/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248429110,"owners_count":21101783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","command-line-interface","fast","frs-replace","javascript","nodejs","performance","pipe","pipes","regex","regexp","regular-expression","replace","replacement","stream","streams"],"created_at":"2025-03-25T11:18:55.393Z","updated_at":"2026-05-18T06:14:59.300Z","avatar_url":"https://github.com/FRSOURCE.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@frsource/frs-replace\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@frsource/frs-replace\" alt=\"NPM version badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://bundlejs.com/?q=%40frsource%2Ffrs-replace\"\u003e\n    \u003cimg src=\"https://deno.bundlejs.com/badge?q=@frsource/frs-replace\" alt=\"GZIP size calculated by bundlejs.com\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/semantic-release/semantic-release\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\" alt=\"semantic-release badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/FRSOURCE/frs-replace/blob/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/FRSOURCE/frs-replace\" alt=\"license MIT badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e@frsource/frs-replace - replace content directly in your files/streams with ease (CLI included)! 📝\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/FRSOURCE/autoresize-textarea/issues\"\u003eFile an Issue\u003c/a\u003e\n  ·\n  \u003ca href=\"#questions\"\u003eQuestion or an idea?\u003c/a\u003e\n  ·\n  \u003ca href=\"#chart_with_upwards_trend-benchmarks\"\u003eBenchmarks\u003c/a\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eThe fastest\u003c/strong\u003e (\u003ca href=\"#chart_with_upwards_trend-benchmarks\"\u003esee benchmarks\u003c/a\u003e) CLI \u0026 Node wrapper around \u003ca href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace\"\u003ejavascript replace\u003c/a\u003e which allows in-file replacing (with possibility to save changed file as a copy), \u003ca href=\"https://en.wikipedia.org/wiki/Glob_(programming)\"\u003eglobbing\u003c/a\u003e, \u003ca href=\"https://en.wikipedia.org/wiki/Pipeline_(Unix)\"\u003epiping\u003c/a\u003e and many more!\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#keyboard-cli\"\u003eGetting Started (CLI)\u003c/a\u003e\n  ·\n  \u003ca href=\"#mag_right-examples-and-recipes---cli\"\u003eExamples and recipes (CLI)\u003c/a\u003e\n  \u003cbr\u003e\n  \u003ca href=\"#books-node-api\"\u003eGetting Started (Node)\u003c/a\u003e\n  ·\n  \u003ca href=\"#mag_right-examples-and-recipes---node\"\u003eExamples and recipes (Node)\u003c/a\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n## :scroll: Installation\n\n```bash\nnpm install @frsource/frs-replace\n```\n\nor execute it right away:\n\n```bash\nnpx @frsource/frs-replace\n```\n\n## :keyboard: CLI\n\n```bash\nfrs-replace \u003cregex\u003e \u003creplacement\u003e [flags]\n```\n\nBasic usage:\n\n```bash\nfrs-replace something anything -i foo.js -o foo_replaced.js\n\n# all of the occurences of \"something\" in `foo.js` will be replaced with \"anything\" and saved to `foo_replaced.js`\n```\n\nMore examples [below](#mag_right-examples-and-recipes---cli).\n\n### Arguments\n\n| Argument        | Type   | Description                                                                                                                             |\n| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |\n| \\\u003cregex\\\u003e       | string | First parameter to [RegExp constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) |\n| \\\u003creplacement\\\u003e | string | String or path to replacement function file (see \u0026#8209;\u0026#8209;replace\u0026#8209;fn switch for details)                                     |\n\n### Flags\n\n\u003e Note: Every boolean option can be negated with use of `--no-` prefix, e.g. `--stdout` or `--no-stdout` turn stdout output on or off, respectively.\n\n\u003e Note: Object types can be set using [dot notation](https://github.com/yargs/yargs-parser#dot-notation). So, e.g. if you want to pass `utf8` value under `i-read-opts` `encoding` field you should write `--i-read-opts.encoding utf8`.\n\n| Option                                   | Type                                        | Default                                          | Description                                                                                                                                                                                                                                                                                                                       |\n| ---------------------------------------- | ------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| \u0026#8209;i, \u0026#8209;\u0026#8209;input            | string or string[]                          | _-_                                              | Path to files or [fast-glob](https://github.com/mrmlnc/fast-glob) pattern pointing to files to be read \u0026 replaced from. If multiple files specified results will be joined using `outputJoinString` option's value)                                                                                                               |\n| \u0026#8209;\u0026#8209;i-read-opts                | string or object                            | utf8                                             | Options which are passed directly to the [readFileSync method](https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options) when reading input file                                                                                                                                                                            |\n| \u0026#8209;\u0026#8209;i-glob-opts                | object                                      | _undefined_                                      | Options which are passed directly to the [fast-glob package](https://github.com/mrmlnc/fast-glob#options-1) when resolving glob patterns                                                                                                                                                                                          |\n| \u0026#8209;\u0026#8209;stdin                      | boolean                                     | _true_                                           | Wait for stdin input (should be set to _false_ when used in non-interactive terminals)                                                                                                                                                                                                                                            |\n| \u0026#8209;o, \u0026#8209;\u0026#8209;output           | string                                      | _-_                                              | Output file name/path (replaces the file if it already exists and creates any intermediate directories if they don't already exist)                                                                                                                                                                                               |\n| \u0026#8209;\u0026#8209;o-write-opts               | string or object                            | utf8                                             | Passed as options argument of [write's .sync](https://www.npmjs.com/package/write#sync)                                                                                                                                                                                                                                           |\n| \u0026#8209;\u0026#8209;o-join-str                 | string                                      | \\n                                               | Used when joining multiple files, passed directly to [javascript join](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#Syntax)                                                                                                                                                        |\n| \u0026#8209;c, \u0026#8209;\u0026#8209;content          | string                                      | _-_                                              | Content to be replaced (takes precedence over stream \u0026 file input)                                                                                                                                                                                                                                                                |\n| \u0026#8209;s, \u0026#8209;\u0026#8209;strategy         | \"join\" or \"flatten\" or \"preserve-structure\" | \"join\"                                           | Output file generation strategy. _\"join\"_ - joins all input files and outputs them as a single file using path passed as: _\"output\"_. _\"preserve-structure\"_ - saves all files to the _\"output\"_ directory keeping relative directory structure._\"flatten\"_ - same as _\"preserve-structure\"_ but flattens the directory structure |\n| \u0026#8209;f, \u0026#8209;\u0026#8209;flags            | string, combination of _gim_ flags          | g                                                | [RegExp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) flags                                                                                                                                                                                                                    |\n| \u0026#8209;\u0026#8209;stdout                     | boolean                                     | _true_ if piped input present, _false_ otherwise | Force sending output on stdout                                                                                                                                                                                                                                                                                                    |\n| \u0026#8209;r, \u0026#8209;\u0026#8209;replace\u0026#8209;fn | boolean                                     | false                                            | Treat replacement argument as path to file containing replacement function                                                                                                                                                                                                                                                        |\n| \u0026#8209;h, \u0026#8209;\u0026#8209;help             | boolean                                     | _-_                                              | Show help                                                                                                                                                                                                                                                                                                                         |\n| \u0026#8209;v, \u0026#8209;\u0026#8209;version          | boolean                                     | _-_                                              | Show version number                                                                                                                                                                                                                                                                                                               |\n\n## :mag_right: Examples and recipes - CLI\n\n##### 1. Replace all `a` occurrences with `b` from the `foo.js` file and return the result (using CLI)\n\n```bash\nfrs-replace a b -i foo.js --stdout\n```\n\n##### 2. Replace all `a` occurrences with `b` from `foo.js` and save the result to the `foo_replaced.js` (using CLI)\n\n```bash\nfrs-replace a b -i foo.js -o foo_replaced.js\n```\n\n##### 3. Replace all `a` occurrences with `b` from an array of files and save the result to the `foo_replaced.js` using default `\\n` as a result-joining string (using CLI)\n\n```bash\nfrs-replace a b -i foo.js -i foo2.js -o foo_replaced.js\n```\n\n##### 4. Replace all `a` occurrences with `b` from all `.js` files in the `foo` directory and save the result to the `foo_replaced.js` using `\\n/////\\n` as a result-joining string (using CLI)\n\n```bash\nfrs-replace a b -i foo/*.js -o foo_replaced.js --o-join-str \"\\n/////\\n\"\n```\n\n##### 5. Replace all `a` occurrences with `b` in a content string `abcd` and save the result to the `foo_replaced.js` (using CLI)\n\n```bash\nfrs-replace a b --content abcd -o foo_replaced.js\n```\n\n##### 6. Replace all `a` occurrences with `b` from a piped stream and save it to the output file (using CLI)\n\n```bash\n\u003cread-file\u003e | frs-replace a b \u003e \u003coutput-file-path\u003e\n```\n\n##### 7. Replace all `a` occurrences with `b` from a piped stream and pass it through the `stdout` stream to the `\u003cnext-command\u003e` (using CLI)\n\n```bash\n\u003cread-file\u003e | frs-replace a b | \u003cnext-command\u003e\n```\n\n## :books: Node API\n\n@frsource/frs-replace package is shipped in 2 flavors: synchronous and asynchronous:\n\n```javascript\nimport { sync, async } from '@frsource/frs-replace';\n\nsync({\n  /* options */\n});\nawait async({\n  /* options */\n});\n```\n\nWhere `/* options */` is an object containing:\n\n\u003e Note: one of parameters: **input** or **content** is required\n\n| Option             | Type                                                                                                                      | Default     | Description                                                                                                                                                                                                                                                                                                                       |\n| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| input              | string or string[]                                                                                                        | _undefined_ | Path to files or [fast-glob](https://github.com/mrmlnc/fast-glob) pattern pointing to files to be read \u0026 replaced from. If multiple files specified results will be joined using `outputJoinString` option's value)                                                                                                               |\n| inputReadOptions   | string or object                                                                                                          | utf8        | Options which are passed directly to the [readFileSync method](https://nodejs.org/api/fs.html#fs_fs_readfilesync_path_options) when reading input file                                                                                                                                                                            |\n| inputGlobOptions   | object                                                                                                                    | _undefined_ | Options which are passed directly to the [fast-glob package](https://github.com/mrmlnc/fast-glob#options-1) when resolving glob patterns                                                                                                                                                                                          |\n| content            | string                                                                                                                    | _undefined_ | Content to be replaced (takes precedence over file input)                                                                                                                                                                                                                                                                         |\n| strategy           | \"join\" or \"flatten\" or \"preserve-structure\"                                                                               | \"join\"      | Output file generation strategy. _\"join\"_ - joins all input files and outputs them as a single file using path passed as: _\"output\"_. _\"preserve-structure\"_ - saves all files to the _\"output\"_ directory keeping relative directory structure._\"flatten\"_ - same as _\"preserve-structure\"_ but flattens the directory structure |\n| needle             | string or [RegExp Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#Syntax) | _-_         | Used as a first argument of [javascript replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Syntax)                                                                                                                                                                          |\n| replacement        | string                                                                                                                    | _-_         | Passed as a second argument to [javascript replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#Syntax)                                                                                                                                                                       |\n| output             | string                                                                                                                    | _undefined_ | Path of an output file                                                                                                                                                                                                                                                                                                            |\n| outputWriteOptions | string or object                                                                                                          | \"utf8\"      | Passed as options argument of [write's .sync](https://www.npmjs.com/package/write#sync)                                                                                                                                                                                                                                           |\n| outputJoinString   | string                                                                                                                    | \\n          | String used when joining multiple files, passed directly to [javascript join](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join#Syntax)                                                                                                                                                 |\n\n## :mag_right: Examples and recipes - Node\n\n\u003e Note: While all of examples are using synchronous API method in all cases your can use `async` as well.\n\n##### 1. Replace all `a` occurrences with `b` from the `foo.js` file and return the result\n\n```javascript\nimport { sync } from '@frsource/frs-replace';\n\nconst result = sync({\n  input: 'foo.js',\n  regex: new RegExp('a', 'g'),\n  replacement: 'b',\n  output: 'foo_replaced.js',\n});\n```\n\n##### 2. Replace all `a` occurrences with `b` from `foo.js` and save the result to the `foo_replaced.js`\n\n```javascript\nimport { sync } from '@frsource/frs-replace';\nconst result = sync({\n  input: 'foo.js',\n  regex: new RegExp('a', 'g'),\n  replacement: 'b',\n  output: 'foo_replaced.js',\n});\n```\n\n##### 3. Replace all `a` occurrences with `b` from an array of files and save the result to the `foo_replaced.js` using default `\\n` as a result-joining string\n\n```javascript\nimport { sync } from '@frsource/frs-replace';\nconst result = sync({\n  input: ['foo.js', 'foo2.js'],\n  regex: new RegExp('a', 'g'),\n  replacement: 'b',\n  output: 'foo_replaced.js',\n});\n```\n\n##### 4. Replace all `a` occurrences with `b` from all `.js` files in the `foo` directory and save the result to the `foo_replaced.js` using `\\n/////\\n` as a result-joining string\n\n```javascript\nimport { sync } from '@frsource/frs-replace';\nconst result = sync({\n  input: 'foo/*.js',\n  regex: new RegExp('a', 'g'),\n  replacement: 'b',\n  outputJoinString: '\\n/////\\n',\n  output: 'foo_replaced.js',\n});\n```\n\n##### 5. Replace all `a` occurrences with `b` in a content string `abcd` and save the result to the `foo_replaced.js`\n\n```javascript\nimport { sync } from '@frsource/frs-replace';\nconst result = sync({\n  content: 'abcd',\n  regex: new RegExp('a', 'g'),\n  replacement: 'b',\n  output: 'foo_replaced.js',\n});\n```\n\n## :chart_with_upwards_trend: Benchmarks\n\n\u003e Tested on Node v24.15.0.\n\n### input as glob pattern [40 files]\n\n| Rank | Library                       | Average latency [ms] | Difference percentage (comparing\u0026nbsp;to\u0026nbsp;best\u0026nbsp;average\u0026nbsp;latency) |\n| ---- | ----------------------------- | -------------------- | ----------------------------------------------------------------------------- |\n| 1    | @frsource/frs-replace (sync)  | 0.37 ± 1.21%         | +0.00%                                                                        |\n| 2    | replace-in-file (sync)        | 0.47 ± 2.53%         | +28.55%                                                                       |\n| 3    | @frsource/frs-replace (async) | 1.87 ± 1.49%         | +408.43%                                                                      |\n| 4    | replace-in-file (async)       | 2.83 ± 1.61%         | +670.75%                                                                      |\n\n### input \u0026 replacement as strings\n\n| Rank | Library                       | Average latency [ms] | Difference percentage (comparing\u0026nbsp;to\u0026nbsp;best\u0026nbsp;average\u0026nbsp;latency) |\n| ---- | ----------------------------- | -------------------- | ----------------------------------------------------------------------------- |\n| 1    | @frsource/frs-replace (sync)  | 0.00 ± 0.48%         | +0.00%                                                                        |\n| 2    | replaceString                 | 0.00 ± 0.51%         | +24.37%                                                                       |\n| 3    | @frsource/frs-replace (async) | 0.00 ± 0.50%         | +32.73%                                                                       |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrsource%2Ffrs-replace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrsource%2Ffrs-replace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrsource%2Ffrs-replace/lists"}