react-native-update-cli/example/README.md

Custom Modules and Workflows Examples

中文文档 | Chinese Documentation

This directory contains complete examples of React Native Update CLI custom modules and workflows, demonstrating how to extend the CLI functionality.

📁 Directory Structure

example/
├── modules/                    # Custom module examples
│   ├── custom-deploy-module.ts # Custom deployment module
│   └── analytics-module.ts     # Analytics module
├── workflows/                  # Custom workflow examples
│   └── custom-workflows.ts     # Complex workflow collection
├── scripts/                    # Execution script examples
│   ├── register-modules.ts     # Module registration and execution
│   ├── provider-api-example.ts # Provider API usage examples
│   └── workflow-demo.ts        # Workflow demonstration script
└── README.md                   # This documentation

🚀 Quick Start

1. Run Module Registration and Execution Examples

# Compile TypeScript (if needed)
npm run build

# Run module examples
npx ts-node example/scripts/register-modules.ts

2. Run Provider API Examples

npx ts-node example/scripts/provider-api-example.ts

3. Run Workflow Demonstrations

# Run all workflow demonstrations
npx ts-node example/scripts/workflow-demo.ts

# Interactive execution of specific workflows
npx ts-node example/scripts/workflow-demo.ts interactive canary-deployment --version 1.0.0 --initialRollout 5

# Multi-environment deployment workflow
npx ts-node example/scripts/workflow-demo.ts interactive multi-env-deploy --version 1.0.0

# Rollback workflow
npx ts-node example/scripts/workflow-demo.ts interactive rollback-workflow --targetVersion 0.9.5

📦 Custom Module Examples

1. Custom Deployment Module (custom-deploy-module.ts)

This module demonstrates how to create a complete deployment management module, including:

Commands:

• deploy-dev: Deploy to development environment
• deploy-prod: Deploy to production environment
• rollback: Rollback to specified version

Workflows:

• full-deploy: Complete deployment process (development → testing → production)
• hotfix-deploy: Quick hotfix deployment process

Usage Example:

import { moduleManager } from 'react-native-update-cli';
import { customDeployModule } from './modules/custom-deploy-module';

// Register module
moduleManager.registerModule(customDeployModule);

// Execute development deployment
await moduleManager.executeCommand('deploy-dev', {
  args: [],
  options: { platform: 'ios', force: true }
});

// Execute complete deployment workflow
await moduleManager.executeWorkflow('full-deploy', {
  args: [],
  options: { version: '1.2.3' }
});

2. Analytics Module (analytics-module.ts)

Demonstrates how to create analytics and statistics functionality:

Commands:

• track-deployment: Record deployment statistics
• deployment-report: Generate deployment reports

Workflows:

• deploy-with-analytics: Deployment process with analytics

🔄 Custom Workflow Examples

1. Canary Deployment Workflow (canary-deployment)

Implements a complete canary deployment process:

• ✅ Prepare canary deployment environment
• ✅ Initial small-scale deployment
• ✅ Monitor key metrics
• ✅ Automatically expand deployment based on metrics
• ✅ Final validation

await moduleManager.executeWorkflow('canary-deployment', {
  args: [],
  options: {
    version: '2.1.0',
    initialRollout: 10,    // 初始10%用户
    autoExpand: true       // 自动扩大范围
  }
});

2. Multi-Environment Deployment Workflow (multi-env-deploy)

Implements a standard multi-environment deployment process:

• ✅ Deploy to development environment
• ✅ Run integration tests
• ✅ Deploy to staging environment
• ✅ Run end-to-end tests
• ✅ Deploy to production environment
• ✅ Post-deployment validation

await moduleManager.executeWorkflow('multi-env-deploy', {
  args: [],
  options: {
    version: '2.1.0',
    skipProduction: false,     // 不跳过生产部署
    forceProduction: false     // 测试失败时不强制部署
  }
});

3. Rollback Workflow (rollback-workflow)

Safe application rollback process:

• ✅ Validate target version
• ✅ Backup current state
• ✅ Execute rollback operation
• ✅ Verify rollback results
• ✅ Notify relevant personnel

await moduleManager.executeWorkflow('rollback-workflow', {
  args: [],
  options: {
    targetVersion: '2.0.5',
    skipVerification: false
  }
});

