0
# Type Definitions
1

2
Ice.js provides comprehensive TypeScript definitions for all framework APIs, configuration options, and plugin interfaces. These types ensure type safety and excellent developer experience with intelligent autocompletion.
3

4
## Core Types
5

6
### Configuration Types
7

8
Complete type definitions for framework configuration with all available options.
9

10
```typescript { .api }
11
interface UserConfig {
12
  /** Build output directory (default: 'build') */
13
  outputDir?: string;
14
  /** Public path for assets (default: '/') */
15
  publicPath?: string;
16
  /** Development public path override */
17
  devPublicPath?: string;
18
  /** Enable filename hashing for cache busting */
19
  hash?: boolean | string;
20
  /** Code minification settings */
21
  minify?: boolean | MinifyOptions;
22
  /** Source map generation configuration */
23
  sourceMap?: boolean | 'inline' | 'hidden' | 'nosources-cheap-source-map';
24
  /** Cross-origin loading for dynamic imports */
25
  crossOriginLoading?: 'anonymous' | 'use-credentials' | false;
26
  /** Output filename pattern for built bundles */
27
  filename?: string;
28
  
29
  /** Module path aliases for import resolution */
30
  alias?: Record<string, string>;
31
  /** External dependencies to exclude from bundle */
32
  externals?: Record<string, string> | string[];
33
  /** Dependencies to compile instead of treating as external */
34
  compileDependencies?: string[];
35
  /** Global constant definitions for DefinePlugin */
36
  define?: Record<string, any>;
37
  /** Legacy browser polyfill configuration */
38
  polyfill?: boolean | 'entry' | 'usage';
39
  
40
  /** Development server proxy configuration */
41
  proxy?: Record<string, ProxyConfig>;
42
  /** Mock service configuration */
43
  mock?: MockConfig | boolean;
44
  
45
  /** CSS Modules configuration */
46
  cssModules?: boolean | CSSModulesConfig;
47
  /** PostCSS configuration */
48
  postcss?: PostCSSConfig;
49
  
50
  /** Routing configuration */
51
  routes?: RoutesConfig;
52
  /** Enable server-side rendering */
53
  ssr?: boolean;
54
  /** Enable static site generation */
55
  ssg?: boolean;
56
  /** Data loading capabilities */
57
  dataLoader?: boolean;
58
  /** HTML generation configuration */
59
  htmlGenerating?: HtmlGeneratingConfig;
60
  
61
  /** Server-side configuration */
62
  server?: ServerConfig;
63
  /** Plugin configuration */
64
  plugins?: Plugin[];
65
  
66
  /** Build optimization settings */
67
  optimization?: OptimizationConfig;
68
  /** Code splitting configuration */
69
  codeSplitting?: boolean | 'page-only' | 'depot-granular';
70
  
71
  /** TypeScript type checking */
72
  tsChecker?: boolean;
73
  /** ESLint integration */
74
  eslint?: boolean | ESLintConfig;
75
  /** Console log levels to drop in production */
76
  dropLogLevel?: DropType[];
77
  /** Bundle analyzer integration */
78
  analyzer?: boolean;
79
  /** Enable Rust-based build optimization */
80
  speedup?: boolean;
81
  
82
  /** Experimental features */
83
  experimental?: ExperimentalConfig;
84
  /** Code transformation rules */
85
  transform?: TransformConfig;
86
  /** Syntax feature flags */
87
  syntaxFeatures?: SyntaxFeatures;
88
  /** Feature polyfill configuration */
89
  featurePolyfill?: PolyfillConfig;
90
  /** Direct webpack configuration modification (not recommended) */
91
  webpack?: (config: WebpackConfig, { webpack }: { webpack: any }) => WebpackConfig;
92
  /** Data loading configuration for SSR/SSG */
93
  dataLoader?: boolean | DataLoaderConfig;
94
}
95

96
interface MinifyOptions {
97
  type: 'terser' | 'swc';
98
  options?: MinimizerOptions<Record<string, any>>;
99
}
100

101
type DropType = 'trace' | 'debug' | 'log' | 'info' | 'warn' | 'error';
102
```
103

104
### Service Types
105

106
Type definitions for service management and programmatic API access.
107

