0
# Configuration
1

2
Type-safe configuration system with environment-specific overrides and webpack merge capabilities.
3

4
## Capabilities
5

6
### Configuration Definition
7

8
Core function for defining Taro project configuration with type safety and IDE support.
9

10
```typescript { .api }
11
/**
12
 * Define Taro project configuration with type safety
13
 * @param config - Configuration object, function, or promise
14
 * @returns The same configuration for Taro consumption
15
 */
16
function defineConfig<T extends CompilerTypes = CompilerWebpackTypes>(
17
  config: UserConfigExport<T>
18
): UserConfigExport<T>;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { defineConfig } from "@tarojs/cli";
25

26
// Static configuration
27
export default defineConfig({
28
  projectName: 'my-app',
29
  framework: 'react',
30
  compiler: 'webpack5',
31
  // ... other config options
32
});
33

34
// Dynamic configuration with environment
35
export default defineConfig((merge, { command, mode }) => {
36
  const baseConfig = {
37
    projectName: 'my-app',
38
    framework: 'react' as const,
39
    compiler: 'webpack5' as const,
40
  };
41

42
  if (mode === 'development') {
43
    return merge(baseConfig, {
44
      devServer: {
45
        port: 3000,
46
      },
47
    });
48
  }
49

50
  return baseConfig;
51
});
52

53
// Async configuration
54
export default defineConfig(async () => {
55
  const config = await loadExternalConfig();
56
  return {
57
    projectName: config.name,
58
    framework: 'vue3',
59
    // ... other config
60
  };
61
});
62
```
63

64
### Configuration Types
65

66
Type definitions for configuration objects, functions, and environment context.
67

68
```typescript { .api }
69
/**
70
 * Configuration environment context
71
 */
72
interface ConfigEnv {
73
  /** Current Taro command being executed */
74
  command: string;
75
  /** Current build mode (development, production, etc.) */
76
  mode: string;
77
}
78

79
/**
80
 * Webpack merge function type for combining configurations
81
 */
82
type WebpackMerge = (...configs: Array<object | null | undefined>) => object;
83

84
/**
85
 * Configuration function type with merge utilities
86
 */
87
type UserConfigFn<T extends CompilerTypes = CompilerWebpackTypes> = (
88
  merge: WebpackMerge,
89
  env: ConfigEnv
90
) => IProjectConfig<T> | Promise<IProjectConfig<T>>;
91

92
/**
93
 * Union type for all valid configuration exports
94
 */
95
type UserConfigExport<T extends CompilerTypes = CompilerWebpackTypes> = 
96
  | IProjectConfig<T> 
97
  | Promise<IProjectConfig<T>> 
98
  | UserConfigFn<T>;
99
```
100

101
### Project Configuration Interface
102

103
Complete interface for Taro project configuration covering all build and runtime options.
104

105
```typescript { .api }
106
/**
107
 * Complete Taro project configuration interface
108
 */
109
interface IProjectConfig<T extends CompilerTypes = CompilerWebpackTypes> {
110
  /** Project name */
111
  projectName: string;
112
  
113
  /** Build and compilation settings */
114
  framework: FrameworkType;
115
  compiler: T;
116
  sourceRoot?: string;
117
  outputRoot?: string;
118
  
119
  /** Platform-specific configurations */
120
  h5?: H5Config;
121
  weapp?: WeappConfig;
122
  alipay?: AlipayConfig;
123
  swan?: SwanConfig;
124
  tt?: TTConfig;
125
  qq?: QQConfig;
126
  jd?: JDConfig;
127
  rn?: RNConfig;
128
  
129
  /** Plugin configuration */
130
  plugins?: (string | [string, object])[];
131
  presets?: (string | [string, object])[];
132
  
133
  /** Environment and build options */
134
  env?: Record<string, any>;
135
  defineConstants?: Record<string, any>;
136
  alias?: Record<string, string>;
137
  
138
  /** Optimization settings */
139
  terser?: TerserConfig;
140
  csso?: CssoConfig;
141
  
142
  /** Development server */
143
  devServer?: DevServerConfig;
144
  
145
  /** File system options */
146
  copy?: CopyConfig;
147
  
148
  /** Framework-specific options */
149
  react?: ReactConfig;
150
  vue?: VueConfig;
151
  
152
  /** Compiler-specific options */
153
  webpack5?: WebpackConfig;
154
  vite?: ViteConfig;
155
  esbuild?: EsbuildConfig;
156
}
157
```
158

159
### Platform Configurations
160

161
Platform-specific configuration options for different target environments.
162

163
```typescript { .api }
164
/**
165
 * H5 platform configuration
166
 */
167
interface H5Config {
168
  /** Public path for assets */
169
  publicPath?: string;
170
  /** Static directory path */
171
  staticDirectory?: string;
172
  /** HTML chunk loading timeout */
173
  chunkLoadingTimeout?: number;
174
  /** Enable service worker */
175
  enableExtract?: boolean;
176
  /** Router configuration */
177
  router?: {
178
    mode?: 'hash' | 'browser';
179
    basename?: string;
180
  };
181
  /** Development server options */
182
  devServer?: DevServerConfig;
183
}
184

185
/**
186
 * WeChat Mini Program configuration
187
 */
188
interface WeappConfig {
189
  /** Mini program compile type */
190
  compile?: {
191
    exclude?: string[];
192
    include?: string[];
193
  };
194
  /** Enable source map */
195
  enableSourceMap?: boolean;
196
  /** Mini program subpackages */
197
  subPackages?: SubPackageConfig[];
198
}
199

200
/**
201
 * React Native configuration
202
 */
203
interface RNConfig {
204
  /** Bundle output path */
205
  output?: {
206
    ios?: string;
207
    android?: string;
208
  };
209
  /** Enable Hermes engine */
210
  enableHermes?: boolean;
211
  /** Metro bundler options */
212
  metro?: MetroConfig;
213
}
214
```
215

