0
# Build System
1

2
Core build functionality for compiling library projects using Rsbuild as the underlying build system. Supports multiple output formats, TypeScript compilation, and advanced features like Module Federation.
3

4
## Capabilities
5

6
### Build Function
7

8
Main build function that compiles library projects using Rsbuild with support for multiple output formats.
9

10
```typescript { .api }
11
/**
12
 * Main build function that compiles library projects using Rsbuild
13
 * @param config - Rslib configuration object
14
 * @param options - Build options including watch mode and library selection
15
 * @returns Promise resolving to Rsbuild instance
16
 */
17
function build(config: RslibConfig, options?: BuildOptions): Promise<RsbuildInstance>;
18

19
interface BuildOptions extends CommonOptions {
20
  /** Enable watch mode for automatic rebuilds */
21
  watch?: boolean;
22
}
23
```
24

25
**Usage Examples:**
26

27
```typescript
28
import { build, loadConfig } from "@rslib/core";
29

30
// Basic build
31
const { content: config } = await loadConfig();
32
const rsbuildInstance = await build(config);
33

34
// Build with watch mode
35
await build(config, { watch: true });
36

37
// Build specific libraries only
38
await build(config, { lib: ["esm", "cjs"] });
39
```
40

41
### Inspect Function
42

43
Inspects and analyzes the generated bundle configuration without actually building.
44

45
```typescript { .api }
46
/**
47
 * Inspects and analyzes the generated bundle configuration
48
 * @param config - Rslib configuration object
49
 * @param options - Inspection options including mode and output settings
50
 * @returns Promise resolving to Rsbuild instance
51
 */
52
function inspect(config: RslibConfig, options?: InspectOptions): Promise<RsbuildInstance>;
53

54
interface InspectOptions extends CommonOptions {
55
  /** Build mode (development or production) */
56
  mode?: RsbuildMode;
57
  /** Output directory for inspection results */
58
  output?: string;
59
  /** Enable verbose output */
60
  verbose?: boolean;
61
}
62
```
63

64
**Usage Examples:**
65

66
```typescript
67
import { inspect, loadConfig } from "@rslib/core";
68

69
// Basic inspection
70
const { content: config } = await loadConfig();
71
await inspect(config);
72

73
// Inspect with verbose output
74
await inspect(config, { 
75
  verbose: true,
76
  mode: 'development',
77
  output: './inspect-output'
78
});
79
```
80

81
### Module Federation Dev Server
82

83
Starts Module Federation development server for MF format builds.
84

85
```typescript { .api }
86
/**
87
 * Starts Module Federation development server for MF format builds
88
 * @param config - Rslib configuration object
89
 * @param options - Common CLI options including library selection
90
 * @returns Promise resolving to Rsbuild instance or undefined
91
 */
92
function startMFDevServer(
93
  config: RslibConfig, 
94
  options?: CommonOptions
95
): Promise<RsbuildInstance | undefined>;
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { startMFDevServer, loadConfig } from "@rslib/core";
102

103
// Start MF dev server
104
const { content: config } = await loadConfig();
105
const server = await startMFDevServer(config);
106

107
// Start with specific library
108
await startMFDevServer(config, { lib: ["mf"] });
109
```
110

111
## Build Configuration
112

113
### Output Formats
114

115
Supported output formats for library builds:
116

117
```typescript { .api }
118
type Format = 'esm' | 'cjs' | 'umd' | 'mf' | 'iife';
119
```
120

121
- **`esm`**: ES Modules format
122
- **`cjs`**: CommonJS format
123
- **`umd`**: Universal Module Definition
124
- **`mf`**: Module Federation format
125
- **`iife`**: Immediately Invoked Function Expression
126

127
### Library Configuration
128

129
Individual library configuration within the build system:
130

