string-replace-loader
raw JSON → 3.3.0 verified Sat Apr 25 auth: no javascript
A Webpack loader that performs string or regex replacements on file contents during the build process. Version 3.3.0 is the latest stable release, with occasional minor/patch updates. It supports plain string replacement, RegExp replacement (via string with flags or RegExp object), multiple replacements in a single rule, callback-based dynamic replacement, and strict mode. Key differentiators: flexible configuration similar to String.prototype.replace, array of replacements, strict mode to ensure replacements occurred. Compared to alternatives like `replace-in-file-webpack-plugin` or `webpack-replace-loader`, this loader integrates directly into the loader chain and works per-file based on test patterns. Requires Webpack 5+ and Node.js 4+.
Common errors
error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓
cause The string-replace-loader is misconfigured or not matching the correct file type, causing Webpack to attempt parsing the output as JavaScript.
fix
Ensure the loader is applied only to files that should be replaced, using a specific test pattern. Also ensure your rules are not overlapping incorrectly.
error Error: The 'search' option is not defined, but 'replace' option is provided. ↓
cause When not using 'multiple' replacements, both 'search' and 'replace' are required. This error occurs if 'search' is missing.
fix
Add a 'search' option to your loader configuration: options: { search: 'string', replace: 'newString' }
error Error: Nothing replaced. Enable strict mode to throw on unreplaced content. ↓
cause Strict mode is enabled (options.strict: true) but the search pattern was not found in the file content.
fix
Disable strict mode or ensure the search pattern exists in the matched files.
error TypeError: loaderContext.getOptions is not a function ↓
cause Using an incompatible version of Webpack (e.g., Webpack 4 with loader version 3.x).
fix
Use string-replace-loader@2.3.0 for Webpack 4 or upgrade to Webpack 5.
Warnings
breaking Version 3.0.0 drops support for Webpack 4 and lower. Using with Webpack 4 will cause errors. ↓
fix Upgrade to Webpack 5 or use string-replace-loader@2.3.0 for Webpack 4 support.
breaking Version 2.0.0 drops support for Node.js 3 and lower. Older Node versions will fail to load the loader. ↓
fix Upgrade Node.js to v4+ or use version 1.3.0.
deprecated The loader uses String.prototype.replace internally; for global replacements, you must use a regex with the 'g' flag. Missing 'g' flag replaces only first occurrence. ↓
fix Set options.flags = 'g' or provide a RegExp with global flag.
gotcha When using options.search as a string and options.flags, special regex characters in the search string must be escaped. If you intend a literal string, use the plain replacement method without flags. ↓
fix Either use a RegExp object or escape special characters like '\\$' for '$'.
gotcha The multiple replacements option processes replacements in parallel? No, they are applied sequentially. This can cause unexpected results if later replacements match strings introduced by earlier ones. ↓
fix Order your replacements carefully or use separate rules.
Install
npm install string-replace-loader yarn add string-replace-loader pnpm add string-replace-loader Imports
- string-replace-loader wrong
import stringReplaceLoader from 'string-replace-loader'correctmodule.exports = { module: { rules: [ { test: /\.js$/, loader: 'string-replace-loader', options: { search: 'foo', replace: 'bar' } } ] } }
Quickstart
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /\.js$/,
loader: 'string-replace-loader',
options: {
search: 'jQuery',
replace: 'window.$'
}
}
]
}
};