0
# @builder/user-config
1

2
@builder/user-config provides comprehensive webpack configuration management for the Ice framework ecosystem. It offers standardized user configuration options, CLI option handling, and webpack enhancement utilities for building modern web applications with multiple target platforms.
3

4
## Package Information
5

6
- **Package Name**: @builder/user-config
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @builder/user-config`
10

11
## Core Imports
12

13
```javascript
14
const { 
15
  applyCliOption, 
16
  applyUserConfig, 
17
  getEnhancedWebpackConfig, 
18
  defaultConfig 
19
} = require("@builder/user-config");
20
```
21

22
For ES6 modules:
23

24
```typescript
25
import { 
26
  applyCliOption, 
27
  applyUserConfig, 
28
  getEnhancedWebpackConfig, 
29
  defaultConfig 
30
} from "@builder/user-config";
31
```
32

33
## Basic Usage
34

35
```javascript
36
const { applyUserConfig, applyCliOption, getEnhancedWebpackConfig } = require("@builder/user-config");
37

38
// Register user configuration options with a build plugin API
39
function buildPlugin(api, options) {
40
  // Apply user config options (alias, devServer, externals, etc.)
41
  applyUserConfig(api, { customConfigs: [] });
42
  
43
  // Apply CLI options (https, analyzer, disable-reload, etc.)
44
  applyCliOption(api, { customOptionConfig: {} });
45
}
46

47
// Get enhanced webpack configuration for a specific target
48
function enhanceWebpack(api, webpackConfig, babelConfig) {
49
  return getEnhancedWebpackConfig(api, {
50
    target: 'web',
51
    webpackConfig,
52
    babelConfig,
53
    libName: 'react'
54
  });
55
}
56
```
57

58
## Architecture
59

60
@builder/user-config is built around several key components:
61

62
- **Configuration Registration**: System for registering user config options and CLI options with build APIs
63
- **Webpack Enhancement**: Enhanced webpack configuration with optimizations, plugins, and loaders
64
- **Multi-target Support**: Platform-specific configurations for web, weex, miniapp, and other targets
65
- **User Config System**: 33 comprehensive configuration options covering build, development, and deployment settings
66
- **CLI Integration**: Command-line option handling for development and build workflows
67
- **Validation System**: Type validation and default value management for all configuration options
68

69
## Capabilities
70

71
### Core Configuration Functions
72

73
Main API functions for registering and managing webpack build configurations.
74

75
```javascript { .api }
76
/**
77
 * Register CLI options with build system
78
 * @param api - Build API object with registerCliOption and log methods
79
 * @param options - Configuration options with optional customOptionConfig
80
 */
81
function applyCliOption(api: BuildAPI, options?: CliOptionConfig): void;
82

83
/**
84
 * Register user configuration options with build system
85
 * @param api - Build API object with registerUserConfig method
86
 * @param options - Configuration options with optional customConfigs array
87
 */
88
function applyUserConfig(api: BuildAPI, options?: UserConfigOptions): void;
89

90
/**
91
 * Create enhanced webpack configuration with build optimizations
92
 * @param api - Build API object with context
93
 * @param params - Configuration parameters for webpack enhancement
94
 */
95
function getEnhancedWebpackConfig(
96
  api: BuildAPI, 
97
  params: WebpackEnhancementParams
98
): WebpackConfig;
99

100
/**
101
 * Default configuration values for all user config options
102
 */
103
const defaultConfig: DefaultUserConfig;
104
```
105

106
[Core Configuration](./core-configuration.md)
107

108
### User Configuration Options
109

110
Comprehensive set of 33 configuration options for customizing webpack builds, covering output settings, module resolution, development tools, and platform-specific features.
111

112
```javascript { .api }
113
interface UserConfigSchema {
114
  // Build Output
115
  outputDir?: string;           // Output directory (default: "build")
116
  publicPath?: string;          // Public path for assets (default: "/")
117
  filename?: string;            // Output filename pattern (default: "[name].js")
118
  hash?: string | boolean;      // Enable hash in filenames (default: false)
119
  
120
  // Module Resolution
121
  alias?: Record<string, string>;      // Path aliases (default: {})
122
  extensions?: string[];               // File extensions (default: ['.js', '.jsx', '.json', '.html', '.ts', '.tsx', '.rml'])
123
  modules?: string[];                  // Module directories (default: ['node_modules'])
124
  externals?: Record<string, any>;     // External dependencies (default: {})
125
  
126
  // Development
127
  devServer?: DevServerConfig;         // Development server settings
128
  mock?: boolean;                      // Enable mock server (default: true)
129
  proxy?: Record<string, any>;         // Proxy configuration (default: {})
130
  
131
  // Processing & Optimization
132
  minify?: boolean;                    // Enable minification
133
  sourceMap?: boolean;                 // Enable source maps
134
  browserslist?: string | object;      // Browser support targets
135
  
136
  // And 27 more options...
137
}
138
```
139

140
[User Configuration](./user-configuration.md)
141

142
### CLI Options
143

144
Command-line options for controlling development server behavior and build analysis tools.
145

146
```javascript { .api }
147
interface CliOptions {
148
  https?: boolean;              // Enable HTTPS in dev server
149
  analyzer?: boolean;           // Enable bundle analyzer
150
  'analyzer-port'?: number;     // Bundle analyzer port
151
  'disable-reload'?: boolean;   // Disable hot reload
152
  'disable-mock'?: boolean;     // Disable mock server
153
  'disable-open'?: boolean;     // Disable browser auto-open
154
  'disable-assets'?: boolean;   // Disable assets processing
155
  'debug-runtime'?: boolean;    // Enable debug runtime
156
  mode?: string;                // Set build mode
157
}
158
```
159

160
[CLI Options](./cli-options.md)
161

162
## Types
163

164
```javascript { .api }
165
interface BuildAPI {
166
  registerCliOption(options: CliOptionDefinition[]): void;
167
  registerUserConfig(configs: UserConfigDefinition[]): void;
168
  modifyUserConfig(modifier: (config: any) => any): void;
169
  context: BuildContext;
170
  log: Logger;
171
}
172

173
interface BuildContext {
174
  command: string;              // Current command ('start' | 'build')
175
  commandArgs: Record<string, any>;  // Command line arguments
176
  userConfig: Record<string, any>;   // Current user configuration
177
  webpack: any;                      // Webpack instance
178
  rootDir: string;                   // Project root directory
179
}
180

181
interface WebpackEnhancementParams {
182
  target: string;               // Target platform ('web', 'weex', 'miniapp', etc.)
183
  webpackConfig: any;           // Webpack-chain configuration object
184
  babelConfig: any;             // Babel configuration object
185
  libName?: string;             // Library name (default: 'rax')
186
}
187

188
interface CliOptionConfig {
189
  customOptionConfig?: Record<string, CliOptionDefinition>;
190
}
191

192
interface UserConfigOptions {
193
  customConfigs?: UserConfigDefinition[];
194
}
195

196
interface CliOptionDefinition {
197
  name: string;
198
  commands: string[];           // Applicable commands (['start'], ['build'], ['start', 'build'])
199
  module?: string | false;      // Module name or false to disable
200
  configWebpack?: (config: any, value: any, context: BuildContext) => void;
201
}
202

203
interface UserConfigDefinition {
204
  name: string;
205
  validation: string | ((value: any) => boolean);
206
  defaultValue?: any;
207
  configWebpack?: (config: any, value: any, context: BuildContext, api: BuildAPI) => void;
208
}
209
```