0
# Rollup
1

2
Rollup is a next-generation JavaScript module bundler that compiles small pieces of code into larger, more complex applications or libraries. It focuses on ES module standards and provides superior tree-shaking capabilities through deep execution path analysis, eliminating dead code more effectively than other bundlers.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { rollup, defineConfig, watch, VERSION } from "rollup";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { rollup, defineConfig, watch, VERSION } = require("rollup");
21
```
22

23
Separate entry points:
24

25
```typescript
26
// Configuration loading (Node.js only)
27
import { loadConfigFile } from "rollup/loadConfigFile";
28

29
// Log filtering
30
import { getLogFilter } from "rollup/getLogFilter";
31

32
// AST parsing utilities
33
import { parseAst, parseAstAsync } from "rollup/parseAst";
34
```
35

36
## Basic Usage
37

38
```typescript
39
import { rollup } from "rollup";
40

41
// Basic bundling
42
const bundle = await rollup({
43
  input: "src/main.js",
44
  external: ["lodash"],
45
  plugins: []
46
});
47

48
// Generate bundle
49
const { output } = await bundle.generate({
50
  format: "esm",
51
  file: "dist/bundle.js"
52
});
53

54
// Write to disk
55
await bundle.write({
56
  format: "esm",
57
  file: "dist/bundle.js"
58
});
59

60
// Clean up
61
await bundle.close();
62
```
63

64
## Architecture
65

66
Rollup is built around several key components:
67

68
- **Core Bundler**: Main `rollup()` function that creates bundles from input options
69
- **Build System**: `RollupBuild` objects that handle generation and output
70
- **Plugin System**: Comprehensive hook-based architecture for extending functionality
71
- **Watch Mode**: File watching capabilities for development workflows
72
- **Configuration System**: Flexible configuration loading and merging
73
- **Tree-shaking Engine**: Advanced static analysis for dead code elimination
74
- **Format Support**: Multiple output formats (ES modules, CommonJS, UMD, IIFE, AMD, SystemJS)
75

76
## Capabilities
77

78
### Core Bundling
79

80
Primary bundling functionality for creating optimized JavaScript bundles from ES modules. Supports advanced tree-shaking, code splitting, and multiple output formats.
81

82
```typescript { .api }
83
function rollup(options: RollupOptions): Promise<RollupBuild>;
84

85
interface RollupBuild {
86
  cache: RollupCache | undefined;
87
  closed: boolean;
88
  watchFiles: string[];
89
  generate(outputOptions: OutputOptions): Promise<RollupOutput>;
90
  write(outputOptions: OutputOptions): Promise<RollupOutput>;
91
  close(): Promise<void>;
92
  [Symbol.asyncDispose](): Promise<void>;
93
  getTimings?(): SerializedTimings;
94
}
95
```
96

97
[Core Bundling](./core-bundling.md)
98

99
### Configuration System
100

101
Type-safe configuration utilities and loading mechanisms for managing complex build setups and development workflows.
102

103
```typescript { .api }
104
function defineConfig<T extends RollupOptions | RollupOptions[] | RollupOptionsFunction>(
105
  options: T
106
): T;
107

108
function loadConfigFile(
109
  fileName: string,
110
  commandOptions?: object,
111
  watchMode?: boolean
112
): Promise<{options: MergedRollupOptions[], warnings: object}>;
113

114
type RollupOptionsFunction = (
115
  commandLineArguments: Record<string, any>
116
) => MaybePromise<RollupOptions | RollupOptions[]>;
117
```
118

119
[Configuration](./configuration.md)
120

121
### Watch Mode
122

123
Development-focused file watching system that automatically rebuilds when source files change, with comprehensive event handling and error recovery.
124

125
```typescript { .api }
126
function watch(configs: RollupWatchOptions | RollupWatchOptions[]): RollupWatcher;
127

