0
# ice.js
1

2
ice.js is a command line interface and builtin plugin system for the icejs React.js-based universal framework. It provides essential development commands and integrates multiple build plugins for various functionalities like authentication, routing, state management, server-side rendering, and multi-page applications. The tool serves as the core development toolchain for icejs applications, enabling developers to quickly scaffold, develop, and build React applications with built-in support for TypeScript, CSS modules, and modern JavaScript features.
3

4
## Package Information
5

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

11
## Core Imports
12

13
For programmatic usage (framework integration):
14

15
```javascript
16
// Main module exports an anonymous function via module.exports
17
const createIceCli = require("ice.js");
18
```
19

20
ES Modules:
21

22
```javascript
23
// ES module default import of the main function
24
import createIceCli from "ice.js";
25
```
26

27
For accessing the plugin system directly:
28

29
```javascript
30
// getBuiltInPlugins uses CommonJS export = syntax
31
const getBuiltInPlugins = require("ice.js/lib/getBuiltInPlugins");
32
```
33

34
## Basic Usage
35

36
### CLI Usage
37

38
Most common usage is through the command line interface:
39

40
```bash
41
# Install ice.js as a dev dependency
42
npm install ice.js --save-dev
43

44
# Add scripts to package.json
45
{
46
  "scripts": {
47
    "start": "icejs start",
48
    "build": "icejs build",
49
    "test": "icejs test"
50
  }
51
}
52

53
# Run development server
54
npm start
55

56
# Build for production
57
npm run build
58

59
# Run tests
60
npm test
61
```
62

63
### Programmatic Usage
64

65
For framework integration or custom tooling:
66

67
```javascript
68
const createIceCli = require("ice.js");
69
const packageInfo = require("./package.json");
70

71
// Create CLI with custom framework name
72
createIceCli("my-framework", {
73
  packageInfo: packageInfo,
74
  extendCli: (program) => {
75
    // Add custom commands
76
    program
77
      .command("custom")
78
      .description("custom command")
79
      .action(() => {
80
        console.log("Custom command executed");
81
      });
82
  }
83
});
84
```
85

86
## Architecture
87

88
ice.js is built around several key components:
89

90
- **CLI Interface**: Commander.js-based command line interface with standard development commands
91
- **Plugin System**: Extensible plugin architecture with builtin plugins for common functionality
92
- **Build Scripts Integration**: Built on @alib/build-scripts for consistent build processes
93
- **Child Process Management**: Fork-based process management for development server isolation
94
- **Configuration Management**: Flexible configuration system supporting multiple formats
95

96
## Capabilities
97

98
### Command Line Interface
99

100
Core CLI functionality providing `start`, `build`, and `test` commands with configurable options and plugin integration.
101

102
```javascript { .api }
103
// CLI commands accessible via icejs executable
104
// icejs <command> [options]
105

106
// Available commands:
107
// - start: Start development server
108
// - build: Build project for production  
109
// - test: Run Jest tests
110
```
111

112
[CLI Commands](./cli-commands.md)
113

114
### Plugin System
115

116
Builtin plugin system that automatically configures development and build processes based on user configuration and project requirements.
117

118
```javascript { .api }
119
/**
120
 * Get builtin plugins based on user configuration
121
 * @param {Object} userConfig - User configuration object
122
 * @returns {Array} Array of plugin configurations
123
 */
124
function getBuiltInPlugins(userConfig);
125
```
126

127
[Plugin System](./plugin-system.md)
128

129
### Framework Integration
130

131
Programmatic interface for integrating ice.js into custom frameworks and toolchains.
132

133
```javascript { .api }
134
/**
135
 * Create CLI with framework integration (module.exports function)
136
 * @param {string} frameworkName - Name of the framework
137
 * @param {Object} options - Configuration options (destructured)
138
 * @param {Object} options.packageInfo - Package.json information
139
 * @param {Function} [options.extendCli] - Function to extend CLI with custom commands
140
 */
141
module.exports = function(frameworkName, { packageInfo, extendCli });
142
```
143

144
[Framework Integration](./framework-integration.md)
145

146
## Types
147

148
```javascript { .api }
149
/**
150
 * User configuration object
151
 * @typedef {Object} UserConfig
152
 * @property {boolean} [disableRuntime] - Disable runtime features
153
 * @property {boolean} [ssr] - Enable server-side rendering
154
 * @property {boolean} [store] - Enable state management (default: true)
155
 * @property {boolean} [auth] - Enable authentication (default: true)
156
 * @property {Array} [plugins] - Additional user plugins
157
 */
158

159
/**
160
 * Package information object (standard package.json structure)
161
 * @typedef {Object} PackageInfo
162
 * @property {string} name - Package name
163
 * @property {string} version - Package version
164
 * @property {Object} engines - Node.js engine requirements
165
 * @property {string} engines.node - Node.js version requirement (e.g., ">=10.13.0")
166
 * @property {Object} [__ICEJS_INFO__] - Ice.js framework information (auto-added)
167
 * @property {string} [__ICEJS_INFO__.name] - Ice.js package name ("ice.js")
168
 * @property {string} [__ICEJS_INFO__.version] - Ice.js package version
169
 */
170

171
/**
172
 * Plugin configuration
173
 * @typedef {string|Array} PluginConfig
174
 * - String: Plugin name
175
 * - Array: [pluginName, options]
176
 */
177
```