0
# Core Bundling
1

2
Core bundling functions and compiler creation for building JavaScript applications with webpack-compatible API.
3

4
## Capabilities
5

6
### Main Bundling Function
7

8
Creates a compiler or multi-compiler instance for building applications.
9

10
```typescript { .api }
11
/**
12
 * Create a compiler instance for building applications
13
 * @param options - Build configuration options
14
 * @returns Compiler instance for single config or MultiCompiler for array
15
 */
16
function rspack(options: Configuration): Compiler;
17
function rspack(options: Configuration[]): MultiCompiler;
18
function rspack(
19
  options: Configuration | Configuration[],
20
  callback: (err: Error | null, stats?: Stats | MultiStats) => void
21
): Compiler | MultiCompiler | null;
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import rspack from "@rspack/core";
28

29
// Single configuration
30
const compiler = rspack({
31
  entry: "./src/index.js",
32
  output: {
33
    path: "./dist",
34
    filename: "bundle.js"
35
  },
36
  mode: "production"
37
});
38

39
// Multiple configurations
40
const multiCompiler = rspack([
41
  { entry: "./src/app.js", output: { filename: "app.js" } },
42
  { entry: "./src/worker.js", output: { filename: "worker.js" } }
43
]);
44

45
// With callback for immediate execution
46
rspack(config, (err, stats) => {
47
  if (err) {
48
    console.error("Build failed:", err);
49
    return;
50
  }
51
  console.log("Build completed:", stats?.toString());
52
});
53
```
54

55
### Compiler Creation
56

57
Direct compiler creation functions for advanced use cases.
58

59
```typescript { .api }
60
/**
61
 * Create a single compiler instance
62
 * @param options - Configuration for the compiler
63
 * @returns Compiler instance
64
 */
65
function createCompiler(options: Configuration): Compiler;
66

67
/**
68
 * Create a multi-compiler for multiple configurations
69
 * @param options - Array of configurations
70
 * @returns MultiCompiler instance managing multiple compilers
71
 */
72
function createMultiCompiler(options: Configuration[]): MultiCompiler;
73
```
74

75
### Compiler Class
76

77
Main compilation controller managing the build process and plugin system.
78

79
```typescript { .api }
80
class Compiler {
81
  /** Full build configuration options */
82
  options: Configuration;
83
  /** Tapable hooks system for plugin integration */
84
  hooks: CompilerHooks;
85
  /** Output directory path */
86
  outputPath: string;
87
  /** Optional compiler name for multi-compiler setups */
88
  name?: string;
89
  /** Input file system interface */
90
  inputFileSystem?: any;
91
  /** Output file system interface */  
92
  outputFileSystem?: any;
93
  /** Watch file system interface */
94
  watchFileSystem?: any;
95

96
  /**
97
   * Execute a single build
98
   * @param callback - Called when build completes or fails
99
   */
100
  run(callback: (err: Error | null, stats?: Stats) => void): void;
101

102
  /**
103
   * Start watch mode for continuous building
104
   * @param options - Watch configuration options
105
   * @param callback - Called on each build completion
106
   * @returns Watching instance for controlling watch mode
107
   */
108
  watch(
109
    options: WatchOptions,
110
    callback: (err: Error | null, stats?: Stats) => void
111
  ): Watching;
112

113
  /**
114
   * Close the compiler and cleanup resources
115
   * @param callback - Called when cleanup is complete
116
   */
117
  close(callback: () => void): void;
118

119
  /**
120
   * Create a new compilation instance
121
   * @returns Compilation instance for this build
122
   */
123
  createCompilation(): Compilation;
124
}
125
```
126

127
**Usage Examples:**
128

129
```typescript
130
import { createCompiler } from "@rspack/core";
131

132
const compiler = createCompiler({
133
  entry: "./src/index.js",
134
  output: { path: "./dist", filename: "bundle.js" },
135
  mode: "development"
136
});
137

138
// Single build
139
compiler.run((err, stats) => {
140
  if (err) {
141
    console.error("Compilation failed:", err);
142
    return;
143
  }
144
  
145
  if (stats?.hasErrors()) {
146
    console.error("Build errors:", stats.toJson().errors);
147
    return;
148
  }
149
  
150
  console.log("Build successful!");
151
  compiler.close(() => {
152
    console.log("Compiler closed");
153
  });
154
});
155

156
// Watch mode
157
const watching = compiler.watch({
158
  aggregateTimeout: 300,
159
  poll: undefined
160
}, (err, stats) => {
161
  console.log("Build completed at", new Date().toISOString());
162
});
163

164
// Stop watching
165
watching.close(() => {
166
  console.log("Watching stopped");
167
});
168
```
169

