0
# Ice.js (@ice/app)
1

2
Ice.js is a universal framework based on React.js that provides scripts and configuration for web development with zero-config support for ES6+, TypeScript, routing, state management, and multi-platform deployment (web, miniapp, Weex). It offers comprehensive tooling, a plugin system, development server with hot reloading, and optimized build processes for scalable application development.
3

4
## Package Information
5

6
- **Package Name**: @ice/app
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ice/app --save-dev`
10

11
## Core Imports
12

13
```typescript
14
import { defineConfig } from "@ice/app";
15
```
16

17
For configuration types:
18

19
```typescript
20
import type { UserConfig } from "@ice/app";
21
```
22

23
For service creation:
24

25
```typescript
26
import createService from "@ice/app/service";
27
```
28

29
For code analysis:
30

31
```typescript
32
import { analyzeImports, scanImports, getFileExports } from "@ice/app/analyze";
33
```
34

35
For logging utilities:
36

37
```typescript
38
import { logger, createLogger } from "@ice/app";
39
```
40

41
For Express types (for mock functionality):
42

43
```typescript
44
import type { Request, Response } from "@ice/app";
45
```
46

47
## Basic Usage
48

49
```typescript
50
// ice.config.ts
51
import { defineConfig } from "@ice/app";
52

53
export default defineConfig({
54
  // Development server configuration
55
  server: {
56
    host: 'localhost',
57
    port: 3000
58
  },
59
  // Module aliases
60
  alias: {
61
    '@': './src'
62
  },
63
  // Build output configuration
64
  outputDir: 'dist',
65
  // Enable TypeScript checking
66
  tsChecker: true,
67
  // CSS modules configuration
68
  cssModules: {
69
    localIdentName: '[name]__[local]--[hash:base64:5]'
70
  },
71
  // Routing configuration
72
  routes: {
73
    ignoreFiles: ['**/components/**']
74
  }
75
});
76
```
77

78
## Architecture
79

80
Ice.js is built around several key architectural components:
81

82
- **Service Layer**: Core build and development services managed by `createService`
83
- **Configuration System**: Comprehensive configuration through `defineConfig` with TypeScript support
84
- **CLI Interface**: Command-line tools for `build` and `start` operations with extensive options
85
- **Plugin System**: Extensible architecture supporting custom plugins for build pipeline customization  
86
- **Code Analysis**: Static analysis tools for import/export discovery and dependency scanning
87
- **Multi-platform Support**: Unified development experience targeting web, miniapps, and Weex platforms
88
- **Zero Configuration**: Smart defaults requiring minimal setup while maintaining full customizability
89

90
## Capabilities
91

92
### Configuration Management
93

94
Define and manage comprehensive framework configuration with full TypeScript support and validation.
95

96
```typescript { .api }
97
function defineConfig(config: UserConfig | (() => UserConfig)): UserConfig;
98

99
interface UserConfig {
100
  alias?: Record<string, string>;
101
  outputDir?: string;
102
  publicPath?: string;
103
  devPublicPath?: string;
104
  hash?: boolean | string;
105
  externals?: Record<string, string> | string[];
106
  define?: Record<string, any>;
107
  plugins?: Plugin[];
108
  routes?: RoutesConfig;
109
  server?: ServerConfig;
110
  ssr?: boolean;
111
  ssg?: boolean;
112
  proxy?: Record<string, ProxyConfig>;
113
  mock?: MockConfig | boolean;
114
  cssModules?: CSSModulesConfig | boolean;
115
  postcss?: PostCSSConfig;
116
  optimization?: OptimizationConfig;
117
  experimental?: ExperimentalConfig;
118
  // ... and many more options
119
}
120
```
121

122
[Configuration](./configuration.md)
123

124
### Command Line Interface
125

126
Powerful CLI for development and build operations with extensive configuration options and multi-platform support.
127

128
```typescript { .api }
129
// CLI Commands
130
ice build [options]    // Build project for production
131
ice start [options]    // Start development server
132

133
// Key Options
134
--target <target>      // Build target: 'web', 'weex', miniapp platforms
135
--mode <mode>         // Build mode: 'development' | 'production'  
136
--config <config>     // Custom config file path
137
--host <host>         // Development server host
138
--port <port>         // Development server port
139
--analyzer            // Bundle size analysis
140
--speedup             // Rust-based build optimization
141
```
142

143
[Command Line Interface](./cli.md)
144

145
### Service Management
146

147
Create and manage Ice.js service instances for programmatic build and development operations.
148

149
```typescript { .api }
150
function createService(options: CreateServiceOptions): Promise<{ run: () => Promise<any> }>;
151

