🌜
ğŸŒž
@rollup/plugin-replace

@rollup/plugin-replace

v4.0.0

Replace strings in files while bundling

npm install @rollup/plugin-replace

README

npm size libera manifesto

@rollup/plugin-replace

🍣 A Rollup plugin which replaces targeted strings in files while bundling.

Requirements

This plugin requires an LTS Node version (v8.0.0+) and Rollup v1.20.0+.

Install

Using npm:

npm install @rollup/plugin-replace --save-dev

Usage

Create a rollup.config.js configuration file and import the plugin:

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.

Options

In addition to the properties and values specified for replacement, users may also specify the options below.

delimiters

Type: Array[String, String]
Default: ['\\b', '\\b(?!\\.)']

Specifies the boundaries around which strings will be replaced. By default, delimiters are word 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 replaced
  • typeof window.document will not be replaced due to (?!\.) boundary
  • typeof windowSmth will not be replaced due to a \b boundary

Delimiters will be used to build a Regexp. To match special characters (any of .*+?^${}()|[]\), be sure to escape them.

objectGuards

Type: Boolean
Default: false

When replacing dot-separated object properties like process.env.NODE_ENV, will also replace typeof process object guard checks against the objects with the string "object".

For example:

replace({
  values: {
    'process.env.NODE_ENV': '"production"'
  }
});
// Input
if (typeof process !== 'undefined' && process.env.NODE_ENV === 'production') {
  console.log('production');
}
// Without `objectGuards`
if (typeof process !== 'undefined' && 'production' === 'production') {
  console.log('production');
}
// With `objectGuards`
if ('object' !== 'undefined' && 'production' === 'production') {
  console.log('production');
}

preventAssignment

Type: Boolean
Default: false

Prevents replacing strings where they are followed by a single equals sign. For example, where the plugin is called as follows:

replace({
  values: {
    'process.env.DEBUG': 'false'
  }
});

Observe the following code:

// Input
process.env.DEBUG = false;
if (process.env.DEBUG == true) {
  //
}
// Without `preventAssignment`
false = false; // this throws an error because false cannot be assigned to
if (false == true) {
  //
}
// With `preventAssignment`
process.env.DEBUG = false;
if (false == true) {
  //
}

exclude

Type: String | Array[...String]
Default: null

A minimatch pattern, or array of patterns, which specifies the files in the build the plugin should ignore. By default no files are ignored.

include

Type: String | Array[...String]
Default: null

A minimatch pattern, or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.

values

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:

replace({
  include: ['src/**/*.js'],
  changed: 'replaced'
});

Can be replaced with:

replace({
  include: ['src/**/*.js'],
  values: {
    changed: 'replaced'
  }
});

Word Boundaries

By default, values will only match if they are surrounded by word boundaries.

Consider the following options and build file:

module.exports = {
  ...
  plugins: [replace({ changed: 'replaced' })]
};
// file.js
console.log('changed');
console.log('unchanged');

The result would be:

// 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:

export default {
  ...
  plugins: [
    replace({
      changed: 'replaced',
      delimiters: ['', '']
    })
  ]
};

Meta

CONTRIBUTING

LICENSE (MIT)

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
Yes

Popularity

GitHub Stargazers
2,785
Community Interest
2,538
Number of Forks
446

Maintenance

Commits
10/219/22050
Last Commit
Open Issues
25
Closed Issues
710
Open Pull Requests
17
Closed Pull Requests
115

Versions

Versions Released
10/219/2202
Latest Version Released
Feb 22, 2022
Current Tags
latest4.0.0

Contributors

shellscape
shellscape
Commits: 350
lukastaegert
lukastaegert
Commits: 40
NotWoods
NotWoods
Commits: 39
benmccann
benmccann
Commits: 19
danielgindi
danielgindi
Commits: 14
tjenkinson
tjenkinson
Commits: 14
LarsDenBakker
LarsDenBakker
Commits: 13
Andarist
Andarist
Commits: 8
guybedford
guybedford
Commits: 7
TrySound
TrySound
Commits: 7
chengcyber
chengcyber
Commits: 4
Acionyx
Acionyx
Commits: 3
Kocal
Kocal
Commits: 3
pnevares
pnevares
Commits: 3
eight04
eight04
Commits: 3