0
# Rsbuild Core
1

2
Rsbuild is a high-performance build tool powered by Rspack that provides a comprehensive solution for modern web development. It serves as a modernized alternative to Create React App or Vue CLI with significantly improved build performance through its Rust-based Rspack bundler. The tool offers out-of-the-box support for TypeScript, JSX, Sass, Less, CSS Modules, and other modern web technologies, while maintaining compatibility with the webpack ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @rsbuild/core
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rsbuild/core`
10

11
## Core Imports
12

13
```typescript
14
import { createRsbuild, defineConfig, loadConfig, loadEnv } from "@rsbuild/core";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { createRsbuild, defineConfig, loadConfig, loadEnv } = require("@rsbuild/core");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { createRsbuild, defineConfig } from "@rsbuild/core";
27

28
// Define configuration
29
const config = defineConfig({
30
  source: {
31
    entry: {
32
      index: "./src/index.ts",
33
    },
34
  },
35
  output: {
36
    target: "web",
37
  },
38
  dev: {
39
    hmr: true,
40
  },
41
});
42

43
// Create Rsbuild instance
44
const rsbuild = await createRsbuild({ rsbuildConfig: config });
45

46
// Start development server 
47
await rsbuild.startDevServer();
48

49
// Or build for production
50
await rsbuild.build();
51
```
52

53
## Architecture
54

55
Rsbuild is built around several key components:
56

57
- **Core Instance**: `RsbuildInstance` providing build and dev server methods with lifecycle hooks
58
- **Configuration System**: Type-safe configuration with environment-specific overrides
59
- **Plugin System**: Extensible architecture with comprehensive lifecycle hooks and plugin communication
60
- **Provider System**: Bundler abstraction supporting both Rspack and Webpack
61
- **Multi-Environment Support**: Build multiple targets simultaneously with different configurations
62
- **Development Server**: Hot module replacement, live reload, and debugging capabilities
63

64
## Capabilities
65

66
### Core Build System
67

68
Primary Rsbuild instance creation and build orchestration. Provides production builds, development server, and configuration management.
69

70
```typescript { .api }
71
function createRsbuild(options?: CreateRsbuildOptions): Promise<RsbuildInstance>;
72

73
interface CreateRsbuildOptions {
74
  cwd?: string;
75
  rsbuildConfig?: RsbuildConfig | (() => Promise<RsbuildConfig>);
76
  environment?: string[];
77
  callerName?: string;
78
  loadEnv?: boolean | LoadEnvOptions;
79
}
80

81
interface RsbuildInstance {
82
  build(options?: BuildOptions): Promise<{
83
    close: () => Promise<void>;
84
    stats?: Rspack.Stats | Rspack.MultiStats;
85
  }>;
86
  preview(): Promise<void>;
87
  startDevServer(options?: StartDevServerOptions): Promise<StartServerResult>;
88
  createDevServer(): Promise<RsbuildDevServer>;
89
  createCompiler(): Promise<Compiler>;
90
  initConfigs(): Promise<InitConfigsResult>;
91
  inspectConfig(options?: InspectConfigOptions): Promise<InspectConfigResult>;
92
  addPlugins(plugins: RsbuildPlugins): void;
93
  removePlugins(pluginNames: string[]): void;
94
  getPlugins(): RsbuildPlugin[];
95
  isPluginExists(pluginName: string, options?: { environment?: string }): boolean;
96
}
97
```
98

99
[Core Build System](./core-build-system.md)
100

101
### Configuration Management
102

103
Configuration loading, definition, and merging utilities. Handles both file-based and programmatic configuration.
104

105
```typescript { .api }
106
function defineConfig(config: RsbuildConfig): RsbuildConfig;
107
function loadConfig(options?: LoadConfigOptions): Promise<LoadConfigResult>;
108
function mergeRsbuildConfig(...configs: RsbuildConfig[]): RsbuildConfig;
109

110
interface LoadConfigOptions {
111
  cwd?: string;
112
  path?: string;
113
  meta?: Record<string, unknown>;
114
  envMode?: string;
115
  configLoader?: 'jiti' | 'native';
116
}
117
```
118

119
[Configuration Management](./configuration-management.md)
120

121
### Plugin System
122

123
Comprehensive plugin architecture with lifecycle hooks, configuration modification, and inter-plugin communication.
124

125
```typescript { .api }
126
interface RsbuildPlugin {
127
  name: string;
128
  setup: (api: RsbuildPluginAPI) => MaybePromise<void>;
129
  apply?: 'serve' | 'build' | ((config: any, context: any) => boolean);
130
  enforce?: 'pre' | 'post';
131
  pre?: string[];
132
  post?: string[];
133
  remove?: string[];
134
}
135

