0
# Build Configuration
1

2
Configuration interfaces and utilities for defining Taro H5 build parameters, webpack customization options, and development server settings.
3

4
## Capabilities
5

6
### BuildConfig Interface
7

8
Main configuration interface that extends Taro's base configuration interfaces with H5-specific options.
9

10
```typescript { .api }
11
/**
12
 * Main build configuration interface for Taro H5 builds
13
 * Extends IProjectBaseConfig and IH5Config with webpack-specific options
14
 */
15
interface BuildConfig extends IProjectBaseConfig, IH5Config {
16
  /** Target platform adapter (e.g., "h5", "weapp", "swan") */
17
  buildAdapter: string;
18
  
19
  /** Webpack entry configuration */
20
  entry?: webpack.Entry;
21
  
22
  /** Entry file name (default: "app") */
23
  entryFileName?: string;
24
  
25
  /** Runtime path(s) for Taro runtime modules */
26
  runtimePath?: string | string[];
27
  
28
  /** Flag for building native components */
29
  isBuildNativeComp?: boolean;
30
  
31
  /** Skip actual webpack build execution */
32
  withoutBuild?: boolean;
33
  
34
  /** Hook function called during webpack compilation make phase */
35
  onCompilerMake?: (compilation: any) => Promise<any>;
36
  
37
  /** Hook function called when parsing createElement calls */
38
  onParseCreateElement?: (nodeName: any, componentConfig: any) => Promise<any>;
39
  
40
  /** Function to modify component configuration */
41
  modifyComponentConfig?: Func;
42
}
43
```
44

45
**Usage Examples:**
46

47
```typescript
48
import webpackRunner from "@tarojs/webpack-runner";
49

50
// Basic production configuration
51
const productionConfig: BuildConfig = {
52
  buildAdapter: "h5",
53
  sourceRoot: "src",
54
  outputRoot: "dist",
55
  isWatch: false,
56
  entry: {
57
    app: "./src/app.tsx"
58
  },
59
  publicPath: "/",
60
  
61
  // Build optimization
62
  terser: {
63
    enable: true,
64
    config: {
65
      compress: {
66
        drop_console: true
67
      }
68
    }
69
  },
70
  
71
  // CSS optimization
72
  csso: {
73
    enable: true,
74
    config: {
75
      comments: false
76
    }
77
  },
78
  
79
  // Asset handling
80
  imageUrlLoaderOption: {
81
    limit: 10240,
82
    name: "static/images/[name].[contenthash].[ext]"
83
  }
84
};
85

86
// Development configuration with dev server
87
const developmentConfig: BuildConfig = {
88
  buildAdapter: "h5",
89
  sourceRoot: "src",
90
  outputRoot: "dist",
91
  isWatch: true,
92
  
93
  // Development server settings
94
  devServer: {
95
    port: 3000,
96
    host: "0.0.0.0",
97
    open: true,
98
    compress: true,
99
    hot: true,
100
    
101
    // Proxy configuration
102
    proxy: {
103
      "/api": {
104
        target: "http://localhost:8080",
105
        changeOrigin: true,
106
        secure: false
107
      }
108
    }
109
  },
110
  
111
  // Router configuration
112
  router: {
113
    mode: "hash",
114
    basename: "/",
115
    customRoutes: {
116
      "/custom": "/pages/custom/index"
117
    }
118
  }
119
};
120

121
// Advanced configuration with hooks
122
const advancedConfig: BuildConfig = {
123
  buildAdapter: "h5",
124
  sourceRoot: "src",
125
  outputRoot: "dist",
126
  isWatch: false,
127
  
128
  // Webpack customization
129
  webpackChain: (chain, webpack) => {
130
    chain.resolve.alias.set("@", path.resolve("src"));
131
  },
132
  
133
  modifyWebpackChain: async (chain, webpack, data) => {
134
    // Add custom plugin
135
    chain.plugin("custom").use(CustomPlugin, [options]);
136
  },
137
  
138
  // Build lifecycle hooks
139
  onBuildFinish: ({ error, stats, isWatch }) => {
140
    if (error) {
141
      console.error("Build failed:", error.message);
142
    } else {
143
      console.log("Build completed successfully");
144
      if (stats) {
145
        console.log("Build time:", stats.endTime - stats.startTime, "ms");
146
      }
147
    }
148
  },
149
  
150
  onWebpackChainReady: (chain) => {
151
    console.log("Webpack chain is ready for compilation");
152
  },
153
  
154
  // Asset modification
155
  modifyBuildAssets: async (assets) => {
156
    // Modify build assets before emit
157
    Object.keys(assets).forEach(filename => {
158
      if (filename.endsWith(".html")) {
159
        // Modify HTML assets
160
        const source = assets[filename].source();
161
        assets[filename] = {
162
          source: () => source.replace("{{TITLE}}", "My App"),
163
          size: () => source.length
164
        };
165
      }
166
    });
167
  }
168
};
169
```
170