108
```typescript { .api }
109
interface CreateServiceOptions {
110
  /** Project root directory path */
111
  rootDir: string;
112
  /** Command to execute */
113
  command: CommandName;
114
  /** Command-line arguments and options */
115
  commandArgs: CommandArgs;
116
}
117

118
type CommandName = 'start' | 'build' | 'test';
119

120
interface CommandArgs {
121
  /** Build/start target platform */
122
  target?: BuildTarget;
123
  /** Build mode */
124
  mode?: 'development' | 'production';
125
  /** Configuration file path */
126
  config?: string;
127
  /** Development server host */
128
  host?: string;
129
  /** Development server port */
130
  port?: number;
131
  /** Enable bundle analyzer */
132
  analyzer?: boolean;
133
  /** Enable HTTPS */
134
  https?: boolean | 'self-signed';
135
  /** Force cache clear */
136
  force?: boolean;
137
  /** Enable speedup mode */
138
  speedup?: boolean;
139
  /** Browser opening behavior */
140
  open?: boolean | string;
141
  /** Disable browser opening */
142
  'no-open'?: boolean;
143
  /** Disable mock service */
144
  'no-mock'?: boolean;
145
  /** List available pages */
146
  list?: boolean;
147
  /** Custom plugin */
148
  plugin?: string;
149
  /** Additional unknown options */
150
  [key: string]: any;
151
}
152

153
type BuildTarget = 
154
  | 'web'
155
  | 'weex'
156
  | 'ali-miniapp'
157
  | 'wechat-miniprogram'
158
  | 'bytedance-microapp'
159
  | 'baidu-smartprogram'
160
  | 'kuaishou-miniprogram';
161

162
interface ServiceInstance {
163
  /** Execute the service operation */
164
  run(): Promise<any>;
165
}
166
```
167

168
### Development Configuration Types
169

170
Type definitions for development server and build pipeline configuration.
171

172
```typescript { .api }
173
interface ProxyConfig {
174
  /** Target server URL */
175
  target: string;
176
  /** Change origin header */
177
  changeOrigin?: boolean;
178
  /** Path rewriting rules */
179
  pathRewrite?: Record<string, string>;
180
  /** Custom headers */
181
  headers?: Record<string, string>;
182
  /** WebSocket proxying */
183
  ws?: boolean;
184
  /** Secure connection */
185
  secure?: boolean;
186
  /** Log level */
187
  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
188
}
189

190
interface MockConfig {
191
  /** Files to exclude from mocking */
192
  exclude?: string[];
193
  /** Files to include in mocking */
194
  include?: string[];
195
  /** Mock data directory */
196
  dir?: string;
197
  /** Enable/disable mock middleware */
198
  enable?: boolean;
199
}
200
```
201

202
### Styling Configuration Types
203

204
Type definitions for CSS processing and styling configuration.
205

206
```typescript { .api }
207
interface CSSModulesConfig {
208
  /** Local class name generation pattern */
209
  localIdentName?: string;
210
  /** Hash digest method */
211
  hashPrefix?: string;
212
  /** Generate scoped name function */
213
  generateScopedName?: (name: string, filename: string, css: string) => string;
214
  /** Export globals */
215
  exportGlobals?: boolean;
216
  /** CSS Modules mode */
217
  mode?: 'local' | 'global' | 'pure';
218
}
219

220
interface PostCSSConfig {
221
  /** PostCSS plugins */
222
  plugins?: any[];
223
  /** PostCSS options */
224
  options?: Record<string, any>;
225
  /** Custom PostCSS config file path */
226
  config?: string;
227
}
228
```
229

230
### Routing Configuration Types
231

232
Type definitions for file-system based routing and route configuration.
233

234
```typescript { .api }
235
interface RoutesConfig {
236
  /** Files to ignore during route generation */
237
  ignoreFiles?: string[];
238
  /** Custom route definitions */
239
  defineRoutes?: (defineRoute: DefineRouteFunction) => void;
240
  /** Route-specific configuration */
241
  config?: Record<string, RouteConfig>;
242
  /** Initial entry injection configuration */
243
  injectInitialEntry?: boolean | InjectInitialEntryConfig;
244
}
245

246
interface RouteConfig {
247
  /** Page title */
248
  title?: string;
249
  /** Meta tags */
250
  meta?: Record<string, any>;
251
  /** Authentication requirements */
252
  auth?: boolean | string[];
253
  /** Layout component */
254
  layout?: string;
255
  /** Route-specific data loading */
256
  dataLoader?: boolean;
257
}
258

259
interface DefineRouteFunction {
260
  (path: string, file: string, options?: RouteOptions): void;
261
}
262

263
interface RouteOptions {
264
  /** Index route flag */
265
  index?: boolean;
266
  /** Case-sensitive matching */
267
  caseSensitive?: boolean;
268
  /** Route ID */
269
  id?: string;
270
}
271

272
interface InjectInitialEntryConfig {
273
  /** Enable injection */
274
  enable?: boolean;
275
  /** Custom injection logic */
276
  inject?: (entry: string) => string;
277
}
278
```
279

