0
# @rollup/plugin-terser
1

2
@rollup/plugin-terser is a Rollup plugin that provides JavaScript code minification using the Terser minifier. It integrates seamlessly with Rollup's build pipeline to generate optimized, minified bundles with optional multi-threading support for improved build performance.
3

4
## Package Information
5

6
- **Package Name**: @rollup/plugin-terser
7
- **Package Type**: npm
8
- **Language**: 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
```typescript
26
import terser from '@rollup/plugin-terser';
27

28
export default {
29
  input: 'src/index.js',
30
  output: {
31
    dir: 'output',
32
    format: 'cjs'
33
  },
34
  plugins: [terser()]
35
};
36
```
37

38
With configuration options:
39

40
```typescript
41
import terser from '@rollup/plugin-terser';
42

43
export default {
44
  input: 'src/index.js',
45
  output: {
46
    dir: 'output',
47
    format: 'cjs'
48
  },
49
  plugins: [
50
    terser({
51
      compress: {
52
        drop_console: true
53
      },
54
      mangle: {
55
        reserved: ['MyClass']
56
      },
57
      maxWorkers: 4,
58
      nameCache: {}
59
    })
60
  ]
61
};
62
```
63

64
## Architecture
65

66
The plugin is built around several key components:
67

68
- **Main Plugin Function**: Factory function that returns a Rollup plugin instance
69
- **Worker Pool System**: Optional multi-threading using Node.js worker threads for parallel processing
70
- **Terser Integration**: Direct integration with the Terser minification library
71
- **Source Map Support**: Automatic source map generation based on Rollup output configuration
72
- **Name Cache Management**: Consistent variable naming across multiple chunks
73

74
## Capabilities
75

76
### Plugin Factory Function
77

78
Creates a Rollup plugin instance configured for JavaScript minification.
79

80
```typescript { .api }
81
// External type imports (from rollup and terser packages)
82
import type { Plugin, RenderedChunk, NormalizedOutputOptions } from 'rollup';
83
import type { MinifyOptions } from 'terser';
84

85
/**
86
 * A Rollup plugin to generate a minified output bundle.
87
 *
88
 * @param options - Plugin options extending Terser's MinifyOptions
89
 * @returns Plugin instance
90
 */
91
export default function terser(options?: Options): Plugin;
92
```
93

94
### Plugin Options
95

96
Configuration interface extending Terser's standard minification options.
97

98
```typescript { .api }
99
interface Options extends MinifyOptions {
100
  /** Name cache for consistent variable naming across chunks */
101
  nameCache?: Record<string, any>;
102
  /** Maximum number of worker threads to use for parallel processing */
103
  maxWorkers?: number;
104
}
105
```
106

107
The `Options` interface extends Terser's `MinifyOptions`, which includes all standard Terser configuration options such as:
108

109
- `compress`: Compression options for dead code elimination
110
- `mangle`: Variable name mangling options  
111
- `output`: Output formatting options
112
- `sourceMap`: Source map generation settings
113
- `toplevel`: Top-level scope mangling
114
- `module`: ES module-specific optimizations
115

116
### Plugin Instance Properties
117

118
The returned plugin instance includes:
119

120
```typescript { .api }
121
interface TerserPlugin {
122
  /** Plugin identifier */
123
  name: 'terser';
124
  /** Processes each chunk through the minifier */
125
  renderChunk(
126
    code: string, 
127
    chunk: RenderedChunk, 
128
    outputOptions: NormalizedOutputOptions
129
  ): Promise<string | { code: string; map: any }>;
130
  /** Returns number of workers used in the last operation */
131
  readonly numOfWorkersUsed: number;
132
}
133
```
134

135

136
## Plugin Behavior
137

138
### Automatic Configuration
139

140
The plugin automatically applies format-specific optimizations:
141

142
- **ES Modules**: Sets `module: true` for ES module optimizations
143
- **CommonJS**: Sets `toplevel: true` for top-level scope minification  
144
- **Source Maps**: Automatically generates source maps when Rollup output specifies `sourcemap: true`
145

146
### Multi-threading Support
147

148
When `maxWorkers` is specified or multiple chunks are processed:
149

150
- Creates worker pool with specified number of workers (defaults to CPU count)
151
- Distributes minification tasks across workers for parallel processing
152
- Automatically manages worker lifecycle and cleanup
153
- Maintains thread-safe name cache synchronization
154

155
### Name Cache Management
156

157
The `nameCache` option enables consistent variable naming across chunks:
158

159
- Shared cache maintains variable mappings between processing sessions
160
- Automatically merges cache updates from worker threads
161
- Preserves naming consistency in multi-chunk builds
162

163
### Error Handling
164

165
The plugin handles errors gracefully:
166

167
- Worker thread errors are propagated to the main thread
168
- Failed workers are automatically replaced with new instances
169
- Proper cleanup ensures no hanging processes
170

171
## Usage Examples
172

173
### Basic Minification
174

175
```typescript
176
import terser from '@rollup/plugin-terser';
177

178
export default {
179
  input: 'src/index.js',
180
  output: { file: 'dist/bundle.min.js', format: 'iife' },
181
  plugins: [terser()]
182
};
183
```
184

185
### Advanced Configuration
186

187
```typescript
188
import terser from '@rollup/plugin-terser';
189

190
export default {
191
  input: 'src/index.js',
192
  output: { 
193
    file: 'dist/bundle.min.js', 
194
    format: 'iife',
195
    sourcemap: true
196
  },
197
  plugins: [
198
    terser({
199
      compress: {
200
        drop_console: true,
201
        drop_debugger: true,
202
        pure_funcs: ['console.log']
203
      },
204
      mangle: {
205
        reserved: ['MyLibrary', 'API']
206
      },
207
      output: {
208
        comments: false
209
      },
210
      maxWorkers: 4
211
    })
212
  ]
213
};
214
```
215

216
### Multi-Chunk Builds with Name Cache
217

218
```typescript
219
import terser from '@rollup/plugin-terser';
220

221
const nameCache = {};
222

223
export default {
224
  input: ['src/main.js', 'src/worker.js'],
225
  output: {
226
    dir: 'dist',
227
    format: 'es'
228
  },
229
  plugins: [
230
    terser({
231
      nameCache,
232
      mangle: true,
233
      maxWorkers: 2
234
    })
235
  ]
236
};
237
```