CLI Commands

Core command line interface functionality providing development, build, and testing commands for icejs applications.

Capabilities

icejs Command

Main CLI executable that provides access to all ice.js functionality.

# Basic usage
icejs <command> [options]

# Global options
icejs --version, -V    # Output version number
icejs --help, -h       # Output usage information

Usage Examples:

# Show version
icejs --version

# Show help
icejs --help

# Show help for specific command
icejs start --help

start Command

Starts the development server with hot reloading and development optimizations.

# Start development server
icejs start [options]

# Options:
#   --config <config>     Use custom config file
#   -h, --host <host>     Dev server host (default: 0.0.0.0)
#   -p, --port <port>     Dev server port
#   --help               Display help for command

Usage Examples:

# Start with default settings
icejs start

# Start on specific host and port
icejs start --host localhost --port 3000

# Start with custom config
icejs start --config build.custom.json

# Start and let system choose available port
icejs start --port 0

Behavior:

• Automatically detects available ports if specified port is in use
• Enables hot module replacement for development
• Serves static assets and handles routing for SPAs
• Integrates with all configured builtin plugins
• Runs in child process for better isolation

build Command

Builds the project for production with optimizations and asset bundling.

# Build project for production
icejs build [options]

# Options:
#   --config <config>     Use custom config file
#   --help               Display help for command

Usage Examples:

# Build with default configuration
icejs build

# Build with custom config file
icejs build --config build.production.json

# Build and output verbose information
NODE_ENV=production icejs build

Behavior:

• Optimizes bundle size and performance
• Generates production-ready assets
• Handles code splitting and tree shaking
• Processes CSS and other static assets
• Generates manifest files and service workers if configured
• Applies all production-oriented plugin configurations

test Command

Runs the test suite using Jest with project-specific configuration.

# Run tests with Jest
icejs test [options]

# Options:
#   --config <config>     Use custom config file
#   --help               Display help for command
#   [jest-options]       Any Jest CLI options are supported

Usage Examples:

# Run all tests
icejs test

# Run tests in watch mode
icejs test --watch

# Run tests with coverage
icejs test --coverage

# Run specific test files
icejs test --testPathPattern=components

# Run tests with custom config
icejs test --config build.test.json

# Combine custom config with Jest options
icejs test --config build.test.json --verbose --detectOpenHandles

Behavior:

• Integrates with project's Jest configuration
• Supports all standard Jest CLI options
• Handles TypeScript compilation for tests
• Provides appropriate environment setup for React components
• Respects project's test patterns and ignore rules

Configuration

Config File Support

All commands support the --config option to specify custom configuration files:

# Supported config file formats
icejs start --config build.json
icejs build --config build.js
icejs test --config .buildrc.js

Environment Variables

Commands respect standard Node.js and framework environment variables:

# Set environment for build optimizations
NODE_ENV=production icejs build

# Enable debugging
DEBUG=ice:* icejs start

# Custom framework name
__FRAMEWORK_NAME__=my-framework icejs start

Error Handling

CLI commands include comprehensive error handling:

• Node Version Checking: Validates Node.js version against package requirements
• Port Conflicts: Automatically finds available ports for development server
• Configuration Errors: Clear error messages for invalid configuration
• Build Failures: Detailed error reporting for build and compilation issues
• Plugin Errors: Isolated error handling for plugin failures

Process Management

Child Process Architecture

Development server runs in child process for better isolation:

# Main process manages child process lifecycle
icejs start
# ↳ Spawns child process for development server
# ↳ Handles cleanup on exit signals
# ↳ Forwards output and error streams

Signal Handling

Proper cleanup and shutdown handling:

• SIGINT (Ctrl+C): Graceful shutdown of development server
• SIGTERM: Clean process termination
• Process Exit: Automatic cleanup of child processes