0
# @tarojs/webpack-runner
1

2
@tarojs/webpack-runner is a Webpack runner for the Taro cross-platform development framework that transforms Taro compilation configurations into Webpack configurations for H5/web builds. It serves as the bridge between @tarojs/cli and Webpack, handling the complete compilation pipeline from Taro source code to web-ready applications.
3

4
## Package Information
5

6
- **Package Name**: @tarojs/webpack-runner
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/webpack-runner`
10

11
## Core Imports
12

13
```typescript
14
// ES6 imports
15
import webpackRunner from "@tarojs/webpack-runner";
16
import { AppHelper } from "@tarojs/webpack-runner";
17

18
// Import utility functions
19
import { 
20
  addLeadingSlash, 
21
  addTrailingSlash, 
22
  stripBasename, 
23
  formatOpenHost, 
24
  parsePublicPath 
25
} from "@tarojs/webpack-runner";
26

27
// Import types (TypeScript only)
28
import type { BuildConfig, TEntry, IOptions } from "@tarojs/webpack-runner";
29
```
30

31
For CommonJS:
32

33
```javascript
34
// CommonJS imports
35
const webpackRunner = require("@tarojs/webpack-runner").default;
36
const { AppHelper, addLeadingSlash, formatOpenHost } = require("@tarojs/webpack-runner");
37
```
38

39
For utility functions:
40

41
```typescript
42
// Utility imports (from subdirectories)
43
import { makeConfig } from "@tarojs/webpack-runner/dist/utils/chain";
44
```
45

46
## Basic Usage
47

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

51
// Basic production build
52
await webpackRunner("/path/to/app", {
53
  buildAdapter: "h5",
54
  sourceRoot: "src",
55
  outputRoot: "dist",
56
  isWatch: false,
57
});
58

59
// Development build with watch
60
await webpackRunner("/path/to/app", {
61
  buildAdapter: "h5",
62
  sourceRoot: "src", 
63
  outputRoot: "dist",
64
  isWatch: true,
65
  devServer: {
66
    port: 3000,
67
    host: "localhost"
68
  }
69
});
70
```
71

72
## Architecture
73

74
@tarojs/webpack-runner is built around several key components:
75

76
- **Main Runner**: Default export function that orchestrates the entire build process
77
- **Configuration System**: Modular webpack configuration generation for different build modes
78
- **App Helper**: Utility class for parsing and managing Taro app configurations
79
- **Plugin System**: Custom webpack plugins for Taro-specific transformations
80
- **Chain Customization**: Support for webpack-chain based configuration customization
81

82
## Capabilities
83

84
### Main Build Runner
85

86
Primary function that executes the complete Taro H5 build process, handling both development and production modes.
87

88
```typescript { .api }
89
function webpackRunner(appPath: string, config: BuildConfig): Promise<void>;
90
```
91

92
[Main Build Runner](./build-runner.md)
93

94
### Path and URL Utilities
95

96
Utility functions for handling paths, URLs, and routing in Taro H5 applications.
97

98
```typescript { .api }
99
/**
100
 * Adds leading slash to URL if missing
101
 */
102
function addLeadingSlash(url?: string): string;
103

104
/**
105
 * Adds trailing slash to URL if missing  
106
 */
107
function addTrailingSlash(url?: string): string;
108

109
/**
110
 * Removes leading basename from path
111
 */
112
function stripBasename(path?: string, prefix?: string): string;
113

114
/**
115
 * Removes trailing slash from path
116
 */
117
function stripTrailingSlash(path?: string): string;
118

119
/**
120
 * Adds .html suffix to path
121
 */
122
function addHtmlSuffix(path?: string): string;
123

124
/**
125
 * Formats host for opening in browser, converts 0.0.0.0 to local IP
126
 */
127
function formatOpenHost(host: string): string;
128

129
/**
130
 * Parses and normalizes public path configuration
131
 */
132
function parsePublicPath(publicPath?: string): string;
133

134
/**
135
 * Generates HTML script for responsive font-size based on pxtransform options
136
 */
137
function parseHtmlScript(pxtransformOption?: IPostcssOption['pxtransform']): string | undefined;
138
```
139

140
### Webpack Chain Customization
141

142
Internal webpack chain customization system used by the build process.
143

144
```typescript { .api }
145
function makeConfig(buildConfig: BuildConfig): Promise<BuildConfig & { sassLoaderOption: any }>;
146
```
147

148
[Webpack Chain Customization](./webpack-chain.md)
149

150
### App Configuration Management
151

152
Helper class for parsing Taro app configurations, managing pages, components, and build entry points.
153

154
```typescript { .api }
155
class AppHelper {
156
  constructor(entry: TEntry, options: Partial<IOptions>);
157
  readonly appEntry: string;
158
  readonly appConfig: AppConfig;
159
  readonly pages: Set<{ name: string; path: string }>;
160
  readonly comps: Set<{ name: string; path: string }>;
161
  readonly pagesConfigList: Map<string, string>;
162
  readonly compsConfigList: Map<string, string>;
163
  getConfigFilePath(filePath: string): string;
164
  clear(): void;
165
}
166
```
167

168
[App Configuration Management](./app-helper.md)
169

170
### Build Configuration
171

172
Configuration interface and utilities for defining Taro H5 build parameters and webpack customization options.
173

174
```typescript { .api }
175
interface BuildConfig extends IProjectBaseConfig, IH5Config {
176
  buildAdapter: string;
177
  entry?: webpack.Entry;
178
  entryFileName?: string;
179
  runtimePath?: string | string[];
180
  isBuildNativeComp?: boolean;
181
  withoutBuild?: boolean;
182
  onCompilerMake: (compilation: any) => Promise<any>;
183
  onParseCreateElement: (nodeName: any, componentConfig: any) => Promise<any>;
184
  modifyComponentConfig: Func;
185
}
186
```
187

188
[Build Configuration](./build-config.md)
189

190
## Types
191

192
```typescript { .api }
193
type TEntry = string | string[] | webpack.Entry | webpack.EntryFunc;
194

195
type CustomWebpackConfig = FunctionLikeCustomWebpackConfig | webpack.Configuration;
196

197
type FunctionLikeCustomWebpackConfig = (
198
  webpackConfig: webpack.Configuration,
199
  webpack: any
200
) => webpack.Configuration;
201

202
interface IOptions {
203
  sourceDir: string;
204
  entryFileName: string;
205
  frameworkExts: string[];
206
  modifyAppConfig?: Func;
207
}
208

209
interface Option {
210
  [key: string]: any;
211
}
212

213
interface Chain {
214
  [key: string]: any;
215
}
216

217
// External types from @tarojs/taro
218
type Func = (...args: any[]) => any;
219

220
interface AppConfig {
221
  pages?: string[];
222
  components?: string[]; // For native component builds only
223
  window?: object;
224
  tabBar?: object;
225
  subPackages?: object[];
226
  subpackages?: object[]; // Alternative spelling
227
  entryPagePath?: string;
228
  [key: string]: any;
229
}
230

231
// Additional interfaces for utility functions
232
interface IPostcssOption {
233
  pxtransform?: {
234
    config?: {
235
      maxRootSize?: number;
236
      minRootSize?: number;
237
      baseFontSize?: number;
238
      designWidth?: number | ((input: any) => number);
239
      deviceRatio?: Record<number, number>;
240
      targetUnit?: 'rem' | 'px';
241
    };
242
  };
243
}
244
```