128
interface RollupWatcher extends AwaitingEventEmitter<{
129
  change: (id: string, change: { event: ChangeEvent }) => void;
130
  close: () => void;
131
  event: (event: RollupWatcherEvent) => void;
132
  restart: () => void;
133
}> {
134
  close(): Promise<void>;
135
  emit<K extends keyof T>(event: K, ...parameters: Parameters<T[K]>): Promise<unknown>;
136
  on<K extends keyof T>(event: K, listener: AwaitedEventListener<T, K>): this;
137
  off<K extends keyof T>(event: K, listener: AwaitedEventListener<T, K>): this;
138
}
139
```
140

141
[Watch Mode](./watch-mode.md)
142

143
### Plugin System
144

145
Comprehensive hook-based plugin architecture for extending bundling behavior, with lifecycle hooks for input processing, transformation, and output generation.
146

147
```typescript { .api }
148
interface Plugin<A = any> extends OutputPlugin, Partial<PluginHooks> {
149
  name: string;
150
  version?: string;
151
  api?: A;
152
}
153

154
interface PluginContext extends MinimalPluginContext {
155
  addWatchFile: (id: string) => void;
156
  cache: PluginCache;
157
  emitFile: EmitFile;
158
  getFileName: (fileReferenceId: string) => string;
159
  getModuleIds: () => IterableIterator<string>;
160
  getModuleInfo: GetModuleInfo;
161
  resolve: (source: string, importer?: string, options?: ResolveOptions) => Promise<ResolvedId | null>;
162
  load: (options: LoadOptions) => Promise<ModuleInfo>;
163
  parse: ParseAst;
164
}
165
```
166

167
[Plugin System](./plugin-system.md)
168

169
### Utilities
170

171
AST parsing, logging, and debugging utilities for advanced use cases and tool development.
172

173
```typescript { .api }
174
function parseAst(
175
  input: string,
176
  options?: { allowReturnOutsideFunction?: boolean; jsx?: boolean }
177
): ProgramNode;
178

179
function parseAstAsync(
180
  input: string,
181
  options?: { allowReturnOutsideFunction?: boolean; jsx?: boolean; signal?: AbortSignal }
182
): Promise<ProgramNode>;
183

184
function getLogFilter(filters: string[]): (log: RollupLog) => boolean;
185

186
const VERSION: string;
187
```
188

189
[Utilities](./utilities.md)
190

191
## Core Types
192

193
```typescript { .api }
194
interface RollupOptions extends InputOptions {
195
  output?: OutputOptions | OutputOptions[];
196
}
197

198
interface InputOptions {
199
  input?: InputOption;
200
  external?: ExternalOption;
201
  plugins?: InputPluginOption;
202
  cache?: boolean | RollupCache;
203
  treeshake?: boolean | TreeshakingPreset | TreeshakingOptions;
204
  logLevel?: LogLevelOption;
205
  onLog?: LogHandlerWithDefault;
206
  watch?: WatcherOptions | false;
207
  context?: string;
208
  fs?: RollupFsModule;
209
  jsx?: false | JsxPreset | JsxOptions;
210
  moduleContext?: ((id: string) => string | null) | Record<string, string>;
211
  perf?: boolean;
212
  preserveEntrySignatures?: PreserveEntrySignaturesOption;
213
  preserveSymlinks?: boolean;
214
  shimMissingExports?: boolean;
215
  strictDeprecations?: boolean;
216
  experimentalCacheExpiry?: number;
217
  experimentalLogSideEffects?: boolean;
218
  makeAbsoluteExternalsRelative?: boolean | 'ifRelativeSource';
219
  maxParallelFileOps?: number;
220
}
221

