0
# Configuration
1

2
Comprehensive configuration options for the UglifyJsPlugin constructor, organized by functionality.
3

4
## Capabilities
5

6
### File Selection Options
7

8
Configure which files the plugin processes during webpack builds.
9

10
```javascript { .api }
11
/**
12
 * Test to match files against for processing
13
 * @type {RegExp | string | Array<RegExp | string>}
14
 * @default /\.js(\?.*)?$/i
15
 */
16
test?: RegExp | string | Array<RegExp | string>;
17

18
/**
19
 * Files to include for processing
20
 * @type {RegExp | string | Array<RegExp | string>}
21
 * @default undefined
22
 */
23
include?: RegExp | string | Array<RegExp | string>;
24

25
/**
26
 * Files to exclude from processing
27
 * @type {RegExp | string | Array<RegExp | string>}
28
 * @default undefined
29
 */
30
exclude?: RegExp | string | Array<RegExp | string>;
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
new UglifyJsPlugin({
37
  // Process only .js files (default behavior)
38
  test: /\.js(\?.*)?$/i,
39
  
40
  // Include specific directories
41
  include: /\/src\//,
42
  
43
  // Exclude vendor files
44
  exclude: [/node_modules/, /vendor/],
45
  
46
  // Multiple patterns
47
  test: [/\.js$/, /\.jsx$/],
48
})
49
```
50

51
### Chunk Filtering
52

53
Control which webpack chunks undergo minification.
54

55
```javascript { .api }
56
/**
57
 * Function to filter which chunks should be uglified
58
 * @param {object} chunk - Webpack chunk object
59
 * @returns {boolean} True to uglify the chunk, false otherwise
60
 * @default () => true
61
 */
62
chunkFilter?: (chunk: any) => boolean;
63
```
64

65
**Usage Example:**
66

67
```javascript
68
new UglifyJsPlugin({
69
  chunkFilter: (chunk) => {
70
    // Exclude uglification for the 'vendor' chunk
71
    if (chunk.name === 'vendor') {
72
      return false;
73
    }
74
    return true;
75
  },
76
})
77
```
78

79
### Performance Options
80

81
Caching and parallel processing configuration for build performance optimization.
82

83
```javascript { .api }
84
/**
85
 * Enable file caching for faster rebuilds
86
 * @type {boolean | string}
87
 * @default false
88
 */
89
cache?: boolean | string;
90

91
/**
92
 * Override default cache keys for cache invalidation control
93
 * @param {object} defaultCacheKeys - Default cache key object
94
 * @param {string} file - File path being processed
95
 * @returns {object} Custom cache keys object
96
 * @default (defaultCacheKeys) => defaultCacheKeys
97
 */
98
cacheKeys?: (defaultCacheKeys: object, file: string) => object;
99

100
/**
101
 * Use multi-process parallel running to improve build speed
102
 * @type {boolean | number}
103
 * @default false
104
 */
105
parallel?: boolean | number;
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
new UglifyJsPlugin({
112
  // Enable caching with default directory
113
  cache: true,
114
  
115
  // Custom cache directory
116
  cache: 'path/to/cache',
117
  
118
  // Enable parallel processing (uses os.cpus().length - 1)
119
  parallel: true,
120
  
121
  // Custom number of parallel workers
122
  parallel: 4,
123
  
124
  // Custom cache keys
125
  cacheKeys: (defaultCacheKeys, file) => ({
126
    ...defaultCacheKeys,
127
    customKey: 'custom-value',
128
  }),
129
})
130
```
131

132
Default cache keys include:
133
- `'uglify-js'`: UglifyJS version
134
- `'uglifyjs-webpack-plugin'`: Plugin version  
135
- `'uglifyjs-webpack-plugin-options'`: Plugin options
136
- `hash`: Source file hash
137

138
### Source Map Options
139

140
Source map generation and processing configuration.
141

142
```javascript { .api }
143
/**
144
 * Use source maps to map error message locations to modules
145
 * Note: Slows down compilation significantly
146
 * @type {boolean}
147
 * @default false
148
 */
149
sourceMap?: boolean;
150
```
151

152
**Usage Example:**
153

154
```javascript
155
new UglifyJsPlugin({
156
  sourceMap: true, // Enable for development builds with debugging needs
157
})
158
```
159

160
**Important:** `cheap-source-map` options don't work with this plugin.
161

162
### Custom Minification
163

164
Override the default UglifyJS minification with custom functions.
165

166
```javascript { .api }
167
/**
168
 * Custom minify function to replace default UglifyJS behavior
169
 * @param {object} file - File content object with filename as key
170
 * @param {object} sourceMap - Source map object (if available)
171
 * @returns {MinifyResult} Minification result object
172
 * @default undefined (uses UglifyJS)
173
 */
174
minify?: (file: object, sourceMap?: object) => MinifyResult;
175

176
interface MinifyResult {
177
  error?: Error;
178
  map?: string;
179
  code?: string;
180
  warnings?: string[];
181
  extractedComments?: string[];
182
}
183
```
184