🛠️ Provider API Usage Examples

Provider API provides programmatic interfaces suitable for integration in applications:

Basic Usage

import { moduleManager } from 'react-native-update-cli';

const provider = moduleManager.getProvider();

// Bundle application
const bundleResult = await provider.bundle({
  platform: 'ios',
  dev: false,
  sourcemap: true
});

// Publish version
const publishResult = await provider.publish({
  name: 'v1.0.0',
  description: 'Bug fixes',
  rollout: 100
});

// Upload file
const uploadResult = await provider.upload({
  filePath: 'app.ipa',
  platform: 'ios'
});

Application Management

// Create application
await provider.createApp('MyApp', 'ios');

// Get current application
const { appId, platform } = await provider.getSelectedApp('ios');

// List versions
const versions = await provider.listVersions(appId);

// Update version
await provider.updateVersion(appId, versionId, {
  name: 'v1.1.0',
  description: 'New features'
});

Automation Service Class

class DeploymentService {
  private provider = moduleManager.getProvider();
  
  async buildAndPublish(platform: Platform, version: string) {
    // 1. Bundle
    const bundleResult = await this.provider.bundle({
      platform, dev: false, sourcemap: true
    });
    
    // 2. Publish
    const publishResult = await this.provider.publish({
      name: version, rollout: 100
    });
    
    return { bundleResult, publishResult };
  }
}

🎯 Advanced Features

1. Workflow Validation

const workflow: CustomWorkflow = {
  name: 'my-workflow',
  steps: [...],
  validate: (context) => {
    if (!context.options.version) {
      console.error('Version number must be specified');
      return false;
    }
    return true;
  }
};

2. Conditional Execution

const step: WorkflowStep = {
  name: 'conditional-step',
  execute: async (context) => { /* ... */ },
  condition: (context) => {
    return context.options.environment === 'production';
  }
};

3. Error Handling

try {
  const result = await moduleManager.executeCommand('deploy-prod', {
    args: [],
    options: {} // Missing required parameters
  });
} catch (error) {
  console.error('Execution failed:', error.message);
}

4. Custom Workflow Registration

const provider = moduleManager.getProvider();

provider.registerWorkflow({
  name: 'custom-workflow',
  description: 'Custom workflow',
  steps: [
    {
      name: 'step1',
      execute: async (context, previousResult) => {
        // Execution logic
        return { step1: 'completed' };
      }
    }
  ]
});

// Execute workflow
await provider.executeWorkflow('custom-workflow', {
  args: [],
  options: {}
});

📝 Best Practices

1. Module Design

• Single Responsibility: Each module focuses on specific functional domains
• Clear Naming: Use descriptive command and option names
• Complete Documentation: Provide descriptions for all commands and options
• Error Handling: Provide clear error messages and recovery suggestions

2. Workflow Design

• Atomic Operations: Each step should be atomic and independently executable
• State Passing: Properly use previousResult to pass state
• Error Recovery: Consider cleanup and recovery mechanisms for failures
• Progress Feedback: Provide clear progress information to users

3. Development Recommendations

• Type Safety: Make full use of the TypeScript type system
• Test Coverage: Write tests for custom modules
• Documentation Maintenance: Keep examples and documentation synchronized
• Version Management: Set appropriate version numbers for modules

🐛 故障排除

常见问题

1. 模块注册失败

   // 确保模块符合 CLIModule 接口
   const module: CLIModule = {
     name: 'my-module',
     version: '1.0.0',
     commands: [...],
     workflows: [...]
   };
   

2. Command Execution Failed

   // Check command name and parameters
   await moduleManager.executeCommand('correct-command-name', {
     args: [],
     options: { requiredParam: 'value' }
   });
   

3. Workflow Validation Failed

   // Ensure all required options are provided
   await moduleManager.executeWorkflow('workflow-name', {
     args: [],
     options: { version: '1.0.0' } // Required parameter
   });
   

📖 Related Documentation

• Main Project README
• Modular Architecture Documentation
• API Reference Documentation
• Contributing Guide

🤝 Contributing

Welcome to submit more examples and improvement suggestions! Please check the main project's contributing guide.