0
# Configuration
1

2
Type-safe configuration definition and loading system with support for both static and function-based configurations. Provides autocomplete support and flexible configuration patterns.
3

4
## Capabilities
5

6
### Define Configuration
7

8
Helper function for type-safe configuration definition with autocomplete support.
9

10
```typescript { .api }
11
/**
12
 * Helper function for type-safe configuration definition with autocomplete support
13
 * @param config - Static configuration object, sync function, or async function
14
 * @returns Configuration export with proper typing
15
 */
16
function defineConfig(config: RslibConfig): RslibConfig;
17
function defineConfig(config: RslibConfigSyncFn): RslibConfigSyncFn;
18
function defineConfig(config: RslibConfigAsyncFn): RslibConfigAsyncFn;
19

20
type RslibConfigExport = RslibConfig | RslibConfigSyncFn | RslibConfigAsyncFn;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { defineConfig } from "@rslib/core";
27

28
// Static configuration
29
export default defineConfig({
30
  lib: [
31
    { format: "esm", dts: true },
32
    { format: "cjs" }
33
  ]
34
});
35

36
// Function-based configuration
37
export default defineConfig((env) => ({
38
  lib: [
39
    {
40
      format: env.command === "build" ? "esm" : "cjs",
41
      dts: env.command === "build"
42
    }
43
  ]
44
}));
45

46
// Async configuration
47
export default defineConfig(async (env) => {
48
  const isDev = env.envMode === "development";
49
  return {
50
    lib: [
51
      {
52
        format: "esm",
53
        dts: !isDev,
54
        bundle: !isDev
55
      }
56
    ]
57
  };
58
});
59
```
60

61
### Load Configuration
62

63
Loads and resolves Rslib configuration from the file system.
64

65
```typescript { .api }
66
/**
67
 * Loads and resolves Rslib configuration from file system
68
 * @param options - Configuration loading options
69
 * @returns Promise with config content and file path
70
 */
71
function loadConfig(options?: LoadConfigOptions): Promise<{
72
  content: RslibConfig;
73
  filePath: string;
74
}>;
75

76
interface LoadConfigOptions {
77
  /** Current working directory */
78
  cwd?: string;
79
  /** Custom configuration file path */
80
  path?: string;
81
  /** Environment mode */
82
  envMode?: string;
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import { loadConfig, build } from "@rslib/core";
90

91
// Load default configuration
92
const { content: config, filePath } = await loadConfig();
93
console.log(`Loaded config from: ${filePath}`);
94

95
// Load with custom options
96
const result = await loadConfig({
97
  path: "./custom.config.js",
98
  cwd: "./src",
99
  envMode: "development"
100
});
101

102
// Use loaded config
103
await build(result.content);
104
```
105

106
### Configuration Function Types
107

108
Type definitions for function-based configurations:
109

110
```typescript { .api }
111
/**
112
 * Synchronous configuration function
113
 * @param env - Configuration parameters including environment and command
114
 * @returns Configuration object
115
 */
116
type RslibConfigSyncFn = (env: ConfigParams) => RslibConfig;
117

118
/**
119
 * Asynchronous configuration function
120
 * @param env - Configuration parameters including environment and command
121
 * @returns Promise resolving to configuration object
122
 */
123
type RslibConfigAsyncFn = (env: ConfigParams) => Promise<RslibConfig>;
124

125
interface ConfigParams {
126
  /** Environment (development/production) */
127
  env: string;
128
  /** CLI command being executed */
129
  command: string;
130
  /** Environment mode */
131
  envMode?: string;
132
}
133
```
134

135
## Core Configuration Types
136

137
### Main Configuration Interface
138

139
```typescript { .api }
140
/**
141
 * Main configuration interface for Rslib
142
 * Extends Rsbuild configuration with library-specific options
143
 */
144
interface RslibConfig extends RsbuildConfig {
145
  /** Array of library configurations */
146
  lib: LibConfig[];
147
  /** Output configuration */
148
  output?: RslibOutputConfig;
149
}
150

151
interface RslibOutputConfig {
152
  /** Target output directory */
153
  target?: string;
154
  /** Additional output options */
155
  [key: string]: any;
156
}
157
```
158

159
### Library Configuration
160

