Replace strings in files while bundling
npm install @rollup/plugin-replace[npm]: https://img.shields.io/npm/v/@rollup/plugin-replace
[npm-url]: https://www.npmjs.com/package/@rollup/plugin-replace
[size]: https://packagephobia.now.sh/badge?p=@rollup/plugin-replace
[size-url]: https://packagephobia.now.sh/result?p=@rollup/plugin-replace
[![npm][npm]][npm-url]
[![size][size]][size-url]
š£ A Rollup plugin which replaces targeted strings in files while bundling.
This plugin requires an LTS Node version (v14.0.0+) and Rollup v1.20.0+.
Using npm:
``console`
npm install @rollup/plugin-replace --save-dev
Create a rollup.config.js configuration file and import the plugin:
`js
import replace from '@rollup/plugin-replace';
export default {
input: 'src/index.js',
output: {
dir: 'output',
format: 'cjs'
},
plugins: [
replace({
'process.env.NODE_ENV': JSON.stringify('production'),
__buildDate__: () => JSON.stringify(new Date()),
__buildVersion: 15
})
]
};
`
Then call rollup either via the CLI or the API.
The configuration above will replace every instance of process.env.NODE_ENV with "production" and __buildDate__ with the result of the given function in any file included in the build.
_Note: Values must be either primitives (e.g. string, number) or function that returns a string. For complex values, use JSON.stringify. To replace a target with a value that will be evaluated as a string, set the value to a quoted string (e.g. "test") or use JSON.stringify to preprocess the target string safely._
Typically, @rollup/plugin-replace should be placed in plugins _before_ other plugins so that they may apply optimizations, such as dead code removal.
In addition to the properties and values specified for replacement, users may also specify the options below.
Type: Array[String, String]
Default:
Specifies the boundaries around which strings will be replaced. By default, delimiters match JavaScript identifier boundaries and also prevent replacements of instances with nested access. See Word Boundaries below for more information.
For example, if you pass typeof window in values to-be-replaced, then you could expect the following scenarios:
- typeof window will be replacedtypeof window.document
- will not be replaced due to the (?!\.) boundarytypeof windowSmth
- will not be replaced due to identifier boundaries
Delimiters will be used to build a Regexp. To match special characters (any of .*+?^${}()|[]\), be sure to escape them.
Type: Boolean
Default:
When replacing dot-separated object properties like process.env.NODE_ENV, will also replace typeof process object guard"object"
checks against the objects with the string .
For example:
`js`
replace({
values: {
'process.env.NODE_ENV': '"production"'
}
});
`jsobjectGuards
// Input
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production') {
console.log('production');
}
// Without
if (typeof process !== 'undefined' && 'production' === 'production') {
console.log('production');
}
// With
if ('object' !== 'undefined' && 'production' === 'production') {
console.log('production');
}
Type: Boolean
Default:
Prevents replacing strings where they are followed by a single equals sign. For example, where the plugin is called as follows:
`js`
replace({
values: {
'process.env.DEBUG': 'false'
}
});
Observe the following code:
`jspreventAssignment
// Input
process.env.DEBUG = false;
if (process.env.DEBUG == true) {
//
}
// Without
false = false; // this throws an error because false cannot be assigned to
if (false == true) {
//
}
// With
process.env.DEBUG = false;
if (false == true) {
//
}
Type: String | Array[...String]
Default:
A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should _ignore_. By default no files are ignored.
Type: String | Array[...String]
Default:
A picomatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.
Type: Boolean
Default:
Enables generating sourcemaps for the bundled code. For example, where the plugin is called as follows:
`js`
replace({
sourcemap: true
});
Type: { [key: String]: Replacement }, where Replacement is either a string or a function that returns a string.{}
Default:
To avoid mixing replacement strings with the other options, you can specify replacements in the values option. For example, the following signature:
`js`
replace({
include: ['src/*/.js'],
changed: 'replaced'
});
Can be replaced with:
`js`
replace({
include: ['src/*/.js'],
values: {
changed: 'replaced'
}
});
By default, values will only match if they are surrounded by _word boundaries_ that respect JavaScript's rules for valid identifiers (including $ and _ as valid identifier characters).
Consider the following options and build file:
`js`
module.exports = {
...
plugins: [replace({ changed: 'replaced' })]
};
`js`
// file.js
console.log('changed');
console.log('unchanged');
The result would be:
`js`
// file.js
console.log('replaced');
console.log('unchanged');
To ignore word boundaries and replace every instance of the string, wherever it may be, specify empty strings as delimiters:
`js``
export default {
...
plugins: [
replace({
changed: 'replaced',
delimiters: ['', '']
})
]
};