171
### Configuration Type Aliases and Interfaces
172

173
Supporting types and interfaces for build configuration:
174

175
```typescript { .api }
176
/** Webpack entry type supporting various entry formats */
177
type TEntry = string | string[] | webpack.Entry | webpack.EntryFunc;
178

179
/** Custom webpack configuration type */
180
type CustomWebpackConfig = FunctionLikeCustomWebpackConfig | webpack.Configuration;
181

182
/** Function-based webpack configuration */
183
type FunctionLikeCustomWebpackConfig = (
184
  webpackConfig: webpack.Configuration,
185
  webpack: any
186
) => webpack.Configuration;
187

188
/** Generic options interface for flexible configuration */
189
interface Option {
190
  [key: string]: any;
191
}
192

193
/** Webpack chain interface for type safety */
194
interface Chain {
195
  [key: string]: any;
196
}
197

198
/** AppHelper options interface */
199
interface IOptions {
200
  sourceDir: string;
201
  entryFileName: string;
202
  frameworkExts: string[];
203
  modifyAppConfig?: Func;
204
}
205
```
206

207
### Development Server Configuration
208

209
Configuration options for the webpack development server:
210

211
```typescript { .api }
212
interface DevServerConfig {
213
  /** Server port number */
214
  port?: number;
215
  
216
  /** Server host address */
217
  host?: string;
218
  
219
  /** Automatically open browser */
220
  open?: boolean;
221
  
222
  /** Enable gzip compression */
223
  compress?: boolean;
224
  
225
  /** Enable hot module replacement */
226
  hot?: boolean;
227
  
228
  /** Disable host check for remote access */
229
  disableHostCheck?: boolean;
230
  
231
  /** Proxy configuration for API requests */
232
  proxy?: ProxyConfig | ProxyConfig[];
233
  
234
  /** Additional development server options */
235
  [key: string]: any;
236
}
237

238
interface ProxyConfig {
239
  context?: string | string[];
240
  target?: string;
241
  changeOrigin?: boolean;
242
  secure?: boolean;
243
  bypass?: (req: any) => string | void;
244
  [key: string]: any;
245
}
246
```
247

248
### Router Configuration
249

250
Configuration for client-side routing in H5 builds:
251

252
```typescript { .api }
253
interface RouterConfig {
254
  /** Router mode: "hash", "browser", or "multi" */
255
  mode?: "hash" | "browser" | "multi";
256
  
257
  /** Base path for the router */
258
  basename?: string;
259
  
260
  /** Custom route mappings */
261
  customRoutes?: Record<string, string | string[]>;
262
}
263
```
264

265
### Build Hooks and Lifecycle
266

267
Configuration for build lifecycle hooks and customization:
268

269
```typescript { .api }
270
/** Build finish callback function */
271
type OnBuildFinish = (result: {
272
  error: Error | null;
273
  stats: webpack.Stats | null;
274
  isWatch: boolean;
275
}) => void;
276

277
/** Webpack chain ready callback */
278
type OnWebpackChainReady = (chain: any) => void;
279

280
/** Build assets modification hook */
281
type ModifyBuildAssets = (assets: any) => Promise<void>;
282

283
/** Webpack chain modification function */
284
type ModifyWebpackChain = (
285
  chain: any,
286
  webpack: any,
287
  data: IModifyChainData
288
) => Promise<void>;
289

290
interface IModifyChainData {
291
  componentConfig: IComponentConfig;
292
}
293
```
294

295
**Configuration Validation:**
296

297
The build configuration includes validation and error handling:
298

299
```typescript
300
// Invalid configuration examples that will cause errors:
301

302
// Missing required buildAdapter
303
const invalidConfig = {
304
  sourceRoot: "src" // Missing buildAdapter
305
};
306

307
// Invalid router mode
308
const invalidRouter = {
309
  buildAdapter: "h5",
310
  router: {
311
    mode: "invalid" // Must be "hash", "browser", or "multi"
312
  }
313
};
314

315
// Invalid dev server port
316
const invalidDevServer = {
317
  buildAdapter: "h5",
318
  devServer: {
319
    port: "invalid" // Must be number
320
  }
321
};
322
```
323

324
**Default Configuration Values:**
325

326
The build system applies default values for missing configuration:
327

328
```typescript
329
// Default values applied by the build system
330
const defaults = {
331
  sourceRoot: "src",
332
  outputRoot: "dist",
333
  entryFileName: "app",
334
  frameworkExts: [".tsx", ".ts", ".jsx", ".js"],
335
  publicPath: "/",
336
  router: {
337
    mode: "hash",
338
    basename: "/"
339
  },
340
  devServer: {
341
    port: 8080,
342
    host: "localhost",
343
    open: false,
344
    compress: true
345
  }
346
};
347
```