0
# Configuration Management
1

2
Ice.js provides comprehensive configuration management through the `defineConfig` function and `UserConfig` interface, enabling developers to customize every aspect of the build and development process with full TypeScript support.
3

4
## Capabilities
5

6
### Define Configuration
7

8
Creates a typed configuration object with validation and intelligent defaults.
9

10
```typescript { .api }
11
/**
12
 * Define framework configuration with TypeScript support and validation
13
 * @param config - Configuration object or function returning configuration
14
 * @returns Validated UserConfig object
15
 */
16
function defineConfig(config: UserConfig | (() => UserConfig)): UserConfig;
17
```
18

19
**Usage Examples:**
20

21
```typescript
22
import { defineConfig } from "@ice/app";
23

24
// Object configuration
25
export default defineConfig({
26
  outputDir: 'build',
27
  publicPath: '/my-app/',
28
  hash: true,
29
  plugins: []
30
});
31

32
// Function configuration (for dynamic config)
33
export default defineConfig(() => {
34
  const isProduction = process.env.NODE_ENV === 'production';
35
  
36
  return {
37
    outputDir: isProduction ? 'dist' : 'dev',
38
    minify: isProduction,
39
    sourceMap: !isProduction
40
  };
41
});
42
```
43

44
### Build Configuration
45

46
Configure build output, asset handling, and optimization settings.
47

48
```typescript { .api }
49
interface BuildConfig {
50
  /** Build output directory (default: 'build') */
51
  outputDir?: string;
52
  /** Public path for assets (default: '/') */
53
  publicPath?: string;
54
  /** Development public path override */
55
  devPublicPath?: string;
56
  /** Enable filename hashing for cache busting */
57
  hash?: boolean | string;
58
  /** Code minification settings */
59
  minify?: boolean | MinifyOptions;
60
  /** Source map generation */
61
  sourceMap?: boolean | 'inline' | 'hidden' | 'nosources-cheap-source-map';
62
  /** Cross-origin loading for dynamic imports */
63
  crossOriginLoading?: 'anonymous' | 'use-credentials' | false;
64
  /** Output filename pattern for built bundles */
65
  filename?: string;
66
}
67

68
interface MinifyOptions {
69
  type: 'terser' | 'swc';
70
  options?: Record<string, any>;
71
}
72
```
73

74
### Module Configuration
75

76
Configure module resolution, aliases, and external dependencies.
77

78
```typescript { .api }
79
interface ModuleConfig {
80
  /** Module path aliases for import resolution */
81
  alias?: Record<string, string>;
82
  /** External dependencies to exclude from bundle */
83
  externals?: Record<string, string> | string[];
84
  /** Dependencies to compile (instead of treating as external) */
85
  compileDependencies?: string[];
86
  /** Global constant definitions for DefinePlugin */
87
  define?: Record<string, any>;
88
  /** Legacy browser polyfill configuration */
89
  polyfill?: boolean | 'entry' | 'usage';
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
export default defineConfig({
97
  alias: {
98
    '@': './src',
99
    '@components': './src/components',
100
    '@utils': './src/utils'
101
  },
102
  externals: {
103
    'react': 'React',
104
    'react-dom': 'ReactDOM'
105
  },
106
  define: {
107
    __VERSION__: JSON.stringify(process.env.npm_package_version),
108
    __DEV__: process.env.NODE_ENV === 'development'
109
  }
110
});
111
```
112

113
### Development Configuration
114

115
Configure development server, proxying, and hot reload behavior.
116

117
```typescript { .api }
118
interface DevelopmentConfig {
119
  /** Development server proxy configuration */
120
  proxy?: Record<string, ProxyConfig>;
121
  /** Mock service configuration */
122
  mock?: MockConfig | boolean;
123
  /** Force cache directory removal on start */
124
  force?: boolean;
125
  /** Development server host */
126
  host?: string;
127
  /** Development server port */
128
  port?: number;
129
  /** Enable HTTPS */
130
  https?: boolean | 'self-signed';
131
  /** Automatically open browser */
132
  open?: boolean | string;
133
}
134

135
interface ProxyConfig {
136
  target: string;
137
  changeOrigin?: boolean;
138
  pathRewrite?: Record<string, string>;
139
  headers?: Record<string, string>;
140
}
141

142
interface MockConfig {
143
  exclude?: string[];
144
  include?: string[];
145
}
146
```
147

148
### Styling Configuration  
149

150
Configure CSS processing, modules, and PostCSS plugins.
151