170
### MultiCompiler Class
171

172
Manages multiple parallel or sequential compilations.
173

174
```typescript { .api }
175
class MultiCompiler {
176
  /** Array of individual compilers */
177
  compilers: Compiler[];
178
  /** Multi-compiler specific hooks */
179
  hooks: MultiCompilerHooks;
180

181
  /**
182
   * Run all compilers
183
   * @param callback - Called when all builds complete
184
   */
185
  run(callback: (err: Error | null, stats?: MultiStats) => void): void;
186

187
  /**
188
   * Start watch mode for all compilers
189
   * @param options - Watch options for each compiler
190
   * @param callback - Called on each build completion
191
   * @returns MultiWatching instance
192
   */
193
  watch(
194
    options: WatchOptions | WatchOptions[],
195
    callback: (err: Error | null, stats?: MultiStats) => void
196
  ): MultiWatching;
197

198
  /**
199
   * Set dependencies between compilers
200
   * @param compiler - Dependent compiler
201
   * @param dependencies - Array of compiler names it depends on
202
   */
203
  setDependencies(compiler: Compiler, dependencies: string[]): void;
204
}
205
```
206

207
### Stats Classes
208

209
Build statistics and reporting.
210

211
```typescript { .api }
212
class Stats {
213
  /** Associated compilation instance */
214
  compilation: Compilation;
215

216
  /**
217
   * Convert stats to formatted string
218
   * @param options - Formatting options
219
   * @returns Formatted build statistics
220
   */
221
  toString(options?: StatsOptions): string;
222

223
  /**
224
   * Convert stats to JSON object
225
   * @param options - Serialization options  
226
   * @returns Build statistics as JSON
227
   */
228
  toJson(options?: StatsOptions): StatsCompilation;
229

230
  /**
231
   * Check if build has errors
232
   * @returns True if compilation has errors
233
   */
234
  hasErrors(): boolean;
235

236
  /**
237
   * Check if build has warnings
238
   * @returns True if compilation has warnings
239
   */
240
  hasWarnings(): boolean;
241
}
242

243
class MultiStats {
244
  /** Array of individual stats */
245
  stats: Stats[];
246

247
  /**
248
   * Convert all stats to formatted string
249
   * @param options - Formatting options
250
   * @returns Formatted multi-build statistics
251
   */
252
  toString(options?: StatsOptions): string;
253

254
  /**
255
   * Convert all stats to JSON
256
   * @param options - Serialization options
257
   * @returns Multi-build statistics as JSON
258
   */
259
  toJson(options?: StatsOptions): any;
260

261
  /**
262
   * Check if any build has errors
263
   * @returns True if any compilation has errors
264
   */
265
  hasErrors(): boolean;
266

267
  /**
268
   * Check if any build has warnings  
269
   * @returns True if any compilation has warnings
270
   */
271
  hasWarnings(): boolean;
272
}
273
```
274

275
### Support Types
276

277
```typescript { .api }
278
interface WatchOptions {
279
  /** Delay before rebuilding after change detected */
280
  aggregateTimeout?: number;
281
  /** Polling interval in milliseconds (for polling mode) */
282
  poll?: boolean | number;
283
  /** Ignore files/directories for watching */
284
  ignored?: string | RegExp | (string | RegExp)[];
285
}
286

287
interface Watching {
288
  /** Stop watching and cleanup */
289
  close(callback: () => void): void;
290
  /** Invalidate current build and trigger rebuild */
291
  invalidate(): void;
292
}
293

294
interface MultiWatching {
295
  /** Stop all watching and cleanup */
296
  close(callback: () => void): void;
297
  /** Invalidate all builds and trigger rebuilds */
298
  invalidate(): void;
299
}
300

301
interface StatsOptions {
302
  /** Include asset information */
303
  assets?: boolean;
304
  /** Include chunk information */
305
  chunks?: boolean;
306
  /** Include module information */
307
  modules?: boolean;
308
  /** Include error details */
309
  errors?: boolean;
310
  /** Include warning details */
311
  warnings?: boolean;
312
  /** Color output */
313
  colors?: boolean;
314
  /** Preset configuration */
315
  preset?: "none" | "minimal" | "normal" | "detailed" | "verbose";
316
}
317
```