131
```typescript { .api }
132
interface LibConfig extends EnvironmentConfig {
133
  /** Unique library identifier */
134
  id?: string;
135
  /** Output format */
136
  format?: Format;
137
  /** Whether to bundle the library */
138
  bundle?: boolean;
139
  /** Auto file extension setting */
140
  autoExtension?: boolean;
141
  /** Auto externalization settings */
142
  autoExternal?: AutoExternal;
143
  /** Target syntax/browsers */
144
  syntax?: Syntax;
145
  /** Whether to import SWC helper functions from @swc/helpers */
146
  externalHelpers?: boolean;
147
  /** TypeScript declaration settings */
148
  dts?: Dts;
149
  /** CommonJS/ESM shims configuration */
150
  shims?: Shims;
151
  /** Import path redirection settings */
152
  redirect?: Redirect;
153
  /** UMD bundle export name */
154
  umdName?: Rspack.LibraryName;
155
  /** The base directory of the output files */
156
  outBase?: string;
157
  /** File banners */
158
  banner?: BannerAndFooter;
159
  /** File footers */
160
  footer?: BannerAndFooter;
161
}
162

163
interface AutoExternal {
164
  /** Externalize dependencies */
165
  dependencies?: boolean;
166
  /** Externalize optional dependencies */
167
  optionalDependencies?: boolean;
168
  /** Externalize peer dependencies */
169
  peerDependencies?: boolean;
170
  /** Externalize dev dependencies */
171
  devDependencies?: boolean;
172
}
173

174
type Syntax = EcmaScriptVersion | string[];
175

176
type EcmaScriptVersion = 
177
  | 'es5' | 'es6' | 'es2015' | 'es2016' | 'es2017' | 'es2018' 
178
  | 'es2019' | 'es2020' | 'es2021' | 'es2022' | 'es2023' 
179
  | 'es2024' | 'esnext';
180

181
interface BannerAndFooter {
182
  /** JavaScript banner/footer */
183
  js?: string;
184
  /** CSS banner/footer */
185
  css?: string;
186
  /** TypeScript declaration banner/footer */
187
  dts?: string;
188
}
189
```
190

191
### TypeScript Support
192

193
TypeScript declaration file configuration:
194

195
```typescript { .api }
196
interface Dts {
197
  /** Bundle declarations */
198
  bundle?: boolean | { bundledPackages?: string[] };
199
  /** Output directory */
200
  distPath?: string;
201
  /** Build project references */
202
  build?: boolean;
203
  /** Abort on errors */
204
  abortOnError?: boolean;
205
  /** Auto extension setting */
206
  autoExtension?: boolean;
207
  /** Path aliases */
208
  alias?: Record<string, string>;
209
}
210
```
211

212
### Cross-format Compatibility
213

214
Shims for cross-format compatibility:
215

216
```typescript { .api }
217
interface Shims {
218
  /** CommonJS shims */
219
  cjs?: { 'import.meta.url'?: boolean };
220
  /** ESM shims */
221
  esm?: {
222
    __filename?: boolean;
223
    __dirname?: boolean;
224
    require?: boolean;
225
  };
226
}
227

228
interface Redirect {
229
  /** JavaScript import redirection */
230
  js?: JsRedirect;
231
  /** Style import redirection */
232
  style?: StyleRedirect;
233
  /** Asset import redirection */
234
  asset?: AssetRedirect;
235
  /** Declaration import redirection */
236
  dts?: DtsRedirect;
237
}
238

239
interface JsRedirect {
240
  /** Whether to automatically redirect the import paths of JavaScript output files */
241
  path?: boolean;
242
  /** Whether to automatically redirect the file extension to import paths */
243
  extension?: boolean;  
244
}
245

246
interface StyleRedirect {
247
  /** Whether to automatically redirect the import paths of style output files */
248
  path?: boolean;
249
  /** Whether to automatically redirect the file extension to import paths */
250
  extension?: boolean;
251
}
252

253
interface AssetRedirect {
254
  /** Whether to automatically redirect the import paths of asset output files */
255
  path?: boolean;
256
  /** Whether to automatically redirect the file extension to import paths */
257
  extension?: boolean;
258
}
259

260
interface DtsRedirect {
261
  /** Whether to automatically redirect the import paths of TypeScript declaration output files */
262
  path?: boolean;
263
  /** Whether to automatically redirect the file extension to import paths */
264
  extension?: boolean;
265
}
266
```
267

268
## Build Examples
269

270
### Multiple Format Build
271

272
```typescript
273
import { defineConfig } from "@rslib/core";
274

275
export default defineConfig({
276
  lib: [
277
    {
278
      format: "esm",
279
      dts: true,
280
      autoExternal: {
281
        dependencies: true,
282
        peerDependencies: true
283
      }
284
    },
285
    {
286
      format: "cjs",
287
      autoExternal: {
288
        dependencies: true
289
      }
290
    },
291
    {
292
      format: "umd",
293
      umdName: "MyLib",
294
      autoExternal: {
295
        peerDependencies: true
296
      }
297
    }
298
  ]
299
});
300
```
301

302
### Advanced Configuration
303

304
```typescript
305
export default defineConfig({
306
  lib: [
307
    {
308
      id: "main",
309
      format: "esm",
310
      bundle: false,
311
      dts: {
312
        bundle: true,
313
        distPath: "./types"
314
      },
315
      shims: {
316
        esm: {
317
          __dirname: true,
318
          __filename: true
319
        }
320
      },
321
      redirect: {
322
        js: false,
323
        style: false
324
      }
325
    }
326
  ]
327
});
328
```