152
```typescript { .api }
153
interface StylingConfig {
154
  /** CSS Modules configuration */
155
  cssModules?: boolean | CSSModulesConfig;
156
  /** PostCSS configuration */
157
  postcss?: PostCSSConfig;
158
  /** Global style glob patterns */
159
  globalStyleGlobPattern?: string[];
160
}
161

162
interface CSSModulesConfig {
163
  /** Local class name generation pattern */
164
  localIdentName?: string;
165
  /** Hash digest method */
166
  hashPrefix?: string;
167
  /** Generate source maps for CSS modules */
168
  generateScopedName?: (name: string, filename: string, css: string) => string;
169
}
170

171
interface PostCSSConfig {
172
  plugins?: any[];
173
  options?: Record<string, any>;
174
}
175
```
176

177
### Routing Configuration
178

179
Configure file-system based routing and route generation.
180

181
```typescript { .api }
182
interface RoutesConfig {
183
  /** Files to ignore during route generation */
184
  ignoreFiles?: string[];
185
  /** Custom route definitions */
186
  defineRoutes?: (defineRoute: DefineRouteFunction) => void;
187
  /** Route-specific configuration */
188
  config?: Record<string, RouteConfig>;
189
  /** Initial entry injection configuration */
190
  injectInitialEntry?: boolean | InjectInitialEntryConfig;
191
}
192

193
interface RouteConfig {
194
  title?: string;
195
  meta?: Record<string, any>;
196
  auth?: boolean | string[];
197
}
198
```
199

200
### Server Configuration
201

202
Configure server-side rendering and compilation settings.
203

204
```typescript { .api }
205
interface ServerConfig {
206
  /** Enable server-side rendering */
207
  onDemand?: boolean;
208
  /** Server output format */
209
  format?: 'esm' | 'cjs';
210
  /** Server bundling configuration */
211
  bundle?: boolean;
212
  /** Files to ignore in server compilation */
213
  ignores?: string[];
214
  /** Server external dependencies */
215
  externals?: string[];
216
  /** Bundler selection for server */
217
  bundler?: 'webpack' | 'rspack';
218
  /** Custom webpack configuration for server */
219
  webpackConfig?: (config: WebpackConfig) => WebpackConfig;
220
}
221
```
222

223
### Plugin Configuration
224

225
Configure and extend Ice.js functionality through plugins.
226

227
```typescript { .api }
228
interface PluginConfig {
229
  /** Plugin array for extending framework functionality */
230
  plugins?: Plugin[];
231
}
232

233
interface Plugin<Options = any> {
234
  (api: PluginAPI, options?: Options): void;
235
}
236

237
interface PluginAPI {
238
  /** Register build hooks */
239
  onHook: (name: string, fn: Function) => void;
240
  /** Modify webpack configuration */
241
  modifyWebpackConfig: (fn: ModifyWebpackConfig) => void;
242
  /** Add runtime options */
243
  addRuntimeOptions: (options: RuntimeOptions) => void;
244
  /** Register generator plugins */
245
  addPlugin: (plugin: GeneratorPlugin) => void;
246
}
247
```
248

249
### Optimization Configuration
250

251
Configure build optimizations and performance settings.
252

253
```typescript { .api }
254
interface OptimizationConfig {
255
  /** Router optimization (remove when single route) */
256
  router?: boolean;
257
  /** Force disable router dependencies */
258
  disableRouter?: boolean;
259
  /** Package import optimization for barrel files */
260
  optimizePackageImport?: string[] | boolean;
261
}
262

263
interface CodeSplittingConfig {
264
  /** Enable code splitting */
265
  codeSplitting?: boolean | 'page-only' | 'depot-granular';
266
}
267
```
268

269
### Rendering Configuration
270

271
Configure rendering modes and static generation.
272

273
```typescript { .api }
274
interface RenderingConfig {
275
  /** Enable server-side rendering */
276
  ssr?: boolean;
277
  /** Enable static site generation */
278
  ssg?: boolean;
279
  /** Data loading capabilities */
280
  dataLoader?: boolean;
281
  /** HTML generation configuration */
282
  htmlGenerating?: HtmlGeneratingConfig;
283
}
284

285
interface HtmlGeneratingConfig {
286
  /** Generation mode */
287
  mode?: 'cleanUrl' | 'compat';
288
  /** Custom HTML template */
289
  template?: string;
290
  /** Inject runtime configuration */
291
  inject?: boolean;
292
}
293
```
294

295
### Developer Experience Configuration
296

297
Configure development tools and quality checks.
298