136
interface RsbuildPluginAPI {
137
  context: RsbuildContext;
138
  logger: Logger;
139
  modifyRsbuildConfig: ModifyRsbuildConfigHook;
140
  modifyEnvironmentConfig: ModifyEnvironmentConfigHook;
141
  modifyBundlerChain: ModifyBundlerChainHook;
142
  modifyRspackConfig: ModifyRspackConfigHook;
143
  transform: TransformHook;
144
  processAssets: ProcessAssetsHook;
145
  expose: <T = any>(id: string, api: T) => void;
146
  useExposed: <T = any>(id: string) => T | undefined;
147
}
148
```
149

150
[Plugin System](./plugin-system.md)
151

152
### Development Server
153

154
Development server functionality with hot module replacement, live reload, and debugging capabilities.
155

156
```typescript { .api }
157
interface RsbuildDevServer {
158
  listen(): Promise<void>;
159
  close(): Promise<void>;
160
  server: Connect.Server;
161
  port: number;
162
  host: string;
163
}
164

165
interface StartServerResult {
166
  urls: string[];
167
  port: number;
168
  server: RsbuildDevServer;
169
}
170
```
171

172
[Development Server](./development-server.md)
173

174
### Environment System
175

176
Multi-environment build support allowing simultaneous builds for different targets with environment-specific configurations.
177

178
```typescript { .api }
179
interface EnvironmentConfig {
180
  source?: SourceConfig;
181
  output?: OutputConfig;
182
  html?: HtmlConfig;
183
  tools?: ToolsConfig;
184
  dev?: DevConfig;
185
  server?: ServerConfig;
186
  security?: SecurityConfig;
187
  performance?: PerformanceConfig;
188
  moduleFederation?: ModuleFederationConfig;
189
}
190

191
interface EnvironmentContext {
192
  name: string;
193
  index: number;
194
  entry: RsbuildEntry;
195
  htmlPaths: Record<string, string>;
196
  distPath: string;
197
  browserslist: string[];
198
  config: NormalizedEnvironmentConfig;
199
}
200
```
201

202
[Environment System](./environment-system.md)
203

204
### CLI Integration
205

206
Command-line interface functionality for build scripts and development workflows.
207

208
```typescript { .api }
209
function runCLI(): Promise<void>;
210
```
211

212
[CLI Integration](./cli-integration.md)
213

214
### Environment Variables
215

216
Environment variable loading and management from .env files with mode-specific support.
217

218
```typescript { .api }
219
function loadEnv(options?: LoadEnvOptions): LoadEnvResult;
220

221
interface LoadEnvOptions {
222
  cwd?: string;
223
  mode?: string;
224
  prefixes?: string[];
225
  processEnv?: Record<string, string>;
226
}
227

228
interface LoadEnvResult {
229
  parsed: Record<string, string>;
230
  filePaths: string[];
231
  rawPublicVars: Record<string, string | undefined>;
232
  publicVars: Record<string, string>;
233
  cleanup: () => void;
234
}
235
```
236

237
[Environment Variables](./environment-variables.md)
238

239
## Core Types
240

241
```typescript { .api }
242
interface RsbuildConfig {
243
  mode?: 'development' | 'production' | 'none';
244
  root?: string;
245
  logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
246
  environments?: Record<string, EnvironmentConfig>;
247
  source?: SourceConfig;
248
  output?: OutputConfig;
249
  html?: HtmlConfig;
250
  tools?: ToolsConfig;
251
  dev?: DevConfig;
252
  server?: ServerConfig;
253
  security?: SecurityConfig;
254
  performance?: PerformanceConfig;
255
  moduleFederation?: ModuleFederationConfig;
256
  plugins?: RsbuildPlugins;
257
  provider?: unknown;
258
}
259

260
interface RsbuildContext {
261
  entry: RsbuildEntry;
262
  target: RsbuildTarget;
263
  mode: RsbuildMode;
264
  rootPath: string;
265
  distPath: string;
266
  cachePath: string;
267
  configPath?: string;
268
  bundlerType: 'rspack' | 'webpack';
269
}
270

271
type RsbuildTarget = 'web' | 'node' | 'web-worker';
272
type RsbuildMode = 'development' | 'production' | 'none';
273
type RsbuildEntry = string | string[] | Record<string, string | string[] | RsbuildEntryDescription>;
274
type RsbuildPlugins = (RsbuildPlugin | RsbuildPluginOptions)[];
275

276
interface RsbuildEntryDescription {
277
  import: string | string[];
278
  filename?: string;
279
  runtime?: string;
280
  publicPath?: string;
281
}
282

283
interface Logger {
284
  info(...args: unknown[]): void;
285
  warn(...args: unknown[]): void;
286
  error(...args: unknown[]): void;
287
  success(...args: unknown[]): void;
288
  debug(...args: unknown[]): void;
289
  ready(...args: unknown[]): void;
290
}
291
```
292

293
## Constants
294

295
```typescript { .api }
296
const version: string;
297
const PLUGIN_CSS_NAME = 'rsbuild:css';
298
const PLUGIN_SWC_NAME = 'rsbuild:swc';
299
const defaultAllowedOrigins: RegExp;
300
```
301

302
## Utilities
303

304
```typescript { .api }
305
function ensureAssetPrefix(url: string, assetPrefix?: string): string;
306
const logger: Logger;
307
const rspack: typeof import('@rspack/core');
308
type Rspack = typeof import('@rspack/core');
309
```