@rollup/plugin-replace

What is @rollup/plugin-replace?

The @rollup/plugin-replace npm package allows you to replace strings in files while bundling them with Rollup. This can be particularly useful for inserting environment variables, toggling between development and production modes, or any scenario where you need to dynamically alter your code at build time.

What are @rollup/plugin-replace's main functionalities?

Environment Variable Replacement

This feature allows you to replace occurrences of 'process.env.NODE_ENV' with 'production' in your code. It's particularly useful for setting the environment mode.

import replace from '@rollup/plugin-replace';

export default {
  plugins: [
    replace({
      'process.env.NODE_ENV': JSON.stringify('production')
    })
  ]
};

Conditional Code Inclusion/Exclusion

This feature enables you to conditionally include or exclude code blocks based on the replacement. In this example, all blocks guarded by 'if (process.env.DEBUG)' will always execute as if the condition is true.

import replace from '@rollup/plugin-replace';

export default {
  plugins: [
    replace({
      'if (process.env.DEBUG)': 'if (true)'
    })
  ]
};

Other packages similar to @rollup/plugin-replace

babel-plugin-transform-define

This Babel plugin allows you to replace specified nodes in your Babel AST with arbitrary values, similar to how @rollup/plugin-replace works. The difference lies in the approach: babel-plugin-transform-define operates on the AST level during the transpilation step, rather than during the bundling process.

README

@rollup/plugin-replace

🍣 A Rollup which replaces 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({ __buildEnv__: 'production' })]
};

Then call rollup either via the CLI or the API.

The configuration above will replace every instance of __buildEnv__ with 'productions' in any file included in the build. Note: Values should always be strings. For complex values, use JSON.stringify.

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. See Word Boundaries below for more information.

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.

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)