0
# @rollup/plugin-inject
1
2
The @rollup/plugin-inject package is a Rollup plugin that automatically scans JavaScript modules for global variable usage and dynamically injects import statements where necessary. It provides a comprehensive solution for module dependency management by analyzing code for references to global variables (like Promise, $, fs, etc.) and automatically generating the appropriate import statements at build time.
3
4
## Package Information
5
6
- **Package Name**: @rollup/plugin-inject
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install @rollup/plugin-inject --save-dev`
10
11
## Core Imports
12
13
```javascript
14
import inject from '@rollup/plugin-inject';
15
```
16
17
For CommonJS:
18
19
```javascript
20
const inject = require('@rollup/plugin-inject');
21
```
22
23
## Basic Usage
24
25
```javascript
26
import inject from '@rollup/plugin-inject';
27
28
export default {
29
input: 'src/index.js',
30
output: {
31
dir: 'output',
32
format: 'cjs'
33
},
34
plugins: [
35
inject({
36
// Inject jQuery as $
37
$: 'jquery',
38
39
// Inject named import
40
Promise: ['es6-promise', 'Promise'],
41
42
// Inject namespace import
43
fs: ['fs', '*'],
44
45
// Use local module
46
'Object.assign': './src/helpers/object-assign.js'
47
})
48
]
49
};
50
```
51
52
## Architecture
53
54
The plugin works by:
55
56
1. **Code Scanning**: Uses AST parsing to scan modules for global variable references
57
2. **Reference Detection**: Identifies which global variables are used but not locally defined
58
3. **Import Generation**: Automatically generates the appropriate import statements
59
4. **Code Transformation**: Injects imports at the top of modules and replaces global references
60
61
## Capabilities
62
63
### Plugin Factory Function
64
65
Creates a Rollup plugin instance configured with injection mappings.
66
67
```javascript { .api }
68
/**
69
* Creates a Rollup plugin for injecting import statements
70
* @param options - Configuration object defining injection mappings (required)
71
* @returns Rollup plugin object with transform method
72
* @throws Error if options parameter is missing, null, or undefined
73
*/
74
function inject(options: RollupInjectOptions): Plugin;
75
```
76
77
**Usage Example:**
78
79
```javascript
80
import inject from '@rollup/plugin-inject';
81
82
const plugin = inject({
83
$: 'jquery',
84
Promise: ['es6-promise', 'Promise']
85
});
86
```
87
88
### Configuration Options
89
90
Configuration interface for the inject plugin.
91
92
```typescript { .api }
93
interface RollupInjectOptions {
94
/** String-to-injection mappings for global variables */
95
[str: string]: Injectment | RollupInjectOptions['include'] | RollupInjectOptions['exclude'] | RollupInjectOptions['sourceMap'] | RollupInjectOptions['modules'];
96
97
/** File inclusion patterns (picomatch patterns) */
98
include?: string | RegExp | ReadonlyArray<string | RegExp> | null;
99
100
/** File exclusion patterns (picomatch patterns) */
101
exclude?: string | RegExp | ReadonlyArray<string | RegExp> | null;
102
103
/** Enable/disable source map generation (default: true) */
104
sourceMap?: boolean;
105
106
/** Separate injection mappings object */
107
modules?: { [str: string]: Injectment };
108
}
109
```
110
111
**Note**: The plugin also supports the `sourcemap` option (alternative spelling of `sourceMap`) for backward compatibility, but `sourceMap` is preferred.
112
113
**Configuration Examples:**
114
115
```javascript
116
// Basic injection mapping
117
{
118
$: 'jquery',
119
_: 'lodash'
120
}
121
122
// With file filtering
123
{
124
include: ['src/**/*.js'],
125
exclude: ['**/*.test.js'],
126
$: 'jquery'
127
}
128
129
// Using modules property
130
{
131
sourceMap: false,
132
modules: {
133
$: 'jquery',
134
Promise: ['es6-promise', 'Promise']
135
}
136
}
137
138
// Mixed approach (direct + modules)
139
{
140
// Direct mappings
141
$: 'jquery',
142
143
// Additional configuration
144
include: ['src/**'],
145
modules: {
146
Promise: ['es6-promise', 'Promise']
147
}
148
}
149
```
150
151
### Injection Value Types
152
153
Defines the format for injection values.
154
155
```typescript { .api }
156
type Injectment = string | [string, string];
157
```
158
159
**Injection Patterns:**
160
161
```javascript
162
// Default import: string format
163
{ $: 'jquery' }
164
// Generates: import $ from 'jquery';
165
166
// Named import: [module, export] format
167
{ Promise: ['es6-promise', 'Promise'] }
168
// Generates: import { Promise } from 'es6-promise';
169
170
// Namespace import: [module, '*'] format
171
{ fs: ['fs', '*'] }
172
// Generates: import * as fs from 'fs';
173
174
// Local module with default import (string format)
175
{ 'Object.assign': './helpers/object-assign.js' }
176
// Generates: import Object_assign from './helpers/object-assign.js';
177
178
// Local module with named import (array format)
179
{ 'Object.assign': ['./helpers/object-assign.js', 'assign'] }
180
// Generates: import { assign as Object_assign } from './helpers/object-assign.js';
181
182
// Keypath replacement
183
{ 'console.log': ['./logger', 'log'] }
184
// Replaces console.log calls with imported log function
185
```
186
187
### Plugin Object Properties
188
189
The plugin returns a Rollup plugin object with specific properties.
190
191
```javascript { .api }
192
interface Plugin {
193
/** Plugin identifier */
194
name: 'inject';
195
196
/**
197
* Transform method that processes code and injects imports
198
* @param code - Source code string
199
* @param id - Module identifier/file path
200
* @returns Transformation result or null if file should be skipped
201
*/
202
transform(code: string, id: string): TransformResult | null;
203
}
204
205
interface TransformResult {
206
/** Transformed code string */
207
code: string;
208
/** Source map (present when sourceMap option is true, null when false) */
209
map?: SourceMap | null;
210
/** AST representation (only included when no transformations occurred) */
211
ast?: any;
212
}
213
```
214
215
## Error Handling
216
217
### Configuration Errors
218
219
```javascript
220
// Throws Error if no options provided
221
inject(); // Error: Missing options
222
inject(null); // Error: Missing options
223
inject(undefined); // Error: Missing options
224
225
// Valid configurations (minimum requirement is empty object)
226
inject({}); // Valid - empty object creates plugin with no injections
227
inject({ $: 'jquery' }); // Valid - injection mapping
228
```
229
230
### Parse Errors
231
232
The plugin handles files that cannot be parsed:
233
234
- Issues warning with code `'PARSE_ERROR'`
235
- Suggests using `options.include` to restrict files
236
- Returns `null` to skip transformation on parse failure
237
- Does not throw errors for unparseable files
238
239
**Example Warning:**
240
```
241
rollup-plugin-inject: failed to parse src/binary-file.dat.
242
Consider restricting the plugin to particular files via options.include
243
```
244
245
### Module Resolution
246
247
- **Self-import prevention**: Modules cannot inject imports to themselves (returns false silently)
248
- **Path normalization**: Handles Windows path separators automatically (converts backslashes to forward slashes)
249
- **Module support**: Supports relative and absolute module paths
250
- **Format support**: Works with both CommonJS and ES modules
251
252
Example of prevented self-import:
253
```javascript
254
// In file: src/utils.js
255
inject({ utils: './utils.js' });
256
// The plugin will NOT inject an import to itself
257
```
258
259
## Advanced Usage Patterns
260
261
### File Filtering
262
263
```javascript
264
inject({
265
// Only process JavaScript files in src/
266
include: ['src/**/*.js'],
267
exclude: ['**/*.test.js', '**/*.spec.js'],
268
269
$: 'jquery',
270
_: 'lodash'
271
})
272
```
273
274
### Complex Injection Mappings
275
276
```javascript
277
inject({
278
// Multiple global variables from same module
279
Promise: ['es6-promise', 'Promise'],
280
'Promise.resolve': ['es6-promise', 'Promise'],
281
'Promise.reject': ['es6-promise', 'Promise'],
282
283
// Node.js modules
284
fs: ['fs', '*'],
285
path: ['path', '*'],
286
287
// Utility libraries
288
$: 'jquery',
289
_: 'lodash',
290
291
// Custom utilities
292
'utils.debounce': './src/utils/debounce.js',
293
'api.client': './src/api/client.js'
294
})
295
```
296
297
### Source Map Control
298
299
```javascript
300
inject({
301
// Disable source maps for better performance (both spellings supported)
302
sourceMap: false,
303
// Alternative spelling (deprecated but supported)
304
// sourcemap: false,
305
306
$: 'jquery'
307
})
308
```
309
310
## Dependencies
311
312
The plugin requires these peer and runtime dependencies:
313
314
- **Rollup**: `^1.20.0||^2.0.0||^3.0.0||^4.0.0` (peer dependency, optional)
315
- **@rollup/pluginutils**: `^5.0.1` (runtime dependency)
316
- **estree-walker**: `^2.0.2` (runtime dependency)
317
- **magic-string**: `^0.30.3` (runtime dependency)