CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ice--app

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.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

service.mddocs/

Service Management

Ice.js provides programmatic access to its build and development capabilities through the service management API. This allows for custom tooling, integration with other build systems, and advanced workflow automation.

Capabilities

Create Service

Creates an Ice.js service instance for programmatic build and development operations.

/**
 * Create Ice.js service instance for programmatic build/dev operations
 * @param options - Service creation options
 * @returns Promise resolving to service instance with run method
 */
function createService(options: CreateServiceOptions): Promise<ServiceInstance>;

interface CreateServiceOptions {
  /** Project root directory path */
  rootDir: string;
  /** Command to execute */
  command: 'start' | 'build' | 'test';
  /** Command-line arguments and options */
  commandArgs: CommandArgs;
}

interface ServiceInstance {
  /** Execute the service operation */
  run(): Promise<any>;
}

interface CommandArgs {
  /** Build/start target platform */
  target?: 'web' | 'weex' | 'ali-miniapp' | 'wechat-miniprogram' | 
           'bytedance-microapp' | 'baidu-smartprogram' | 'kuaishou-miniprogram';
  /** Build mode */
  mode?: 'development' | 'production';
  /** Configuration file path */
  config?: string;
  /** Development server host */
  host?: string;
  /** Development server port */
  port?: number;
  /** Enable bundle analyzer */
  analyzer?: boolean;
  /** Enable HTTPS */
  https?: boolean | 'self-signed';
  /** Force cache clear */
  force?: boolean;
  /** Enable speedup mode */
  speedup?: boolean;
  /** Browser opening behavior */
  open?: boolean | string;
  /** Disable browser opening */
  'no-open'?: boolean;
  /** Disable mock service */
  'no-mock'?: boolean;
  /** List available pages */
  list?: boolean;
  /** Custom plugin */
  plugin?: string;
  [key: string]: any; // Support for additional unknown options
}

Usage Examples:

import createService from "@ice/app/service";

// Development server
const devService = await createService({
  rootDir: process.cwd(),
  command: 'start',
  commandArgs: {
    mode: 'development',
    host: 'localhost',
    port: 3000,
    analyzer: false,
    https: false
  }
});

await devService.run();

// Production build
const buildService = await createService({  
  rootDir: '/path/to/project',
  command: 'build',
  commandArgs: {
    mode: 'production',
    target: 'web',
    analyzer: true,
    config: './ice.config.prod.ts'
  }
});

await buildService.run();

Programmatic Development Server

Start a development server programmatically with full configuration control.

/**
 * Start development server programmatically
 */
async function startDevServer(rootDir: string, options?: DevServerOptions): Promise<ServiceInstance>;

interface DevServerOptions {
  host?: string;
  port?: number;
  https?: boolean | 'self-signed';
  open?: boolean | string;
  mock?: boolean;
  target?: string;
  config?: string;
  analyzer?: boolean;
  speedup?: boolean;
  force?: boolean;
}

Usage Examples:

import createService from "@ice/app/service";

// Basic development server
const service = await createService({
  rootDir: __dirname,
  command: 'start',
  commandArgs: {
    host: '0.0.0.0',
    port: 8080,
    https: true,
    open: '/dashboard'
  }
});

try {
  await service.run();
  console.log('Development server started successfully');
} catch (error) {
  console.error('Failed to start development server:', error);
  process.exit(1);
}

Programmatic Build

Execute production builds programmatically with custom configuration.

/**
 * Execute production build programmatically
 */
async function buildProject(rootDir: string, options?: BuildOptions): Promise<ServiceInstance>;

interface BuildOptions {
  target?: string;
  mode?: string;
  analyzer?: boolean;
  config?: string;
  plugin?: string;
}

Usage Examples:

import createService from "@ice/app/service";

// Multi-platform build function
async function buildForPlatform(platform: string) {
  const service = await createService({
    rootDir: process.cwd(),
    command: 'build',
    commandArgs: {
      target: platform,
      mode: 'production',
      analyzer: platform === 'web' // Only analyze web builds
    }
  });

  return service.run();
}

// Build for multiple platforms
const platforms = ['web', 'ali-miniapp', 'wechat-miniprogram'];

for (const platform of platforms) {
  console.log(`Building for ${platform}...`);
  try {
    await buildForPlatform(platform);
    console.log(`✅ ${platform} build completed`);
  } catch (error) {
    console.error(`❌ ${platform} build failed:`, error);
  }
}

Custom Build Pipeline Integration

Integrate Ice.js service into custom build pipelines and automation tools.

/**
 * Custom build pipeline example
 */
interface BuildPipelineOptions {
  rootDir: string;
  platforms: string[];
  config?: string;
  enableAnalysis?: boolean;
  outputBase?: string;
}

Usage Examples:

import createService from "@ice/app/service";
import path from 'path';

