1 | [npm]: https://img.shields.io/npm/v/@rollup/plugin-replace
|
2 | [npm-url]: https://www.npmjs.com/package/@rollup/plugin-replace
|
3 | [size]: https://packagephobia.now.sh/badge?p=@rollup/plugin-replace
|
4 | [size-url]: https://packagephobia.now.sh/result?p=@rollup/plugin-replace
|
5 |
|
6 | [![npm][npm]][npm-url]
|
7 | [![size][size]][size-url]
|
8 | [![libera manifesto](https://img.shields.io/badge/libera-manifesto-lightgrey.svg)](https://liberamanifesto.com)
|
9 |
|
10 | # @rollup/plugin-replace
|
11 |
|
12 | 🍣 A Rollup plugin which replaces targeted strings in files while bundling.
|
13 |
|
14 | ## Requirements
|
15 |
|
16 | This plugin requires an [LTS](https://github.com/nodejs/Release) Node version (v8.0.0+) and Rollup v1.20.0+.
|
17 |
|
18 | ## Install
|
19 |
|
20 | Using npm:
|
21 |
|
22 | ```console
|
23 | npm install @rollup/plugin-replace --save-dev
|
24 | ```
|
25 |
|
26 | ## Usage
|
27 |
|
28 | Create a `rollup.config.js` [configuration file](https://www.rollupjs.org/guide/en/#configuration-files) and import the plugin:
|
29 |
|
30 | ```js
|
31 | import replace from '@rollup/plugin-replace';
|
32 |
|
33 | export default {
|
34 | input: 'src/index.js',
|
35 | output: {
|
36 | dir: 'output',
|
37 | format: 'cjs'
|
38 | },
|
39 | plugins: [
|
40 | replace({
|
41 | 'process.env.NODE_ENV': JSON.stringify('production'),
|
42 | __buildDate__: () => JSON.stringify(new Date()),
|
43 | __buildVersion: 15
|
44 | })
|
45 | ]
|
46 | };
|
47 | ```
|
48 |
|
49 | Then call `rollup` either via the [CLI](https://www.rollupjs.org/guide/en/#command-line-reference) or the [API](https://www.rollupjs.org/guide/en/#javascript-api).
|
50 |
|
51 | 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.
|
52 |
|
53 | _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._
|
54 |
|
55 | Typically, `@rollup/plugin-replace` should be placed in `plugins` _before_ other plugins so that they may apply optimizations, such as dead code removal.
|
56 |
|
57 | ## Options
|
58 |
|
59 | In addition to the properties and values specified for replacement, users may also specify the options below.
|
60 |
|
61 | ### `delimiters`
|
62 |
|
63 | Type: `Array[...String, String]`<br>
|
64 | Default: `['\b', '\b(?!\.)']`
|
65 |
|
66 | Specifies the boundaries around which strings will be replaced. By default, delimiters are [word boundaries](https://www.regular-expressions.info/wordboundaries.html) and also prevent replacements of instances with nested access. See [Word Boundaries](#word-boundaries) below for more information.
|
67 | For example, if you pass `typeof window` in `values` to-be-replaced, then you could expect the following scenarios:
|
68 |
|
69 | - `typeof window` **will** be replaced
|
70 | - `typeof window.document` **will not** be replaced due to `(?!\.)` boundary
|
71 | - `typeof windowSmth` **will not** be replaced due to a `\b` boundary
|
72 |
|
73 | ### `preventAssignment`
|
74 |
|
75 | Type: `Boolean`<br>
|
76 | Default: `false`
|
77 |
|
78 | Prevents replacing strings where they are followed by a single equals sign. For example, where the plugin is called as follows:
|
79 |
|
80 | ```js
|
81 | replace({
|
82 | values: {
|
83 | 'process.env.DEBUG': 'false'
|
84 | }
|
85 | });
|
86 | ```
|
87 |
|
88 | Observe the following code:
|
89 |
|
90 | ```js
|
91 | // Input
|
92 | process.env.DEBUG = false;
|
93 | if (process.env.DEBUG == true) {
|
94 | //
|
95 | }
|
96 | // Without `preventAssignment`
|
97 | false = false; // this throws an error because false cannot be assigned to
|
98 | if (false == true) {
|
99 | //
|
100 | }
|
101 | // With `preventAssignment`
|
102 | process.env.DEBUG = false;
|
103 | if (false == true) {
|
104 | //
|
105 | }
|
106 | ```
|
107 |
|
108 | ### `exclude`
|
109 |
|
110 | Type: `String` | `Array[...String]`<br>
|
111 | Default: `null`
|
112 |
|
113 | A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should _ignore_. By default no files are ignored.
|
114 |
|
115 | ### `include`
|
116 |
|
117 | Type: `String` | `Array[...String]`<br>
|
118 | Default: `null`
|
119 |
|
120 | A [minimatch pattern](https://github.com/isaacs/minimatch), or array of patterns, which specifies the files in the build the plugin should operate on. By default all files are targeted.
|
121 |
|
122 | ### `values`
|
123 |
|
124 | Type: `{ [key: String]: Replacement }`, where `Replacement` is either a string or a `function` that returns a string.
|
125 | Default: `{}`
|
126 |
|
127 | To avoid mixing replacement strings with the other options, you can specify replacements in the `values` option. For example, the following signature:
|
128 |
|
129 | ```js
|
130 | replace({
|
131 | include: ['src/**/*.js'],
|
132 | changed: 'replaced'
|
133 | });
|
134 | ```
|
135 |
|
136 | Can be replaced with:
|
137 |
|
138 | ```js
|
139 | replace({
|
140 | include: ['src/**/*.js'],
|
141 | values: {
|
142 | changed: 'replaced'
|
143 | }
|
144 | });
|
145 | ```
|
146 |
|
147 | ## Word Boundaries
|
148 |
|
149 | By default, values will only match if they are surrounded by _word boundaries_.
|
150 |
|
151 | Consider the following options and build file:
|
152 |
|
153 | ```js
|
154 | module.exports = {
|
155 | ...
|
156 | plugins: [replace({ changed: 'replaced' })]
|
157 | };
|
158 | ```
|
159 |
|
160 | ```js
|
161 | // file.js
|
162 | console.log('changed');
|
163 | console.log('unchanged');
|
164 | ```
|
165 |
|
166 | The result would be:
|
167 |
|
168 | ```js
|
169 | // file.js
|
170 | console.log('replaced');
|
171 | console.log('unchanged');
|
172 | ```
|
173 |
|
174 | To ignore word boundaries and replace every instance of the string, wherever it may be, specify empty strings as delimiters:
|
175 |
|
176 | ```js
|
177 | export default {
|
178 | ...
|
179 | plugins: [
|
180 | replace({
|
181 | changed: 'replaced',
|
182 | delimiters: ['', '']
|
183 | })
|
184 | ]
|
185 | };
|
186 | ```
|
187 |
|
188 | ## Meta
|
189 |
|
190 | [CONTRIBUTING](/.github/CONTRIBUTING.md)
|
191 |
|
192 | [LICENSE (MIT)](/LICENSE)
|