0
# Main Build Runner
1

2
The main build runner function that executes the complete Taro H5 build process, handling both development and production modes based on configuration.
3

4
## Capabilities
5

6
### Default Export Function
7

8
Main webpack runner function that builds Taro projects for the web/H5 platform.
9

10
```typescript { .api }
11
/**
12
 * Main webpack runner function for Taro H5 builds
13
 * @param appPath - Absolute path to the application root directory
14
 * @param config - Taro build configuration object
15
 * @returns Promise that resolves when build completes
16
 */
17
function webpackRunner(appPath: string, config: BuildConfig): Promise<void>;
18
```
19

20
**Parameters:**
21

22
- `appPath` (string): Absolute path to the application root directory containing the Taro project
23
- `config` (BuildConfig): Complete build configuration object with build options, webpack customization, and platform settings
24

25
**Behavior:**
26

27
- **Production mode** (`config.isWatch: false`): Performs optimized build with minification and asset optimization
28
- **Development mode** (`config.isWatch: true`): Starts development server with hot reloading and file watching
29
- Automatically detects available ports for development server
30
- Handles webpack configuration generation based on build mode
31
- Executes custom hooks and webpack chain modifications
32
- Provides error handling and build status reporting
33

34
**Usage Examples:**
35

36
```typescript
37
import webpackRunner from "@tarojs/webpack-runner";
38

39
// Production build
40
await webpackRunner("/Users/dev/my-taro-app", {
41
  buildAdapter: "h5",
42
  sourceRoot: "src",
43
  outputRoot: "dist",
44
  isWatch: false,
45
  entry: {
46
    app: "./src/app.tsx"
47
  },
48
  publicPath: "/",
49
  onBuildFinish: ({ error, stats, isWatch }) => {
50
    if (error) {
51
      console.error("Build failed:", error);
52
    } else {
53
      console.log("Build completed successfully");
54
    }
55
  }
56
});
57

58
// Development build with dev server
59
await webpackRunner("/Users/dev/my-taro-app", {
60
  buildAdapter: "h5",
61
  sourceRoot: "src",
62
  outputRoot: "dist",
63
  isWatch: true,
64
  devServer: {
65
    port: 3000,
66
    host: "localhost",
67
    open: true
68
  },
69
  router: {
70
    mode: "hash",
71
    basename: "/"
72
  }
73
});
74

75
// Build with webpack chain customization
76
await webpackRunner("/Users/dev/my-taro-app", {
77
  buildAdapter: "h5",
78
  sourceRoot: "src",
79
  outputRoot: "dist",
80
  isWatch: false,
81
  webpackChain: (chain, webpack) => {
82
    // Custom webpack configuration
83
    chain.resolve.alias.set("@components", path.resolve("src/components"));
84
  },
85
  modifyWebpackChain: async (chain, webpack, data) => {
86
    // Additional webpack modifications
87
    chain.plugin("custom-plugin").use(CustomPlugin, [options]);
88
  }
89
});
90
```
91

92
### Internal Build Functions
93

94
The main runner delegates to specialized build functions based on the configuration:
95

96
```typescript { .api }
97
/**
98
 * Production build function (internal)
99
 * Configures webpack for optimized production builds
100
 */
101
function buildProd(
102
  appPath: string,
103
  config: BuildConfig,
104
  appHelper: AppHelper
105
): Promise<void>;
106

107
/**
108
 * Development build function (internal)
109
 * Configures webpack dev server for development builds
110
 */
111
function buildDev(
112
  appPath: string,
113
  config: BuildConfig,
114
  appHelper: AppHelper
115
): Promise<any>;
116
```
117

118
**Error Handling:**
119

120
The runner includes comprehensive error handling:
121

122
- **Build errors**: Captured and passed to `onBuildFinish` callback
123
- **Configuration errors**: Thrown as exceptions with descriptive messages
124
- **Development server errors**: Logged and cause process termination
125
- **Webpack compilation errors**: Handled based on `errorLevel` configuration
126

127
**Build Lifecycle:**
128

129
1. **Configuration Processing**: Merges and validates build configuration
130
2. **App Helper Creation**: Parses Taro app structure and entry points
131
3. **Webpack Chain Generation**: Creates webpack configuration based on build mode
132
4. **Chain Customization**: Applies user-defined webpack chain modifications
133
5. **Compilation**: Executes webpack build or starts development server
134
6. **Asset Processing**: Handles build asset modifications via hooks
135
7. **Completion**: Triggers build finish callbacks and error handling