185
**Usage Example with Terser:**
186

187
```javascript
188
new UglifyJsPlugin({
189
  minify(file, sourceMap) {
190
    const uglifyJsOptions = {
191
      /* your custom options */
192
    };
193
    
194
    if (sourceMap) {
195
      uglifyJsOptions.sourceMap = {
196
        content: sourceMap,
197
      };
198
    }
199
    
200
    return require('terser').minify(file, uglifyJsOptions);
201
  },
202
})
203
```
204

205
**Important:** Always use `require` inside minify function when `parallel` option is enabled.
206

207
### UglifyJS Options
208

209
Configuration options passed directly to UglifyJS minifier.
210

211
```javascript { .api }
212
/**
213
 * UglifyJS minify options
214
 * @type {UglifyJSOptions}
215
 * @default UglifyJS defaults with custom output.comments setting
216
 */
217
uglifyOptions?: UglifyJSOptions;
218

219
interface UglifyJSOptions {
220
  /** Enable/disable warnings output */
221
  warnings?: boolean;
222
  /** Parser options */
223
  parse?: object;
224
  /** Compression options */
225
  compress?: boolean | object;
226
  /** Name mangling options */
227
  mangle?: boolean | object;
228
  /** Output generation options */
229
  output?: object;
230
  /** Enable top-level variable/function name mangling */
231
  toplevel?: boolean;
232
  /** Name cache for consistent mangling across builds */
233
  nameCache?: object;
234
  /** Enable IE8 compatibility */
235
  ie8?: boolean;
236
  /** Keep function names during mangling */
237
  keep_fnames?: boolean;
238
}
239
```
240

241
**Usage Example:**
242

243
```javascript
244
new UglifyJsPlugin({
245
  uglifyOptions: {
246
    warnings: false,
247
    parse: {
248
      // Parse options
249
    },
250
    compress: {
251
      drop_console: true,
252
      drop_debugger: true,
253
    },
254
    mangle: {
255
      keep_fnames: true,
256
    },
257
    output: {
258
      comments: false,
259
      beautify: false,
260
    },
261
  },
262
})
263
```
264

265
### Comment Extraction
266

267
Configuration for extracting license comments to separate files.
268

269
```javascript { .api }
270
/**
271
 * Extract comments configuration
272
 * @type {boolean | string | RegExp | Function | ExtractCommentsOptions}
273
 * @default false
274
 */
275
extractComments?: boolean | string | RegExp | Function | ExtractCommentsOptions;
276

277
interface ExtractCommentsOptions {
278
  /** What comments to extract */
279
  condition?: boolean | string | RegExp | Function;
280
  /** Extracted comments filename pattern */
281
  filename?: string | Function;
282
  /** Banner text pointing to extracted file */
283
  banner?: boolean | string | Function;
284
}
285
```
286

287
**Usage Examples:**
288

289
```javascript
290
new UglifyJsPlugin({
291
  // Extract all legal comments
292
  extractComments: true,
293
  
294
  // Extract comments matching 'all' or 'some'
295
  extractComments: 'all',
296
  extractComments: 'some', // Uses default regex /^\**!|@preserve|@license|@cc_on/i
297
  
298
  // Custom regex extraction
299
  extractComments: /^\**!|@preserve|@license/i,
300
  
301
  // Custom function extraction
302
  extractComments: (astNode, comment) => {
303
    return comment.value.includes('@license');
304
  },
305
  
306
  // Advanced configuration
307
  extractComments: {
308
    condition: /^\**!|@preserve|@license/i,
309
    filename: (file) => `${file}.LICENSE.txt`,
310
    banner: (licenseFile) => {
311
      return `License information can be found in ${licenseFile}`;
312
    },
313
  },
314
})
315
```
316

317
Default extracted filename: `${file}.LICENSE`
318
Default banner: `/*! For license information please see ${commentsFile} */`
319

320
### Warning Filtering
321

322
Control which UglifyJS warnings are displayed.
323

324
```javascript { .api }
325
/**
326
 * Filter UglifyJS warnings
327
 * @param {string} warning - Warning message from UglifyJS
328
 * @param {string} source - Source file path (if available)
329
 * @returns {boolean} True to keep the warning, false to filter it out
330
 * @default () => true
331
 */
332
warningsFilter?: (warning: string, source?: string) => boolean;
333
```
334

335
**Usage Example:**
336

337
```javascript
338
new UglifyJsPlugin({
339
  warningsFilter: (warning, source) => {
340
    // Filter out specific warnings
341
    if (warning.includes('Dropping unreachable code')) {
342
      return false;
343
    }
344
    // Keep all other warnings
345
    return true;
346
  },
347
})
348
```