280
### Server Configuration Types
281

282
Type definitions for server-side rendering and compilation.
283

284
```typescript { .api }
285
interface ServerConfig {
286
  /** Enable server-side rendering */
287
  onDemand?: boolean;
288
  /** Server output format */
289
  format?: 'esm' | 'cjs';
290
  /** Server bundling configuration */
291
  bundle?: boolean;
292
  /** Files to ignore in server compilation */
293
  ignores?: string[];
294
  /** Server external dependencies */
295
  externals?: string[];
296
  /** Bundler selection for server */
297
  bundler?: 'webpack' | 'rspack';
298
  /** Custom webpack configuration for server */
299
  webpackConfig?: ModifyWebpackConfig;
300
  /** Server entry file */
301
  entry?: string;
302
  /** Server output directory */
303
  outputDir?: string;
304
}
305

306
type ModifyWebpackConfig = (config: WebpackConfig, options: WebpackConfigOptions) => WebpackConfig;
307

308
interface WebpackConfigOptions {
309
  /** Build context */
310
  context: BuildContext;
311
  /** Command being executed */
312
  command: CommandName;
313
  /** Task configuration */
314
  taskConfig: TaskConfig;
315
}
316
```
317

318
### Plugin System Types
319

320
Type definitions for the plugin system and extensibility.
321

322
```typescript { .api }
323
interface Plugin<Options = any> {
324
  (api: PluginAPI, options?: Options): void;
325
}
326

327
interface PluginAPI extends ExtendsPluginAPI {
328
  /** Register build hooks */
329
  onHook: (name: string, fn: Function) => void;
330
  /** Modify webpack configuration */
331
  modifyWebpackConfig: ModifyWebpackConfig;
332
  /** Add runtime options */
333
  addRuntimeOptions: (options: RuntimeOptions) => void;
334
  /** Register generator plugins */
335
  addPlugin: (plugin: GeneratorPlugin) => void;
336
  /** Add entry code */
337
  addEntryCode: (code: string) => void;
338
  /** Add entry imports */
339
  addEntryImport: (importDeclaration: string) => void;
340
}
341

342
interface ExtendsPluginAPI {
343
  /** Add export declarations */
344
  addExport: (declarationData: DeclarationData) => void;
345
  /** Add export type declarations */
346
  addExportTypes: (declarationData: DeclarationData) => void;
347
  /** Add runtime options */
348
  addRuntimeOptions: (declarationData: DeclarationData) => void;
349
  /** Remove runtime options */
350
  removeRuntimeOptions: (removeSource: string | string[]) => void;
351
  /** Add route types */
352
  addRouteTypes: (declarationData: DeclarationData) => void;
353
  /** Add render files */
354
  addRenderFile: (templateFile: string, targetFile: string) => void;
355
  /** Add render templates */
356
  addRenderTemplate: (templates: RenderTemplate[]) => void;
357
}
358

359
interface PluginData {
360
  /** Plugin name */
361
  name: string;
362
  /** Plugin setup function */
363
  setup: (api: PluginAPI) => void;
364
  /** Plugin options */
365
  options?: any;
366
}
367
```
368

369
### Code Analysis Types
370

371
Type definitions for static analysis and dependency scanning.
372