299
```typescript { .api }
300
interface DeveloperExperienceConfig {
301
  /** TypeScript type checking */
302
  tsChecker?: boolean;
303
  /** ESLint integration */
304
  eslint?: boolean | ESLintConfig;
305
  /** Console log levels to drop in production */
306
  dropLogLevel?: ('trace' | 'debug' | 'log' | 'info' | 'warn' | 'error')[];
307
  /** Bundle analyzer integration */
308
  analyzer?: boolean;
309
  /** Speedup with Rust tools */
310
  speedup?: boolean;
311
}
312

313
interface ESLintConfig {
314
  files?: string[];
315
  exclude?: string[];
316
  options?: Record<string, any>;
317
}
318
```
319

320
### Advanced Configuration
321

322
Configure experimental features and advanced build settings.
323

324
```typescript { .api }
325
interface AdvancedConfig {
326
  /** Experimental features */
327
  experimental?: ExperimentalConfig;
328
  /** Code transformation rules */
329
  transform?: TransformConfig;
330
  /** Syntax feature flags */
331
  syntaxFeatures?: SyntaxFeatures;
332
  /** Feature polyfill configuration */
333
  featurePolyfill?: PolyfillConfig;
334
  /** Direct webpack configuration modification (not recommended) */
335
  webpack?: (config: WebpackConfig, { webpack }: { webpack: any }) => WebpackConfig;
336
  /** Data loading configuration for SSR/SSG */
337
  dataLoader?: boolean | DataLoaderConfig;
338
}
339

340
interface ExperimentalConfig {
341
  /** Experimental router features */
342
  router?: boolean;
343
  /** Experimental build features */
344
  build?: Record<string, any>;
345
}
346

347
interface SyntaxFeatures {
348
  /** Export default from syntax */
349
  exportDefaultFrom?: boolean;
350
  /** Function bind operator */
351
  functionBind?: boolean;
352
}
353

354
interface TransformConfig {
355
  /** File patterns and transform rules */
356
  [pattern: string]: {
357
    loader?: string;
358
    options?: Record<string, any>;
359
  };
360
}
361

362
interface DataLoaderConfig {
363
  /** Custom fetcher configuration */
364
  fetcher?: {
365
    packageName: string;
366
    method?: string;
367
  };
368
}
369

370
interface PolyfillConfig {
371
  /** AbortController polyfill for legacy browsers */
372
  abortcontroller?: boolean | string;
373
}
374
```
375

376
## Complete Configuration Example
377

378
```typescript
379
import { defineConfig } from "@ice/app";
380

381
export default defineConfig({
382
  // Build configuration
383
  outputDir: 'dist',
384
  publicPath: '/',
385
  hash: true,
386
  minify: {
387
    type: 'swc',
388
    options: {
389
      compress: true,
390
      mangle: true
391
    }
392
  },
393
  sourceMap: 'hidden',
394

395
  // Module configuration
396
  alias: {
397
    '@': './src',
398
    '@components': './src/components',
399
    '@utils': './src/utils'
400
  },
401
  define: {
402
    __VERSION__: JSON.stringify('1.0.0'),
403
    __API_URL__: JSON.stringify(process.env.API_URL)
404
  },
405

406
  // Development configuration
407
  proxy: {
408
    '/api': {
409
      target: 'http://localhost:8080',
410
      changeOrigin: true,
411
      pathRewrite: {
412
        '^/api': ''
413
      }
414
    }
415
  },
416
  mock: {
417
    exclude: ['**/components/**']
418
  },
419

420
  // Styling configuration
421
  cssModules: {
422
    localIdentName: '[name]__[local]--[hash:base64:5]'
423
  },
424
  postcss: {
425
    plugins: [
426
      require('autoprefixer'),
427
      require('postcss-preset-env')
428
    ]
429
  },
430

431
  // Routing configuration
432
  routes: {
433
    ignoreFiles: ['**/components/**', '**/*.test.*'],
434
    config: {
435
      '/admin': {
436
        auth: ['admin'],
437
        title: 'Admin Panel'
438
      }
439
    }
440
  },
441

442
  // Server configuration
443
  server: {
444
    format: 'esm',
445
    bundle: true,
446
    externals: ['react', 'react-dom']
447
  },
448

449
  // Optimization configuration
450
  optimization: {
451
    router: true,
452
    optimizePackageImport: ['antd', 'lodash']
453
  },
454

455
  // Rendering configuration
456
  ssr: true,
457
  ssg: false,
458
  dataLoader: true,
459

460
  // Developer experience
461
  tsChecker: true,
462
  eslint: {
463
    files: ['src/**/*.{ts,tsx}'],
464
    exclude: ['**/*.test.*']
465
  },
466
  dropLogLevel: ['debug', 'trace'],
467

468
  // Plugins
469
  plugins: [
470
    // Custom plugins
471
  ]
472
});
473
```