161
```typescript { .api }
162
/**
163
 * Individual library configuration
164
 * Extends Rsbuild environment configuration
165
 */
166
interface LibConfig extends EnvironmentConfig {
167
  /** Unique library identifier */
168
  id?: string;
169
  /** Output format (esm, cjs, umd, mf, iife) */
170
  format?: Format;
171
  /** Whether to bundle the library */
172
  bundle?: boolean;
173
  /** Auto file extension setting */
174
  autoExtension?: boolean;
175
  /** Auto externalization settings */
176
  autoExternal?: AutoExternal;
177
  /** Target syntax/browsers */
178
  syntax?: Syntax;
179
  /** Whether to import SWC helper functions from @swc/helpers */
180
  externalHelpers?: boolean;
181
  /** TypeScript declaration settings */
182
  dts?: Dts;
183
  /** CommonJS/ESM shims configuration */
184
  shims?: Shims;
185
  /** Import path redirection settings */
186
  redirect?: Redirect;
187
  /** UMD bundle export name */
188
  umdName?: Rspack.LibraryName;
189
  /** The base directory of the output files */
190
  outBase?: string;
191
  /** File banners */
192
  banner?: BannerAndFooter;
193
  /** File footers */
194
  footer?: BannerAndFooter;
195
}
196
```
197

198
## Configuration Patterns
199

200
### Environment-based Configuration
201

202
```typescript
203
import { defineConfig } from "@rslib/core";
204

205
export default defineConfig((env) => {
206
  const isDev = env.envMode === "development";
207
  const isProd = env.env === "production";
208
  
209
  return {
210
    lib: [
211
      {
212
        format: "esm",
213
        dts: isProd,
214
        bundle: isProd,
215
        autoExternal: {
216
          dependencies: true,
217
          peerDependencies: isProd
218
        }
219
      },
220
      ...(isProd ? [{
221
        format: "cjs",
222
        autoExternal: { dependencies: true }
223
      }] : [])
224
    ]
225
  };
226
});
227
```
228

229
### Command-based Configuration
230

231
```typescript
232
export default defineConfig((env) => {
233
  const isInspect = env.command === "inspect";
234
  
235
  return {
236
    lib: [
237
      {
238
        format: "esm",
239
        dts: !isInspect,
240
        bundle: !isInspect
241
      }
242
    ]
243
  };
244
});
245
```
246

247
### Async Configuration Loading
248

249
```typescript
250
export default defineConfig(async (env) => {
251
  // Load external configuration
252
  const packageJson = await import("./package.json");
253
  const hasTypescript = packageJson.devDependencies?.typescript;
254
  
255
  return {
256
    lib: [
257
      {
258
        format: "esm",
259
        dts: !!hasTypescript,
260
        syntax: env.env === "production" ? "es2018" : "esnext"
261
      }
262
    ]
263
  };
264
});
265
```
266

267
### Multiple Library Configurations
268

269
```typescript
270
export default defineConfig({
271
  lib: [
272
    {
273
      id: "browser",
274
      format: "esm",
275
      syntax: ["chrome >= 87", "firefox >= 78"],
276
      dts: true
277
    },
278
    {
279
      id: "node",
280
      format: "cjs", 
281
      syntax: "node18",
282
      shims: {
283
        esm: {
284
          __dirname: true,
285
          __filename: true
286
        }
287
      }
288
    },
289
    {
290
      id: "universal",
291
      format: "umd",
292
      umdName: "MyLib",
293
      syntax: "es5"
294
    }
295
  ]
296
});
297
```
298

299
## Advanced Configuration
300

301
### Unstable Compose Function
302

303
```typescript { .api }
304
/**
305
 * Unstable API for composing Rsbuild configuration from Rslib config
306
 * WARNING: This API is marked as unstable and may change
307
 * @param rslibConfig - Rslib configuration object
308
 * @returns Array of Rsbuild configurations with library info
309
 */
310
function unstable_composeCreateRsbuildConfig(
311
  rslibConfig: RslibConfig
312
): Promise<RsbuildConfigWithLibInfo[]>;
313

314
interface RsbuildConfigWithLibInfo {
315
  id?: string;
316
  format: Format;
317
  config: EnvironmentConfig;
318
}
319
```
320

321
This function allows advanced composition of Rsbuild configurations from Rslib config but should be used with caution as it's marked unstable and may change in future versions.
322

323
**Usage Example:**
324

325
```typescript
326
import { unstable_composeCreateRsbuildConfig, defineConfig } from "@rslib/core";
327

328
const rslibConfig = defineConfig({
329
  lib: [
330
    { format: "esm", dts: true },
331
    { format: "cjs" }
332
  ]
333
});
334

335
// Get composed Rsbuild configurations
336
const configs = await unstable_composeCreateRsbuildConfig(rslibConfig);
337
// Result: Array of { id?, format, config } objects
338
```