0
# Core Configuration
1

2
Core API functions for registering and managing webpack build configurations in the @builder/user-config system.
3

4
## Capabilities
5

6
### Apply CLI Option
7

8
Registers command-line interface options with the build system, enabling developers to customize build behavior through CLI flags.
9

10
```javascript { .api }
11
/**
12
 * Register CLI options with build system
13
 * @param api - Build API object with registerCliOption and log methods
14
 * @param options - Configuration options with optional customOptionConfig
15
 */
16
function applyCliOption(api: BuildAPI, options?: CliOptionConfig): void;
17

18
interface CliOptionConfig {
19
  customOptionConfig?: Record<string, CliOptionDefinition>;
20
}
21

22
interface CliOptionDefinition {
23
  name: string;                 // Option name (e.g., 'https', 'analyzer')
24
  commands: string[];           // Applicable commands (['start'], ['build'], ['start', 'build'])
25
  module?: string | false;      // Module name or false to disable webpack config modification
26
  configWebpack?: (config: any, value: any, context: BuildContext) => void;
27
}
28
```
29

30
**Usage Example:**
31

32
```javascript
33
const { applyCliOption } = require("@builder/user-config");
34

35
function myBuildPlugin(api, options) {
36
  // Register default CLI options (https, analyzer, disable-reload, etc.)
37
  applyCliOption(api);
38
  
39
  // Register custom CLI options
40
  applyCliOption(api, {
41
    customOptionConfig: {
42
      'custom-flag': {
43
        name: 'custom-flag',
44
        commands: ['start', 'build'],
45
        configWebpack: (config, flagValue, context) => {
46
          if (flagValue) {
47
            // Modify webpack config when --custom-flag is used
48
            config.optimization.minimize(false);
49
          }
50
        }
51
      }
52
    }
53
  });
54
}
55
```
56

57
### Apply User Config
58

59
Registers user configuration options with the build system, allowing developers to customize build behavior through configuration files.
60

61
```javascript { .api }
62
/**
63
 * Register user configuration options with build system
64
 * @param api - Build API object with registerUserConfig method
65
 * @param options - Configuration options with optional customConfigs array
66
 */
67
function applyUserConfig(api: BuildAPI, options?: UserConfigOptions): void;
68

69
interface UserConfigOptions {
70
  customConfigs?: UserConfigDefinition[];
71
}
72

73
interface UserConfigDefinition {
74
  name: string;                 // Config option name
75
  validation: string | ((value: any) => boolean);  // Validation rule
76
  defaultValue?: any;           // Default value if not specified
77
  configWebpack?: (config: any, value: any, context: BuildContext, api: BuildAPI) => void;
78
}
79
```
80

81
**Usage Example:**
82

83
```javascript
84
const { applyUserConfig } = require("@builder/user-config");
85

86
function myBuildPlugin(api, options) {
87
  // Register all default user config options (33 built-in options)
88
  applyUserConfig(api);
89
  
90
  // Register additional custom configuration options
91
  applyUserConfig(api, {
92
    customConfigs: [
93
      {
94
        name: 'customOutput',
95
        validation: 'string',
96
        defaultValue: 'dist',
97
        configWebpack: (config, outputPath, context, api) => {
98
          config.output.path(outputPath);
99
        }
100
      }
101
    ]
102
  });
103
}
104
```
105

106
### Get Enhanced Webpack Config
107

108
Creates an enhanced webpack configuration with build optimizations, development tools, and platform-specific settings.
109

110
```javascript { .api }
111
/**
112
 * Create enhanced webpack configuration with build optimizations
113
 * @param api - Build API object with context
114
 * @param params - Configuration parameters for webpack enhancement
115
 * @returns Enhanced webpack configuration object
116
 */
117
function getEnhancedWebpackConfig(
118
  api: BuildAPI, 
119
  params: WebpackEnhancementParams
120
): WebpackConfig;
121

122
interface WebpackEnhancementParams {
123
  target: string;               // Target platform ('web', 'weex', 'miniapp', etc.)
124
  webpackConfig: any;           // Webpack-chain configuration object
125
  babelConfig: any;             // Babel configuration object
126
  libName?: string;             // Library name (default: 'rax')
127
}
128
```
129

130
**Usage Example:**
131

132
```javascript
133
const { getEnhancedWebpackConfig } = require("@builder/user-config");
134

135
function enhanceWebpack(api, webpackConfig, babelConfig) {
136
  // Enhance webpack config for web target
137
  const enhancedConfig = getEnhancedWebpackConfig(api, {
138
    target: 'web',
139
    webpackConfig,
140
    babelConfig,
141
    libName: 'react'
142
  });
143
  
144
  return enhancedConfig;
145
}
146
```
147

148
**Enhanced Features Added:**
149

150
- **Performance Settings**: Sets max asset and entry point sizes to 1MB
151
- **DefinePlugin**: Adds environment variables (NODE_ENV, APP_MODE, SERVER_PORT)
152
- **ESLint Integration**: Automatic ESLint reporting unless disabled
153
- **App.json Processing**: Custom loader for processing app.json configuration files
154
- **Development Tools**: Friendly error reporting and hot module replacement
155
- **Production Optimization**: Minification and optimization for production builds
156

157
### Default Config
158

159
Pre-computed default configuration values for all user configuration options.
160

161
```javascript { .api }
162
/**
163
 * Default configuration values for all user config options
164
 * Generated from user config schema with default values applied
165
 */
166
const defaultConfig: DefaultUserConfig;
167

168
interface DefaultUserConfig {
169
  alias: {};
170
  define: {};
171
  devPublicPath: "/";
172
  filename: "[name].js";
173
  extensions: [".js", ".jsx", ".json", ".html", ".ts", ".tsx", ".rml"];
174
  modules: ["node_modules"];
175
  devServer: {
176
    disableHostCheck: true,
177
    compress: true,
178
    transportMode: "ws",
179
    logLevel: "silent",
180
    clientLogLevel: "none",
181
    hot: true,
182
    publicPath: "/",
183
    quiet: false,
184
    watchOptions: {
185
      ignored: /node_modules/,
186
      aggregateTimeout: 600
187
    }
188
  };
189
  mock: true;
190
  externals: {};
191
  hash: false;
192
  outputAssetsPath: { js: "js", css: "css" };
193
  outputDir: "build";
194
  proxy: {};
195
  publicPath: "/";
196
  browserslist: "last 2 versions, Firefox ESR, > 1%, ie >= 9, iOS >= 8, Android >= 4";
197
  vendor: true;
198
  libraryTarget: "";
199
  library: "";
200
  libraryExport: "";
201
  terserOptions: {};
202
  cssLoaderOptions: {};
203
  lessLoaderOptions: {};
204
  sassLoaderOptions: {};
205
  postcssrc: false;
206
  compileDependencies: [];
207
  babelPlugins: [];
208
  babelPresets: [];
209
  tsChecker: false;
210
  dll: false;
211
  dllEntry: {};
212
  polyfill: "entry";
213
  // Plus additional framework-specific defaults
214
}
215
```
216

217
**Usage Example:**
218

219
```javascript
220
const { defaultConfig } = require("@builder/user-config");
221

222
// Access default values
223
console.log(defaultConfig.outputDir);     // "build"
224
console.log(defaultConfig.publicPath);    // "/"
225
console.log(defaultConfig.extensions);    // [".js", ".jsx", ".json", ...]
226

227
// Use as base for custom configuration
228
const customConfig = {
229
  ...defaultConfig,
230
  outputDir: 'dist',
231
  publicPath: '/static/'
232
};
233
```