0
# Taro Mini Runner
1
2
Taro Mini Runner is a Webpack launcher for mini-program compilation within the Taro ecosystem. It converts Taro-specific compilation configurations into standard Webpack configurations and compiles source code to be compatible with various mini-program directory structures across multiple platforms.
3
4
## Package Information
5
6
- **Package Name**: @tarojs/mini-runner
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tarojs/mini-runner`
10
11
## Core Imports
12
13
```typescript
14
import build from "@tarojs/mini-runner";
15
```
16
17
For CommonJS:
18
19
```javascript
20
const build = require("@tarojs/mini-runner");
21
```
22
23
Named imports for utilities:
24
25
```typescript
26
import { isQuickAppPkg, resolveNpmSync } from "@tarojs/mini-runner";
27
```
28
29
## Basic Usage
30
31
```typescript
32
import build from "@tarojs/mini-runner";
33
34
// Configure build settings
35
const config = {
36
mode: "production",
37
platform: "weapp", // WeChat mini-program
38
deviceRatio: {
39
640: 2.34 / 2,
40
750: 1,
41
828: 1.81 / 2
42
},
43
sourceDir: "src",
44
outputDir: "dist",
45
plugins: [],
46
defineConstants: {},
47
copy: {
48
patterns: [],
49
options: {}
50
},
51
// ... other Taro build configuration options
52
};
53
54
// Run the build process
55
try {
56
await build("/path/to/project", config);
57
console.log("Build completed successfully");
58
} catch (error) {
59
console.error("Build failed:", error);
60
}
61
```
62
63
## Architecture
64
65
Taro Mini Runner is designed around several key components:
66
67
- **Build Orchestrator**: Main build function that coordinates the compilation process
68
- **Webpack Configuration Generator**: Converts Taro configurations into Webpack-compatible settings
69
- **Platform Adapters**: Support for multiple mini-program platforms with platform-specific optimizations
70
- **Asset Processing**: Handles CSS, images, and other static assets for mini-program environments
71
- **Module Resolution**: Custom npm package resolution for mini-program constraints
72
73
## Capabilities
74
75
### Build Function
76
77
The primary build function that handles webpack configuration generation and compilation process.
78
79
```typescript { .api }
80
/**
81
* Main build function for compiling Taro projects to mini-programs
82
* @param appPath - Absolute path to the project root directory
83
* @param config - Taro build configuration object
84
* @returns Promise that resolves when build completes
85
*/
86
function build(appPath: string, config: IBuildConfig): Promise<void>;
87
```
88
89
### Package Utilities
90
91
Utility functions for package management and resolution within the Taro ecosystem.
92
93
```typescript { .api }
94
/**
95
* Checks if a package name matches QuickApp platform patterns
96
* @param name - Package name to check
97
* @returns True if package is a QuickApp system or service package
98
*/
99
function isQuickAppPkg(name: string): boolean;
100
101
/**
102
* Synchronously resolves npm package path with caching
103
* @param pkgName - Package name to resolve
104
* @param root - Root directory for package resolution
105
* @returns Resolved package path or null if not found
106
*/
107
function resolveNpmSync(pkgName: string, root: string): string | null;
108
```
109
110
## Types
111
112
### Build Configuration Interface
113
114
```typescript { .api }
115
interface IBuildConfig {
116
/** Build mode: 'development' or 'production' */
117
mode: 'development' | 'production';
118
119
/** Target mini-program platform */
120
platform: 'weapp' | 'swan' | 'alipay' | 'tt' | 'jd' | 'qq' | 'quickapp';
121
122
/** Project source directory */
123
sourceDir: string;
124
125
/** Build output directory */
126
outputDir: string;
127
128
/** Device pixel ratio mappings for responsive design */
129
deviceRatio: Record<number, number>;
130
131
/** Webpack plugins array */
132
plugins: any[];
133
134
/** Build-time constants definition */
135
defineConstants: Record<string, any>;
136
137
/** File copy configuration */
138
copy: {
139
patterns: any[];
140
options: Record<string, any>;
141
};
142
143
/** CSS modules configuration */
144
cssModules?: {
145
enable: boolean;
146
config: Record<string, any>;
147
};
148
149
/** PostCSS configuration */
150
postcss?: {
151
pxtransform: {
152
enable: boolean;
153
config: Record<string, any>;
154
};
155
autoprefixer: {
156
enable: boolean;
157
config: Record<string, any>;
158
};
159
cssModules: {
160
enable: boolean;
161
config: Record<string, any>;
162
};
163
};
164
165
/** SASS/SCSS configuration */
166
sass?: Record<string, any>;
167
168
/** Less configuration */
169
less?: Record<string, any>;
170
171
/** Stylus configuration */
172
stylus?: Record<string, any>;
173
174
/** Webpack optimization settings */
175
optimization?: {
176
splitChunks?: Record<string, any>;
177
};
178
179
/** Custom webpack configuration function or object */
180
webpackChain?: (chain: any, webpack: any) => void;
181
182
/** Additional webpack configuration */
183
webpack?: Record<string, any>;
184
185
/** Build completion callback */
186
onBuildFinish?: (error?: Error, stats?: webpack.Stats) => void;
187
188
/** Watch mode settings */
189
isWatch?: boolean;
190
191
/** Enable prerendering */
192
prerender?: boolean;
193
}
194
```
195
196
### Component Interface
197
198
```typescript { .api }
199
interface IComponent {
200
/** Component name */
201
name: string;
202
203
/** Component file path */
204
path: string;
205
206
/** Whether component is platform-native */
207
isNative: boolean;
208
}
209
```
210
211
### File Type Interface
212
213
```typescript { .api }
214
interface IFileType {
215
/** Style file extensions */
216
style: string;
217
218
/** Script file extensions */
219
script: string;
220
221
/** Template file extensions */
222
templ: string;
223
224
/** Configuration file extensions */
225
config: string;
226
227
/** Optional additional script extensions (for platforms like QuickApp) */
228
xs?: string;
229
}
230
```
231
232
### Option Interface
233
234
```typescript { .api }
235
interface IOption {
236
/** Generic key-value object for configuration options */
237
[key: string]: any;
238
}
239
```
240
241
### Custom Webpack Configuration
242
243
```typescript { .api }
244
type CustomWebpackConfig =
245
| ((config: webpack.Configuration, webpack: any) => webpack.Configuration)
246
| webpack.Configuration;
247
```
248
249
## Platform Support
250
251
Taro Mini Runner supports compilation for multiple mini-program platforms:
252
253
- **WeChat Mini Programs** (`weapp`) - WeChat's mini-program platform
254
- **Baidu Smart Programs** (`swan`) - Baidu's smart mini-program platform
255
- **Alipay Mini Programs** (`alipay`) - Alipay's mini-program platform
256
- **ByteDance Mini Programs** (`tt`) - ByteDance (TikTok) mini-program platform
257
- **JD Mini Programs** (`jd`) - JD.com's mini-program platform
258
- **QQ Mini Programs** (`qq`) - Tencent QQ's mini-program platform
259
- **QuickApp** (`quickapp`) - Industry standard for lightweight apps
260
261
Each platform has specific build optimizations, API adaptations, and directory structure requirements that are automatically handled during the build process.
262
263
## Error Handling
264
265
The build function handles various error scenarios:
266
267
- **Configuration Errors**: Invalid or missing build configuration parameters
268
- **Webpack Compilation Errors**: Source code compilation failures, missing dependencies
269
- **File System Errors**: Missing source files, permission issues, disk space problems
270
- **Platform-Specific Errors**: Platform API limitations, size restrictions, feature compatibility
271
272
Errors are propagated as rejected promises with detailed error messages and stack traces for debugging.