0
# Rollup Plugin Terser
1

2
Rollup Plugin Terser is a plugin for Rollup that integrates Terser for minifying JavaScript bundles during the build process. It provides worker-based parallel processing for efficient minification, automatic configuration based on output format, and comprehensive options for controlling the minification process.
3

4
## Package Information
5

6
- **Package Name**: rollup-plugin-terser
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install rollup-plugin-terser --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { terser } from "rollup-plugin-terser";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { terser } = require("rollup-plugin-terser");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import { rollup } from "rollup";
27
import { terser } from "rollup-plugin-terser";
28

29
// Basic usage with default options
30
export default {
31
  input: "src/index.js",
32
  output: {
33
    file: "dist/bundle.min.js",
34
    format: "iife"
35
  },
36
  plugins: [terser()]
37
};
38

39
// With custom options
40
export default {
41
  input: "src/index.js",
42
  output: {
43
    file: "dist/bundle.min.js",
44
    format: "esm"
45
  },
46
  plugins: [
47
    terser({
48
      compress: {
49
        drop_console: true
50
      },
51
      format: {
52
        comments: false
53
      },
54
      numWorkers: 4
55
    })
56
  ]
57
};
58
```
59

60
## Architecture
61

62
Rollup Plugin Terser is built around several key components:
63

64
- **Plugin Factory**: The `terser()` function that creates and configures the Rollup plugin instance
65
- **Worker Management**: Uses jest-worker for multi-threaded minification to improve performance
66
- **Format Detection**: Automatically configures Terser options based on Rollup's output format (ESM, CommonJS, etc.)
67
- **Options Processing**: Merges user options with format-specific defaults and handles plugin-specific options
68
- **Error Handling**: Enhanced error reporting with code frame context using Babel's code-frame
69

70
## Capabilities
71

72
### Terser Plugin Factory
73

74
Creates a Rollup plugin instance configured for JavaScript minification using Terser.
75

76
```typescript { .api }
77
/**
78
 * Creates a Rollup plugin for minifying JavaScript code using Terser
79
 * @param options - Configuration options extending Terser's MinifyOptions
80
 * @returns Rollup Plugin object with renderChunk method
81
 */
82
function terser(options?: Options): Plugin;
83

84
interface Options extends Omit<MinifyOptions, "sourceMap"> {
85
  /**
86
   * Amount of workers to spawn for parallel processing
87
   * Defaults to the number of CPUs minus 1
88
   */
89
  numWorkers?: number;
90
}
91

92
interface Plugin {
93
  /** Plugin identifier */
94
  name: "terser";
95
  /** Async method called by Rollup to process each chunk */
96
  renderChunk(code: string, chunk: ChunkInfo, outputOptions: OutputOptions): Promise<TransformResult>;
97
}
98
```
99

100
**Configuration Features:**
101

102
- **Automatic Format Detection**: The plugin automatically sets optimal Terser options based on Rollup's output format:
103
  - `module: true` when format is `esm` or `es`
104
  - `toplevel: true` when format is `cjs`
105
  - `sourceMap` inferred from Rollup's sourcemap settings
106

107
- **Worker-based Processing**: Uses jest-worker to spawn multiple processes for parallel minification, improving performance on multi-core systems
108

109
- **Name Cache Support**: Supports Terser's name caching feature for consistent variable names across builds
110

111
**Usage Examples:**
112

113
```javascript
114
// Basic minification
115
terser()
116

117
// Custom compression settings
118
terser({
119
  compress: {
120
    drop_console: true,
121
    drop_debugger: true,
122
    pure_funcs: ["console.log", "console.warn"]
123
  }
124
})
125

126
// Preserve specific comments (e.g., licenses)
127
terser({
128
  format: {
129
    comments: function(node, comment) {
130
      const text = comment.value;
131
      const type = comment.type;
132
      if (type === "comment2") {
133
        // multiline comment
134
        return /@preserve|@license|@cc_on/i.test(text);
135
      }
136
    }
137
  }
138
})
139

140
// Keep all comments
141
terser({
142
  format: {
143
    comments: "all"
144
  }
145
})
146

147
// Custom worker configuration
148
terser({
149
  numWorkers: 2,
150
  compress: {
151
    passes: 2
152
  }
153
})
154

155
// Name cache for consistent builds
156
const nameCache = {};
157
terser({
158
  nameCache: nameCache,
159
  mangle: {
160
    properties: true
161
  }
162
})
163
```
164

165
## Types
166

167
```typescript { .api }
168
interface Options extends Omit<MinifyOptions, "sourceMap"> {
169
  /**
170
   * Amount of workers to spawn for parallel processing
171
   * Defaults to the number of CPUs minus 1
172
   */
173
  numWorkers?: number;
174
}
175

176
interface Plugin {
177
  /** Plugin identifier */
178
  name: "terser";
179
  /** Async method called by Rollup to process each chunk */
180
  renderChunk(
181
    code: string,
182
    chunk: ChunkInfo,
183
    outputOptions: OutputOptions
184
  ): Promise<TransformResult>;
185
}
186

187
interface ChunkInfo {
188
  fileName: string;
189
  name: string;
190
  isEntry: boolean;
191
  isDynamicEntry: boolean;
192
  facadeModuleId: string | null;
193
  moduleIds: string[];
194
  exports: string[];
195
  [key: string]: any;
196
}
197

198
interface OutputOptions {
199
  format: "es" | "esm" | "cjs" | "iife" | "umd" | "system" | "amd";
200
  sourcemap?: boolean | "inline" | "hidden";
201
  [key: string]: any;
202
}
203

204
interface TransformResult {
205
  code: string;
206
  map?: any; // Source map object
207
}
208
```
209

210
## Error Handling
211

212
The plugin provides enhanced error reporting with code context:
213

214
- **Parse Errors**: When Terser encounters syntax errors, the plugin displays the problematic code with line numbers and context using Babel's code-frame
215
- **Worker Errors**: Errors from worker processes are properly propagated and formatted
216
- **Configuration Errors**: Invalid configuration options (like deprecated `sourceMap` or `sourcemap` options) throw descriptive errors
217

218
**Deprecated Options:**
219

220
The plugin will throw errors for these deprecated options:
221
- `sourceMap` - Now inferred from Rollup options
222
- `sourcemap` - Now inferred from Rollup options
223

224
## Performance Notes
225

226
- **Worker Management**: Workers are created per plugin instance and reused across chunks in the same build
227
- **Memory Efficiency**: Workers are terminated when all chunks are processed to free memory
228
- **CPU Utilization**: Default worker count is CPU cores minus 1 for optimal performance without blocking the system