class IceBuildPipeline {
  private options: BuildPipelineOptions;
  
  constructor(options: BuildPipelineOptions) {
    this.options = options;
  }

  async buildAll(): Promise<void> {
    const { platforms, rootDir, config, enableAnalysis } = this.options;
    
    for (const platform of platforms) {
      await this.buildPlatform(platform);
    }
  }

  private async buildPlatform(platform: string): Promise<void> {
    const service = await createService({
      rootDir: this.options.rootDir,
      command: 'build',
      commandArgs: {
        target: platform,
        mode: 'production',
        config: this.options.config,
        analyzer: this.options.enableAnalysis && platform === 'web'
      }
    });

    try {
      await service.run();
      console.log(`✅ Successfully built ${platform}`);
    } catch (error) {
      console.error(`❌ Failed to build ${platform}:`, error);
      throw error;
    }
  }
}

// Usage
const pipeline = new IceBuildPipeline({
  rootDir: '/path/to/project',
  platforms: ['web', 'ali-miniapp'],
  config: './ice.config.prod.ts',
  enableAnalysis: true
});

await pipeline.buildAll();

Development Workflow Automation

Automate development workflows with service management.

/**
 * Development workflow automation
 */
interface WorkflowOptions {
  rootDir: string;
  environments: Array<{
    name: string;
    host: string;
    port: number;
    target?: string;
    config?: string;
  }>;
}

Usage Examples:

import createService from "@ice/app/service";

class DevelopmentWorkflow {
  private options: WorkflowOptions;
  
  constructor(options: WorkflowOptions) {
    this.options = options;
  }

  async startEnvironment(envName: string): Promise<ServiceInstance> {
    const env = this.options.environments.find(e => e.name === envName);
    if (!env) {
      throw new Error(`Environment ${envName} not found`);
    }

    const service = await createService({
      rootDir: this.options.rootDir,
      command: 'start',
      commandArgs: {
        host: env.host,
        port: env.port,
        target: env.target || 'web',
        config: env.config,
        mode: 'development'
      }
    });

    console.log(`Starting ${envName} environment on ${env.host}:${env.port}`);
    return service;
  }

  async startAll(): Promise<ServiceInstance[]> {
    const services = [];
    
    for (const env of this.options.environments) {
      const service = await this.startEnvironment(env.name);
      services.push(service);
      
      // Start services sequentially to avoid port conflicts
      await service.run();
    }
    
    return services;
  }
}

// Usage
const workflow = new DevelopmentWorkflow({
  rootDir: process.cwd(),
  environments: [
    {
      name: 'web',
      host: 'localhost',
      port: 3000,
      target: 'web'
    },
    {
      name: 'miniapp',
      host: 'localhost', 
      port: 3001,
      target: 'ali-miniapp',
      config: './ice.config.miniapp.ts'
    }
  ]
});

// Start specific environment
const webService = await workflow.startEnvironment('web');
await webService.run();

Error Handling

Handle service errors and implement retry logic.

/**
 * Service error handling utilities
 */
interface ServiceError extends Error {
  code?: string;
  phase?: 'initialization' | 'build' | 'serve';
  details?: any;
}

Usage Examples:

import createService from "@ice/app/service";

async function buildWithRetry(options: CreateServiceOptions, maxRetries = 3): Promise<void> {
  let attempt = 1;
  
  while (attempt <= maxRetries) {
    try {
      const service = await createService(options);
      await service.run();
      console.log('Build completed successfully');
      return;
    } catch (error) {
      console.error(`Build attempt ${attempt} failed:`, error.message);
      
      if (attempt === maxRetries) {
        throw new Error(`Build failed after ${maxRetries} attempts: ${error.message}`);
      }
      
      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, 2000 * attempt));
      attempt++;
    }
  }
}

// Usage with error handling
try {
  await buildWithRetry({
    rootDir: process.cwd(),
    command: 'build',
    commandArgs: {
      mode: 'production',
      target: 'web'
    }
  });
} catch (error) {
  console.error('Final build failure:', error);
  process.exit(1);
}

Service Configuration Resolution

Understand how service configurations are resolved and merged.

/**
 * Configuration resolution order:
 * 1. Command line arguments (highest priority)
 * 2. Configuration file options
 * 3. Environment variables
 * 4. Default values (lowest priority)
 */
interface ConfigurationResolution {
  commandArgs: CommandArgs;      // Highest priority  
  configFile: UserConfig;       // From ice.config.*
  environment: NodeJS.ProcessEnv; // Environment variables
  defaults: Record<string, any>;   // Framework defaults
}

This service management API provides full programmatic control over Ice.js operations, enabling integration with custom build tools, CI/CD pipelines, and development workflows while maintaining the same powerful features available through the CLI.

docs

analysis.md

cli.md

configuration.md

index.md

logging.md

service.md

testing.md

types.md

tile.json