373
```typescript { .api }
374
interface AnalyzeOptions {
375
  /** Number of parallel analysis operations (default: 10) */
376
  parallel?: number;
377
  /** Whether to analyze relative imports (default: false) */
378
  analyzeRelativeImport?: boolean;
379
  /** Module path aliases for import resolution */
380
  alias?: Alias;
381
}
382

383
interface ScanOptions {
384
  /** Project root directory */
385
  rootDir?: string;
386
  /** Module path aliases */
387
  alias?: Alias;
388
  /** Existing dependency imports to merge with */
389
  depImports?: Record<string, DepScanData>;
390
  /** ESBuild plugins for custom file processing */
391
  plugins?: Plugin[];
392
  /** Patterns to exclude from scanning */
393
  exclude?: string[];
394
  /** Files to ignore during scanning */
395
  ignores?: string[];
396
}
397

398
interface DepScanData {
399
  /** Imported module specifiers */
400
  imports: Set<string>;
401
  /** Dynamic import specifiers */
402
  dynamicImports: Set<string>;
403
  /** Export names from the module */
404
  exports: Set<string>;
405
  /** File dependencies */
406
  deps: Set<string>;
407
  /** Whether the module has side effects */
408
  hasSideEffects: boolean;
409
}
410

411
interface FileExportOptions {
412
  /** File path (relative or absolute) */
413
  file: string;
414
  /** Project root directory */
415
  rootDir: string;
416
}
417

418
type Alias = Record<string, string>;
419
type AliasWithEmpty = Record<string, string | false>;
420
```
421

422
### Generator and Template Types
423

424
Type definitions for code generation and template system.
425

426
```typescript { .api }
427
interface DeclarationData {
428
  /** Import source */
429
  source: string;
430
  /** Import specifier */
431
  specifier?: string;
432
  /** Import type */
433
  type?: 'default' | 'namespace' | 'named';
434
  /** Export name */
435
  exportName?: string;
436
  /** Type only import */
437
  typeOnly?: boolean;
438
}
439

440
interface RenderData {
441
  /** Template variables */
442
  [key: string]: any;
443
}
444

445
interface TemplateOptions {
446
  /** Template engine options */
447
  engine?: 'ejs' | 'handlebars';
448
  /** Template data */
449
  data?: RenderData;
450
  /** Template helpers */
451
  helpers?: Record<string, Function>;
452
}
453

454
type RenderTemplate = [string, string, TemplateOptions?];
455

456
interface ExtraData {
457
  /** Additional template data */
458
  [key: string]: any;
459
}
460
```
461

462
### Optimization Types
463

464
Type definitions for build optimization and performance configuration.
465

466
```typescript { .api }
467
interface OptimizationConfig {
468
  /** Router optimization (remove when single route) */
469
  router?: boolean;
470
  /** Force disable router dependencies */
471
  disableRouter?: boolean;
472
  /** Package import optimization for barrel files */
473
  optimizePackageImport?: string[] | boolean;
474
}
475

476
interface SyntaxFeatures {
477
  /** Export default from syntax support */
478
  exportDefaultFrom?: boolean;
479
  /** Function bind operator support */
480
  functionBind?: boolean;
481
}
482

483
interface ExperimentalConfig {
484
  /** Experimental router features */
485
  router?: boolean;
486
  /** Experimental build features */
487
  build?: Record<string, any>;
488
  /** Experimental development features */
489
  dev?: Record<string, any>;
490
}
491

492
interface TransformConfig {
493
  /** File pattern to transformer mapping */
494
  [pattern: string]: {
495
    /** Loader to use */
496
    loader?: string;
497
    /** Loader options */
498
    options?: Record<string, any>;
499
  };
500
}
501

502
interface PolyfillConfig {
503
  /** Feature polyfills */
504
  features?: string[];
505
  /** Polyfill mode */
506
  mode?: 'usage' | 'entry';
507
  /** Core-js version */
508
  corejs?: string;
509
}
510

511
interface DataLoaderConfig {
512
  /** Custom fetcher configuration */
513
  fetcher?: {
514
    packageName: string;
515
    method?: string;
516
  };
517
}
518
```
519

520
### HTML Generation Types
521

522
Type definitions for HTML generation and static site generation.
523

524
```typescript { .api }
525
interface HtmlGeneratingConfig {
526
  /** Generation mode */
527
  mode?: HtmlGeneratingMode;
528
  /** Custom HTML template */
529
  template?: string;
530
  /** Inject runtime configuration */
531
  inject?: boolean;
532
  /** Meta tag configuration */
533
  meta?: Record<string, string>;
534
  /** Link tag configuration */
535
  links?: Array<{ rel: string; href: string; [key: string]: string }>;
536
  /** Script tag configuration */
537
  scripts?: Array<{ src: string; [key: string]: string }>;
538
}
539

540
type HtmlGeneratingMode = 'cleanUrl' | 'compat';
541
```
542

