0
# Core Build System
1

2
Primary Rsbuild instance creation and build orchestration functionality. Provides production builds, development server creation, and configuration management with comprehensive lifecycle hooks.
3

4
## Capabilities
5

6
### Create Rsbuild Instance
7

8
Creates and configures a new Rsbuild instance with optional configuration and environment settings.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Rsbuild instance with the provided configuration
13
 * @param options - Configuration options for the Rsbuild instance
14
 * @returns Promise resolving to configured RsbuildInstance
15
 */
16
function createRsbuild(options?: CreateRsbuildOptions): Promise<RsbuildInstance>;
17

18
interface CreateRsbuildOptions {
19
  /** Project root directory */
20
  cwd?: string;
21
  /** Rsbuild configuration object or function */
22
  rsbuildConfig?: RsbuildConfig | (() => Promise<RsbuildConfig>);
23
  /** Specific environments to build */
24
  environment?: string[];
25
  /** Framework or tool name invoking Rsbuild */
26
  callerName?: string;
27
  /** Environment variable loading configuration */
28
  loadEnv?: boolean | LoadEnvOptions;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { createRsbuild } from "@rsbuild/core";
36

37
// Basic instance creation
38
const rsbuild = await createRsbuild();
39

40
// With configuration
41
const rsbuild = await createRsbuild({
42
  rsbuildConfig: {
43
    source: { entry: { index: "./src/index.ts" } },
44
    output: { target: "web" },
45
  },
46
});
47

48
// With async configuration
49
const rsbuild = await createRsbuild({
50
  rsbuildConfig: async () => {
51
    const config = await loadConfigFromDatabase();
52
    return config;
53
  },
54
});
55
```
56

57
### Build for Production
58

59
Executes a production build with optimizations, minification, and asset generation.
60

61
```typescript { .api }
62
/**
63
 * Execute production build
64
 * @param options - Build options
65
 * @returns Promise resolving to build result with close function and stats
66
 */
67
build(options?: BuildOptions): Promise<{
68
  close: () => Promise<void>;
69
  stats?: Rspack.Stats | Rspack.MultiStats;
70
}>;
71

72
interface BuildOptions {
73
  /** Watch mode for continuous builds */
74
  watch?: boolean;
75
  /** Compiler options */
76
  compiler?: any;
77
}
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
const rsbuild = await createRsbuild({ rsbuildConfig: config });
84

85
// Build for production
86
await rsbuild.build();
87
```
88

89
### Preview Production Build
90

91
Starts a local server to preview the production build output.
92

93
```typescript { .api }
94
/**
95
 * Preview production build locally
96
 * @returns Promise that resolves when preview server starts
97
 */
98
preview(): Promise<void>;
99
```
100

101
### Start Development Server
102

103
Starts the development server with hot module replacement and live reload capabilities.
104

105
```typescript { .api }
106
/**
107
 * Start development server with HMR and live reload
108
 * @param options - Development server configuration options
109
 * @returns Promise resolving to server information
110
 */
111
startDevServer(options?: StartDevServerOptions): Promise<StartServerResult>;
112

113
interface StartDevServerOptions {
114
  /** Whether to automatically open browser */
115
  open?: boolean;
116
  /** Custom port number */
117
  port?: number;
118
  /** Custom host address */
119
  host?: string;
120
  /** Enable HTTPS */
121
  https?: boolean;
122
  /** Print server URLs */
123
  printUrls?: boolean | PrintUrls;
124
}
125

126
interface StartServerResult {
127
  /** Server URLs (local and network) */
128
  urls: string[];
129
  /** Server port number */
130
  port: number;
131
  /** Development server instance */
132
  server: RsbuildDevServer;
133
}
134

135
interface PrintUrls {
136
  local: boolean;
137
  network: boolean;
138
}
139
```
140

141
### Create Development Server
142

143
Creates a development server instance without starting it, allowing for custom configuration.
144

145
```typescript { .api }
146
/**
147
 * Create development server instance without starting
148
 * @returns Promise resolving to development server instance
149
 */
150
createDevServer(): Promise<RsbuildDevServer>;
151
```
152

153
### Create Compiler
154

155
Creates the underlying bundler compiler instance (Rspack or Webpack).
156

157
```typescript { .api }
158
/**
159
 * Create bundler compiler instance
160
 * @returns Promise resolving to compiler instance
161
 */
162
createCompiler(): Promise<Compiler>;
163

164
interface Compiler {
165
  /** Run a single build */
166
  run(): Promise<void>;
167
  /** Start watching for changes */
168
  watch(): Promise<void>;
169
  /** Close the compiler */
170
  close(): Promise<void>;
171
}
172
```
173

174
### Initialize Configurations
175

176
Initializes and returns the internal bundler configurations for all environments.
177

178
```typescript { .api }
179
/**
180
 * Initialize internal bundler configurations
181
 * @returns Promise resolving to configuration initialization results
182
 */
183
initConfigs(): Promise<InitConfigsResult>;
184

185
interface InitConfigsResult {
186
  /** Rspack configurations by environment */
187
  rspackConfigs: RspackConfig[];
188
  /** Environment contexts */
189
  environments: EnvironmentContext[];
190
}
191
```
192

193
### Inspect Configuration
194

195
Debug and inspect the resolved configurations for troubleshooting and development.
196

197
```typescript { .api }
198
/**
199
 * Inspect resolved configurations for debugging
200
 * @param options - Inspection options
201
 * @returns Promise resolving to inspection results
202
 */
203
inspectConfig(options?: InspectConfigOptions): Promise<InspectConfigResult>;
204

205
interface InspectConfigOptions {
206
  /** Environment to inspect */
207
  env?: string;
208
  /** Output format */
209
  outputPath?: string;
210
  /** Verbose output */
211
  verbose?: boolean;
212
  /** Write to file */
213
  writeToFile?: boolean;
214
}
215

216
interface InspectConfigResult {
217
  /** Rsbuild configuration */
218
  rsbuildConfig: string;
219
  /** Rspack configurations */
220
  rspackConfigs: string[];
221
  /** Environment configurations */
222
  environmentConfigs: Record<string, string>;
223
  /** Bundle analyzer data */
224
  bundlerConfigs: Record<string, string>;
225
}
226
```
227

228
## Plugin Management
229

230
### Add Plugins
231

232
Adds one or more plugins to the Rsbuild instance.
233

234
```typescript { .api }
235
/**
236
 * Add plugins to the Rsbuild instance
237
 * @param plugins - Plugin instances or configurations to add
238
 */
239
addPlugins(plugins: RsbuildPlugins): void;
240
```
241

242
### Remove Plugins
243

244
Removes plugins from the Rsbuild instance by name.
245

246
```typescript { .api }
247
/**
248
 * Remove plugins by name
249
 * @param pluginNames - Names of plugins to remove
250
 */
251
removePlugins(pluginNames: string[]): void;
252
```
253

254
### Get Plugins
255

256
Retrieves all registered plugins.
257

258
```typescript { .api }
259
/**
260
 * Get all registered plugins
261
 * @returns Array of registered plugin instances
262
 */
263
getPlugins(): RsbuildPlugin[];
264
```
265

266
### Check Plugin Existence
267

268
Checks if a plugin with the given name is registered, optionally within a specific environment.
269

270
```typescript { .api }
271
/**
272
 * Check if plugin exists by name
273
 * @param pluginName - Name of plugin to check
274
 * @param options - Options including environment specification
275
 * @returns True if plugin is registered
276
 */
277
isPluginExists(pluginName: string, options?: { environment?: string }): boolean;
278
```
279

280
## Configuration Access
281

282
### Get Rsbuild Configuration
283

284
Retrieves the current Rsbuild configuration.
285

286
```typescript { .api }
287
/**
288
 * Get current Rsbuild configuration
289
 * @returns Current Rsbuild configuration object
290
 */
291
getRsbuildConfig(): RsbuildConfig;
292
```
293

294
### Get Normalized Configuration
295

296
Retrieves the normalized configuration with defaults applied.
297

298
```typescript { .api }
299
/**
300
 * Get normalized configuration with defaults
301
 * @returns Normalized configuration object
302
 */
303
getNormalizedConfig(): NormalizedConfig;
304
```
305

306
### Modify Rsbuild Configuration
307

308
Modifies the Rsbuild configuration using a callback function.
309

310
```typescript { .api }
311
/**
312
 * Modify Rsbuild configuration
313
 * @param fn - Function to modify configuration
314
 */
315
modifyRsbuildConfig(fn: ModifyRsbuildConfigFn): void;
316

317
type ModifyRsbuildConfigFn = (
318
  config: RsbuildConfig,
319
  utils: ModifyRsbuildConfigUtils
320
) => RsbuildConfig | void | Promise<RsbuildConfig | void>;
321

322
interface ModifyRsbuildConfigUtils {
323
  mergeConfig: typeof mergeRsbuildConfig;
324
}
325
```
326

327
### Modify Environment Configuration
328

329
Modifies environment-specific configuration.
330

331
```typescript { .api }
332
/**
333
 * Modify environment-specific configuration
334
 * @param fn - Function to modify environment configuration
335
 */
336
modifyEnvironmentConfig(fn: ModifyEnvironmentConfigFn): void;
337

338
type ModifyEnvironmentConfigFn = (
339
  config: EnvironmentConfig,
340
  utils: ModifyEnvironmentConfigUtils
341
) => EnvironmentConfig | void | Promise<EnvironmentConfig | void>;
342

343
interface ModifyEnvironmentConfigUtils {
344
  name: string;
345
  mergeConfig: (config: EnvironmentConfig) => EnvironmentConfig;
346
}
347
```
348

349
## Lifecycle Hooks
350

351
### Build Lifecycle
352

353
```typescript { .api }
354
/**
355
 * Hook called before production build starts
356
 * @param fn - Callback function
357
 */
358
onBeforeBuild(fn: OnBeforeBuildFn): void;
359

360
/**
361
 * Hook called after production build completes
362
 * @param fn - Callback function
363
 */
364
onAfterBuild(fn: OnAfterBuildFn): void;
365

366
/**
367
 * Hook called when build process closes
368
 * @param fn - Callback function
369
 */
370
onCloseBuild(fn: OnCloseBuildFn): void;
371

372
type OnBeforeBuildFn = (params: { environments: EnvironmentContext[] }) => void | Promise<void>;
373
type OnAfterBuildFn = (params: { environments: EnvironmentContext[]; stats: BuildStats }) => void | Promise<void>;
374
type OnCloseBuildFn = () => void | Promise<void>;
375
```
376

377
### Development Lifecycle
378

379
```typescript { .api }
380
/**
381
 * Hook called before development compilation
382
 * @param fn - Callback function
383
 */
384
onBeforeDevCompile(fn: OnBeforeDevCompileFn): void;
385

386
/**
387
 * Hook called after development compilation
388
 * @param fn - Callback function
389
 */
390
onAfterDevCompile(fn: OnAfterDevCompileFn): void;
391

392
/**
393
 * Hook called when development compilation completes successfully
394
 * @param fn - Callback function
395
 */
396
onDevCompileDone(fn: OnDevCompileDoneFn): void;
397

398
type OnBeforeDevCompileFn = (params: { environments: EnvironmentContext[] }) => void | Promise<void>;
399
type OnAfterDevCompileFn = (params: { environments: EnvironmentContext[]; stats: DevStats }) => void | Promise<void>;
400
type OnDevCompileDoneFn = (params: { environments: EnvironmentContext[]; stats: DevStats }) => void | Promise<void>;
401
```
402

403
### Server Lifecycle
404

405
```typescript { .api }
406
/**
407
 * Hook called before development server starts
408
 * @param fn - Callback function
409
 */
410
onBeforeStartDevServer(fn: OnBeforeStartDevServerFn): void;
411

412
/**
413
 * Hook called after development server starts
414
 * @param fn - Callback function
415
 */
416
onAfterStartDevServer(fn: OnAfterStartDevServerFn): void;
417

418
/**
419
 * Hook called when development server closes
420
 * @param fn - Callback function
421
 */
422
onCloseDevServer(fn: OnCloseDevServerFn): void;
423

424
type OnBeforeStartDevServerFn = (params: { port: number; host: string }) => void | Promise<void>;
425
type OnAfterStartDevServerFn = (params: { port: number; host: string; urls: string[] }) => void | Promise<void>;
426
type OnCloseDevServerFn = () => void | Promise<void>;
427
```
428

429
### Compiler Lifecycle
430

431
```typescript { .api }
432
/**
433
 * Hook called before compiler creation
434
 * @param fn - Callback function
435
 */
436
onBeforeCreateCompiler(fn: OnBeforeCreateCompilerFn): void;
437

438
/**
439
 * Hook called after compiler creation
440
 * @param fn - Callback function
441
 */
442
onAfterCreateCompiler(fn: OnAfterCreateCompilerFn): void;
443

444
type OnBeforeCreateCompilerFn = (params: { environments: EnvironmentContext[] }) => void | Promise<void>;
445
type OnAfterCreateCompilerFn = (params: { compiler: Compiler; environments: EnvironmentContext[] }) => void | Promise<void>;
446
```
447

448
### Process Lifecycle
449

450
```typescript { .api }
451
/**
452
 * Hook called on process exit
453
 * @param fn - Callback function
454
 */
455
onExit(fn: OnExitFn): void;
456

457
type OnExitFn = () => void | Promise<void>;
458
```
459

460
## Core Types
461

462
```typescript { .api }
463
interface RsbuildInstance {
464
  // Build methods
465
  build(options?: BuildOptions): Promise<{
466
    close: () => Promise<void>;
467
    stats?: Rspack.Stats | Rspack.MultiStats;
468
  }>;
469
  preview(): Promise<void>;
470
  startDevServer(options?: StartDevServerOptions): Promise<StartServerResult>;
471
  createDevServer(): Promise<RsbuildDevServer>;
472
  createCompiler(): Promise<Compiler>;
473
  initConfigs(): Promise<InitConfigsResult>;
474
  inspectConfig(options?: InspectConfigOptions): Promise<InspectConfigResult>;
475
  
476
  // Plugin management
477
  addPlugins(plugins: RsbuildPlugins): void;
478
  removePlugins(pluginNames: string[]): void;
479
  getPlugins(): RsbuildPlugin[];
480
  isPluginExists(pluginName: string, options?: { environment?: string }): boolean;
481
  
482
  // Configuration access
483
  getRsbuildConfig(): RsbuildConfig;
484
  getNormalizedConfig(): NormalizedConfig;
485
  modifyRsbuildConfig(fn: ModifyRsbuildConfigFn): void;
486
  modifyEnvironmentConfig(fn: ModifyEnvironmentConfigFn): void;
487
  
488
  // Lifecycle hooks
489
  onBeforeBuild(fn: OnBeforeBuildFn): void;
490
  onAfterBuild(fn: OnAfterBuildFn): void;
491
  onCloseBuild(fn: OnCloseBuildFn): void;
492
  onBeforeDevCompile(fn: OnBeforeDevCompileFn): void;
493
  onAfterDevCompile(fn: OnAfterDevCompileFn): void;
494
  onDevCompileDone(fn: OnDevCompileDoneFn): void;
495
  onBeforeStartDevServer(fn: OnBeforeStartDevServerFn): void;
496
  onAfterStartDevServer(fn: OnAfterStartDevServerFn): void;
497
  onCloseDevServer(fn: OnCloseDevServerFn): void;
498
  onBeforeCreateCompiler(fn: OnBeforeCreateCompilerFn): void;
499
  onAfterCreateCompiler(fn: OnAfterCreateCompilerFn): void;
500
  onExit(fn: OnExitFn): void;
501
}
502

503
interface BuildStats {
504
  hasErrors: boolean;
505
  hasWarnings: boolean;
506
  toJson(): any;
507
}
508

509
interface DevStats extends BuildStats {
510
  compilation: any;
511
}
512
```