0
# Webpack Chain Customization
1

2
Functions and utilities for customizing webpack configuration through webpack-chain, enabling advanced build customization for Taro H5 projects.
3

4
## Capabilities
5

6
### Chain Customization Function
7

8
Applies custom webpack chain modifications using user-provided functions.
9

10
```typescript { .api }
11
/**
12
 * Customizes webpack chain configuration with user-provided functions
13
 * @param chain - Webpack chain object to be modified
14
 * @param modifyWebpackChainFunc - Function to modify webpack chain
15
 * @param customizeFunc - Optional additional customization function
16
 * @returns Promise that resolves when customization completes
17
 */
18
function customizeChain(
19
  chain: any,
20
  modifyWebpackChainFunc: Func,
21
  customizeFunc?: BuildConfig['webpackChain']
22
): Promise<void>;
23
```
24

25
**Parameters:**
26

27
- `chain` (any): Webpack-chain instance containing the current webpack configuration
28
- `modifyWebpackChainFunc` (Func): Primary function for modifying the webpack chain, receives chain, webpack, and component data
29
- `customizeFunc` (BuildConfig['webpackChain']): Optional secondary customization function
30

31
**Usage Examples:**
32

33
```typescript
34
import { customizeChain } from "@tarojs/webpack-runner";
35

36
// Basic chain customization
37
await customizeChain(
38
  webpackChain,
39
  async (chain, webpack, data) => {
40
    // Add custom alias
41
    chain.resolve.alias.set("@utils", path.resolve("src/utils"));
42
    
43
    // Add custom plugin
44
    chain.plugin("define-plugin").use(webpack.DefinePlugin, [{
45
      "process.env.API_URL": JSON.stringify("https://api.example.com")
46
    }]);
47
    
48
    // Modify loader configuration
49
    chain.module
50
      .rule("typescript")
51
      .test(/\.tsx?$/)
52
      .use("ts-loader")
53
      .loader("ts-loader")
54
      .options({
55
        transpileOnly: true,
56
        compilerOptions: {
57
          jsx: "react"
58
        }
59
      });
60
  }
61
);
62

63
// Advanced customization with both functions
64
await customizeChain(
65
  webpackChain,
66
  async (chain, webpack, data) => {
67
    // Primary modifications with access to component data
68
    const { componentConfig } = data;
69
    
70
    // Configure based on component configuration
71
    if (componentConfig.includeAll) {
72
      chain.plugin("all-components").use(AllComponentsPlugin);
73
    }
74
  },
75
  (chain, webpack) => {
76
    // Secondary customization
77
    chain.optimization.splitChunks({
78
      chunks: "all",
79
      cacheGroups: {
80
        vendor: {
81
          name: "vendor",
82
          test: /[\\/]node_modules[\\/]/,
83
          priority: 10
84
        }
85
      }
86
    });
87
  }
88
);
89
```
90

91
### Configuration Generation Utilities
92

93
Utilities for generating and processing webpack configurations for different build modes.
94

95
```typescript { .api }
96
/**
97
 * Processes build configuration and adds sass loader options
98
 * @param buildConfig - Base build configuration object
99
 * @returns Promise resolving to enhanced build configuration
100
 */
101
function makeConfig(buildConfig: BuildConfig): Promise<BuildConfig & { sassLoaderOption: any }>;
102
```
103

104
**Usage Example:**
105

106
```typescript
107
import { makeConfig } from "@tarojs/webpack-runner/dist/utils/chain";
108

109
// Process configuration before build
110
const enhancedConfig = await makeConfig({
111
  buildAdapter: "h5",
112
  sourceRoot: "src",
113
  outputRoot: "dist",
114
  sass: {
115
    resource: ["src/styles/variables.scss"],
116
    data: "$primary-color: #007bff;"
117
  }
118
});
119

120
// Now includes sassLoaderOption for webpack configuration
121
console.log(enhancedConfig.sassLoaderOption);
122
```
123

124
### Webpack Chain Context Data
125

126
The modification functions receive contextual data for advanced customization:
127

128
```typescript { .api }
129
interface IModifyChainData {
130
  componentConfig: IComponentConfig;
131
}
132

133
interface IComponentConfig {
134
  includes: Set<string>;
135
  exclude: Set<string>;
136
  thirdPartyComponents: Map<string, any>;
137
  includeAll: boolean;
138
}
139
```
140

141
**Chain Modification Patterns:**
142

143
```typescript
144
// Plugin addition
145
chain.plugin("custom-plugin").use(CustomPlugin, [options]);
146

147
// Loader configuration
148
chain.module
149
  .rule("custom-rule")
150
  .test(/\.custom$/)
151
  .use("custom-loader")
152
  .loader("custom-loader")
153
  .options(loaderOptions);
154

155
// Alias configuration
156
chain.resolve.alias
157
  .set("@components", path.resolve("src/components"))
158
  .set("@utils", path.resolve("src/utils"));
159

160
// Output configuration
161
chain.output
162
  .path(path.resolve("dist"))
163
  .filename("[name].[contenthash].js")
164
  .publicPath("/static/");
165

166
// Optimization configuration
167
chain.optimization
168
  .minimize(true)
169
  .minimizer("terser")
170
  .use(TerserPlugin, [terserOptions]);
171

172
// Development server configuration  
173
chain.devServer
174
  .port(3000)
175
  .host("localhost")
176
  .hot(true)
177
  .compress(true);
178
```
179

180
**Integration with Build Process:**
181

182
The chain customization is integrated into the main build process:
183

184
1. **Base Configuration**: Webpack chain is generated based on build mode (dev/prod)
185
2. **Primary Customization**: `modifyWebpackChainFunc` is executed with component data
186
3. **Secondary Customization**: Optional `webpackChain` function is executed
187
4. **Webpack Ready Hook**: `onWebpackChainReady` callback is triggered if provided
188
5. **Compilation**: Modified chain is converted to webpack configuration for compilation
189

190
**Error Handling:**
191

192
- Function execution errors are propagated to the main build process
193
- Invalid chain modifications will cause webpack compilation errors
194
- Both synchronous and asynchronous customization functions are supported