222
interface OutputOptions {
223
  format?: ModuleFormat;
224
  file?: string;
225
  dir?: string;
226
  plugins?: OutputPluginOption;
227
  sourcemap?: boolean | 'inline' | 'hidden';
228
  globals?: GlobalsOption;
229
  banner?: string | AddonFunction;
230
  footer?: string | AddonFunction;
231
  intro?: string | AddonFunction;
232
  outro?: string | AddonFunction;
233
  amd?: AmdOptions;
234
  assetFileNames?: string | ((chunkInfo: PreRenderedAsset) => string);
235
  chunkFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
236
  compact?: boolean;
237
  dynamicImportInCjs?: boolean;
238
  entryFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
239
  esModule?: boolean | 'if-default-prop';
240
  experimentalMinChunkSize?: number;
241
  exports?: 'default' | 'named' | 'none' | 'auto';
242
  extend?: boolean;
243
  externalImportAttributes?: boolean;
244
  externalLiveBindings?: boolean;
245
  freeze?: boolean;
246
  generatedCode?: GeneratedCodePreset | GeneratedCodeOptions;
247
  hashCharacters?: HashCharacters;
248
  hoistTransitiveImports?: boolean;
249
  importAttributesKey?: ImportAttributesKey;
250
  indent?: string | boolean;
251
  inlineDynamicImports?: boolean;
252
  interop?: InteropType | GetInterop;
253
  manualChunks?: ManualChunksOption;
254
  minifyInternalExports?: boolean;
255
  name?: string;
256
  noConflict?: boolean;
257
  paths?: OptionsPaths;
258
  preserveModules?: boolean;
259
  preserveModulesRoot?: string;
260
  reexportProtoFromExternal?: boolean;
261
  sanitizeFileName?: boolean | ((fileName: string) => string);
262
  sourcemapBaseUrl?: string;
263
  sourcemapExcludeSources?: boolean;
264
  sourcemapFile?: string;
265
  sourcemapFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
266
  sourcemapIgnoreList?: boolean | SourcemapIgnoreListOption;
267
  sourcemapPathTransform?: SourcemapPathTransformOption;
268
  sourcemapDebugIds?: boolean;
269
  strict?: boolean;
270
  systemNullSetters?: boolean;
271
  validate?: boolean;
272
  virtualDirname?: string;
273
}
274

275
interface RollupOutput {
276
  output: [OutputChunk, ...(OutputChunk | OutputAsset)[]];
277
}
278

279
interface OutputChunk extends RenderedChunk {
280
  code: string;
281
  map: SourceMap | null;
282
  sourcemapFileName: string | null;
283
  preliminaryFileName: string;
284
}
285

286
interface OutputAsset extends PreRenderedAsset {
287
  fileName: string;
288
  needsCodeReference: boolean;
289
}
290

291
interface RollupCache {
292
  modules: ModuleJSON[];
293
  plugins?: Record<string, SerializablePluginCache>;
294
}
295

296
type ModuleFormat = 'amd' | 'cjs' | 'es' | 'iife' | 'system' | 'umd' | 'commonjs' | 'esm' | 'module' | 'systemjs';
297
type LogLevel = 'warn' | 'info' | 'debug';
298
type LogLevelOption = LogLevel | 'silent';
299
type ChangeEvent = 'create' | 'update' | 'delete';
300
type TreeshakingPreset = 'smallest' | 'safest' | 'recommended';
301
type JsxPreset = 'react' | 'react-jsx' | 'preserve' | 'preserve-react';
302
type PreserveEntrySignaturesOption = false | 'strict' | 'allow-extension' | 'exports-only';
303
type InteropType = 'compat' | 'auto' | 'esModule' | 'default' | 'defaultOnly';
304
type ImportAttributesKey = 'with' | 'assert';
305
type HashCharacters = 'base64' | 'base36' | 'hex';
306
type GeneratedCodePreset = 'es5' | 'es2015';
307
type InputOption = string | string[] | Record<string, string>;
308
type ExternalOption = (string | RegExp)[] | string | RegExp | ((source: string, importer: string | undefined, isResolved: boolean) => boolean | null);
309
type GlobalsOption = Record<string, string> | ((name: string) => string);
310
type ManualChunksOption = Record<string, string[]> | GetManualChunk;
311
type GetManualChunk = (id: string, meta: ManualChunkMeta) => string | null;
312
type AddonFunction = (chunk: RenderedChunk) => string | Promise<string>;
313
type SerializablePluginCache = Record<string, [number, any]>;
314
type SerializedTimings = Record<string, [number, number, number]>;
315
type InputPluginOption = MaybePromise<Plugin | null | false | InputPluginOption[]>;
316
type OutputPluginOption = MaybePromise<OutputPlugin | null | false | OutputPluginOption[]>;
317
type LogHandlerWithDefault = (level: LogLevel, log: RollupLog, defaultHandler: LogOrStringHandler) => void;
318
type MaybePromise<T> = T | Promise<T>;
319
```