216
### Development Server Configuration
217

218
Development server options for local development and hot reloading.
219

220
```typescript { .api }
221
/**
222
 * Development server configuration
223
 */
224
interface DevServerConfig {
225
  /** Server port */
226
  port?: number;
227
  /** Server host */
228
  host?: string;
229
  /** Enable HTTPS */
230
  https?: boolean;
231
  /** Open browser automatically */
232
  open?: boolean;
233
  /** Proxy configuration */
234
  proxy?: Record<string, ProxyConfig>;
235
  /** Enable hot module replacement */
236
  hot?: boolean;
237
  /** Enable live reload */
238
  liveReload?: boolean;
239
  /** Static file serving options */
240
  static?: {
241
    directory?: string;
242
    publicPath?: string;
243
  };
244
}
245

246
/**
247
 * Proxy configuration for development server
248
 */
249
interface ProxyConfig {
250
  target: string;
251
  changeOrigin?: boolean;
252
  pathRewrite?: Record<string, string>;
253
  secure?: boolean;
254
}
255
```
256

257
### Build Optimization Configuration
258

259
Configuration options for build optimization including minification and code splitting.
260

261
```typescript { .api }
262
/**
263
 * Terser minification configuration
264
 */
265
interface TerserConfig {
266
  enable?: boolean;
267
  config?: {
268
    compress?: boolean;
269
    mangle?: boolean;
270
    output?: {
271
      comments?: boolean;
272
    };
273
  };
274
}
275

276
/**
277
 * CSS optimization configuration
278
 */
279
interface CssoConfig {
280
  enable?: boolean;
281
  config?: {
282
    restructure?: boolean;
283
    comments?: boolean;
284
  };
285
}
286

287
/**
288
 * File copy configuration
289
 */
290
interface CopyConfig {
291
  patterns?: Array<{
292
    from: string;
293
    to: string;
294
    ignore?: string[];
295
  }>;
296
  options?: {
297
    ignore?: string[];
298
  };
299
}
300
```
301

302
### Compiler-Specific Configurations
303

304
Configuration options specific to different compilation systems.
305

306
```typescript { .api }
307
/**
308
 * Webpack 5 specific configuration
309
 */
310
interface WebpackConfig {
311
  /** Custom webpack configuration */
312
  configureWebpack?: (config: any) => any;
313
  /** Webpack chain modifications */
314
  chainWebpack?: (chain: any) => void;
315
  /** Enable webpack bundle analyzer */
316
  bundleAnalyzer?: {
317
    enable?: boolean;
318
    port?: number;
319
  };
320
}
321

322
/**
323
 * Vite specific configuration
324
 */
325
interface ViteConfig {
326
  /** Vite configuration options */
327
  viteConfig?: {
328
    server?: {
329
      port?: number;
330
      host?: string;
331
    };
332
    build?: {
333
      outDir?: string;
334
      sourcemap?: boolean;
335
    };
336
  };
337
}
338

339
/**
340
 * ESBuild specific configuration
341
 */
342
interface EsbuildConfig {
343
  /** ESBuild configuration options */
344
  esbuildConfig?: {
345
    target?: string;
346
    minify?: boolean;
347
    sourcemap?: boolean;
348
  };
349
}
350
```
351

352
### Environment Configuration
353

354
Environment variable handling and build-time constant definition.
355

356
```typescript { .api }
357
/**
358
 * Environment configuration interface
359
 */
360
interface EnvironmentConfig {
361
  /** Build-time constants */
362
  defineConstants?: Record<string, any>;
363
  /** Environment variables */
364
  env?: Record<string, any>;
365
  /** Environment-specific overrides */
366
  development?: Partial<IProjectConfig>;
367
  production?: Partial<IProjectConfig>;
368
  test?: Partial<IProjectConfig>;
369
}
370

371
/**
372
 * Common environment constants
373
 */
374
interface CommonConstants {
375
  NODE_ENV: 'development' | 'production' | 'test';
376
  TARO_ENV: string;
377
  API_BASE_URL?: string;
378
  APP_VERSION?: string;
379
  DEBUG?: boolean;
380
}
381
```
382

383
**Usage Examples:**
384

385
```typescript
386
// Environment-specific configuration
387
export default defineConfig({
388
  projectName: 'my-app',
389
  framework: 'react',
390
  defineConstants: {
391
    API_BASE_URL: process.env.NODE_ENV === 'production' 
392
      ? 'https://api.example.com'
393
      : 'http://localhost:3001',
394
  },
395
  env: {
396
    NODE_ENV: '"development"',
397
    CUSTOM_VAR: '"custom-value"',
398
  },
399
});
400

401
// Platform-specific configuration
402
export default defineConfig({
403
  projectName: 'multi-platform-app',
404
  framework: 'react',
405
  h5: {
406
    publicPath: '/h5/',
407
    router: {
408
      mode: 'browser',
409
      basename: '/app',
410
    },
411
    devServer: {
412
      port: 3000,
413
      proxy: {
414
        '/api': {
415
          target: 'http://localhost:8080',
416
          changeOrigin: true,
417
        },
418
      },
419
    },
420
  },
421
  weapp: {
422
    enableSourceMap: true,
423
    compile: {
424
      exclude: ['src/utils/h5-only.ts'],
425
    },
426
  },
427
  rn: {
428
    output: {
429
      ios: 'ios/bundle.js',
430
      android: 'android/bundle.js',
431
    },
432
    enableHermes: true,
433
  },
434
});
435
```