543
### Utility Types
544

545
Additional utility types for framework internals and advanced usage.
546

547
```typescript { .api }
548
interface CreateLoggerReturnType {
549
  /** Debug logging */
550
  debug: (...args: any[]) => void;
551
  /** Info logging */
552
  info: (...args: any[]) => void;
553
  /** Warning logging */
554
  warn: (...args: any[]) => void;
555
  /** Error logging */
556
  error: (...args: any[]) => void;
557
}
558

559
interface Urls {
560
  /** Local development URL */
561
  localUrlForTerminal: string;
562
  /** Local development URL for browser */
563
  localUrlForBrowser: string;
564
  /** Network URL for terminal */
565
  lanUrlForTerminal?: string;
566
  /** Network URL for browser */
567
  lanUrlForBrowser?: string;
568
}
569

570
interface WatchEvent {
571
  /** Event type */
572
  type: 'add' | 'change' | 'unlink';
573
  /** File path */
574
  file: string;
575
  /** Additional event data */
576
  data?: any;
577
}
578

579
interface BuildContext {
580
  /** Command being executed */
581
  command: CommandName;
582
  /** Command arguments */
583
  commandArgs: CommandArgs;
584
  /** Root directory */
585
  rootDir: string;
586
  /** User configuration */
587
  userConfig: UserConfig;
588
}
589

590
interface TaskConfig {
591
  /** Task name */
592
  name: string;
593
  /** Task configuration */
594
  config: any;
595
  /** Task context */
596
  context: BuildContext;
597
}
598
```
599

600
### Logging Types
601

602
Type definitions for the logging system with namespacing and debug controls.
603

604
```typescript { .api }
605
interface Logger {
606
  /** Fatal level logging */
607
  fatal(message: any, ...args: any[]): void;
608
  /** Error level logging */
609
  error(message: any, ...args: any[]): void;
610
  /** Warning level logging */
611
  warn(message: any, ...args: any[]): void;
612
  /** Standard logging */
613
  log(message: any, ...args: any[]): void;
614
  /** Info level logging */
615
  info(message: any, ...args: any[]): void;
616
  /** Start event logging */
617
  start(message: any, ...args: any[]): void;
618
  /** Success event logging */
619
  success(message: any, ...args: any[]): void;
620
  /** Ready event logging */
621
  ready(message: any, ...args: any[]): void;
622
  /** Debug level logging */
623
  debug(message: any, ...args: any[]): void;
624
  /** Trace level logging */
625
  trace(message: any, ...args: any[]): void;
626
  /** Brief error logging with debug instructions */
627
  briefError(message: any, ...args: any[]): void;
628
}
629

630
type ICELogNamespace = string;
631
type CreateLogger = (namespace?: ICELogNamespace) => Logger;
632
```
633

634
### External Type Re-exports
635

636
Types re-exported from external packages for convenience.
637

638
```typescript { .api }
639
// Re-exported from @ice/shared-config/types
640
interface Config {
641
  /** Webpack configuration */
642
  webpack?: WebpackConfiguration;
643
  /** Build configuration */
644
  build?: BuildConfig;
645
  /** Development configuration */
646
  dev?: DevConfig;
647
}
648

649
// Re-exported from Express for mock functionality
650
interface Request {
651
  /** Request body */
652
  body: any;
653
  /** Request headers */
654
  headers: Record<string, string>;
655
  /** Request parameters */
656
  params: Record<string, string>;
657
  /** Request query */
658
  query: Record<string, any>;
659
  /** Request URL */
660
  url: string;
661
  /** Request method */
662
  method: string;
663
}
664

665
interface Response {
666
  /** Send response */
667
  send: (data: any) => void;
668
  /** Send JSON response */
669
  json: (data: any) => void;
670
  /** Set response status */
671
  status: (code: number) => Response;
672
  /** Set response headers */
673
  set: (headers: Record<string, string>) => Response;
674
}
675
```
676

677
These comprehensive type definitions ensure full type safety when working with Ice.js APIs and provide excellent IntelliSense support in TypeScript-enabled editors.