152
interface CreateServiceOptions {
153
  rootDir: string;
154
  command: 'start' | 'build' | 'test';
155
  commandArgs: CommandArgs;
156
}
157
```
158

159
[Service Management](./service.md)
160

161
### Code Analysis
162

163
Static analysis utilities for dependency scanning, import analysis, and export discovery in JavaScript/TypeScript projects.
164

165
```typescript { .api }
166
function analyzeImports(files: string[], options: AnalyzeOptions): Promise<Set<string> | false>;
167
function scanImports(entries: string[], options?: ScanOptions): Promise<Record<string, DepScanData>>;
168
function getFileExports(options: FileExportOptions): Promise<string[]>;
169
```
170

171
[Code Analysis](./analysis.md)
172

173
### Logging Utilities
174

175
Namespaced logging system with debug controls for development and production environments.
176

177
```typescript { .api }
178
function createLogger(namespace?: string): Logger;
179

180
interface Logger {
181
  fatal(message: any, ...args: any[]): void;
182
  error(message: any, ...args: any[]): void;
183
  warn(message: any, ...args: any[]): void;
184
  log(message: any, ...args: any[]): void;
185
  info(message: any, ...args: any[]): void;
186
  start(message: any, ...args: any[]): void;
187
  success(message: any, ...args: any[]): void;
188
  ready(message: any, ...args: any[]): void;
189
  debug(message: any, ...args: any[]): void;
190
  trace(message: any, ...args: any[]): void;
191
  briefError(message: any, ...args: any[]): void;
192
}
193

194
const logger: Logger;
195
```
196

197
[Logging Utilities](./logging.md)
198

199
### Test Configuration
200

201
Helpers for configuring Jest and Vitest with Ice.js framework defaults and optimizations.
202

203
```typescript { .api }
204
function defineJestConfig(userConfig: JestConfig | (() => Promise<JestConfig>)): () => Promise<JestConfig>;
205
function defineVitestConfig(userConfig: UserConfigExport): UserConfigFn;
206
```
207

208
[Test Configuration](./testing.md)
209

210
## Core Types
211

212
```typescript { .api }
213
interface UserConfig {
214
  // Build configuration
215
  outputDir?: string;
216
  publicPath?: string;
217
  hash?: boolean | string;
218
  minify?: boolean | MinifyOptions;
219
  sourceMap?: boolean | string;
220
  
221
  // Development configuration  
222
  devPublicPath?: string;
223
  proxy?: Record<string, ProxyConfig>;
224
  mock?: MockConfig | boolean;
225
  
226
  // Module configuration
227
  alias?: Record<string, string>;
228
  externals?: Record<string, string> | string[];
229
  compileDependencies?: string[];
230
  define?: Record<string, any>;
231
  
232
  // Framework configuration
233
  routes?: RoutesConfig;
234
  ssr?: boolean;
235
  ssg?: boolean;
236
  server?: ServerConfig;
237
  plugins?: Plugin[];
238
  
239
  // Build optimization
240
  optimization?: OptimizationConfig;
241
  codeSplitting?: boolean | string;
242
  crossOriginLoading?: string;
243
  
244
  // Developer experience
245
  tsChecker?: boolean;
246
  eslint?: boolean | ESLintConfig;
247
  cssModules?: boolean | CSSModulesConfig;
248
  postcss?: PostCSSConfig;
249
  
250
  // Advanced configuration
251
  experimental?: ExperimentalConfig;
252
  transform?: TransformConfig;
253
  syntaxFeatures?: SyntaxFeatures;
254
}
255

256
interface CreateServiceOptions {
257
  rootDir: string;
258
  command: 'start' | 'build' | 'test';
259
  commandArgs: CommandArgs;
260
}
261

262
interface AnalyzeOptions {
263
  parallel?: number;
264
  analyzeRelativeImport?: boolean;
265
  alias?: Record<string, string>;
266
}
267

268
// Express types for mock functionality
269
interface Request extends express.Request {}
270
interface Response extends express.Response {}
271
```
272

273
[Type Definitions](./types.md)