Angular Multi-Version Upgrade Orchestrator

An enterprise-grade, intelligent multi-step upgrade orchestrator that safely migrates Angular applications across multiple major versions (12→13→14→...→20) by performing incremental upgrades, validating each step, handling breaking changes systematically, and ensuring zero functionality loss throughout the entire upgrade journey. Features automatic npm installation, comprehensive dependency management, and seamless integration of all 9 official Angular migrations.

🚀 Key Highlights

✅ Production-Ready: Robust architecture designed for enterprise-scale applications
✅ Functionality Preservation: Maintains existing features throughout the upgrade process
✅ Automatic npm Installation: Intelligent dependency management with retry mechanisms
✅ Official Migrations: Integrates all 9 Angular CLI migrations seamlessly
✅ Smart Rollback: Granular checkpoint system with backup restoration
✅ Third-Party Support: Handles Angular Material, NgRx, PrimeNG+
✅ TypeScript AST: Precise code transformations
✅ 99% Automation: Minimal manual intervention required

Features

Core Capabilities

• Multi-Version Orchestration: Seamlessly upgrade through multiple Angular versions in sequence
• Intelligent Path Planning: Automatically determines the optimal upgrade path from current to target version
• Zero Functionality Loss: Prioritizes maintaining existing functionality over modernization
• Automatic npm Installation: Robust dependency management with retry mechanisms and fallback strategies
• Official Angular Migrations: Seamless integration of all 9 Angular CLI migrations from angular.dev/reference/migrations
• Comprehensive Rollback System: Full application snapshots at each major version milestone
• Breaking Change Management: Systematic handling of breaking changes with automated fixes
• Third-Party Library Coordination: Synchronized updates for Angular Material, NgRx, PrimeNG, and more

Dependency Management Excellence

• Multi-Layer Installation Strategy: Primary npm install → Retry with --force → Individual packages → Manual fallback
• Safe package.json Updates: Automatic backup creation before modifications
• Dependency Verification: Ensures packages are actually installed before proceeding
• Timeout Handling: Configurable timeouts with automatic retry mechanisms
• Comprehensive Error Recovery: Graceful degradation when installation issues occur

Official Angular Migrations Integration

• Standalone Components Migration: Automatically converts components to standalone (Angular 14+)
• inject() Function Migration: Converts constructor injection to inject() function (Angular 14+)
• Control Flow Migration: Migrates *ngIf, *ngFor, *ngSwitch to @if, @for, @switch (Angular 17+)
• Signal Inputs Migration: Converts @Input fields to signal inputs (Angular 17+)
• Signal Outputs Migration: Converts @Output events to signal outputs (Angular 17+)
• Signal Queries Migration: Converts ViewChild/ContentChild to signal queries (Angular 17+)
• Route Lazy Loading Migration: Converts eager routes to lazy-loaded routes (Angular 14+)
• Self-closing Tags Migration: Updates templates to use self-closing tags (Angular 16+)
• Cleanup Unused Imports: Removes unused imports for cleaner code (All versions)

Advanced Features

• Intelligent Content Preservation: Advanced AST-based preservation of user customizations using ts-morph
• Detailed Upgrade Reports: Comprehensive HTML, Markdown, and JSON reports with visual analytics
• Checkpoint System: Create restoration points at each upgrade milestone
• AST-Based Code Transformations: Precise code modifications using TypeScript AST
• Multi-Layer Compatibility: Allow old and new patterns to coexist during transitions
• Progressive Enhancement: Opt-in modernization without breaking existing functionality
• Comprehensive Validation: Build, test, and runtime validation at each step

Intelligent Content Preservation System

• User Code Protection: Preserves custom methods, properties, imports, and logic during migrations
• Smart Conflict Resolution: Configurable strategies for handling conflicts between user code and migration requirements
• Template Preservation: Intelligently maintains custom directives and complex template logic
• Comment Retention: Preserves important code comments and documentation
• Detailed Backups: Creates timestamped backups with metadata for easy restoration
• TypeScript AST Analysis: Uses ts-morph for precise code analysis and preservation

Comprehensive Upgrade Reports

• Multiple Formats: HTML (visual), Markdown (documentation), and JSON (programmatic access)
• Visual Analytics: Beautiful charts and metrics with Angular-themed styling
• Detailed Change Tracking: File modifications, dependency updates, and breaking changes
• Executive Summary: High-level overview with success metrics and duration
• Migration Analysis: Complete breakdown of applied migrations and transformations
• Issue Documentation: Comprehensive listing of warnings, errors, and resolutions
• Recommendations: Actionable next steps and best practices for post-upgrade

Quick Start

Installation

npm install -g ng-upgrade-orchestrator

Basic Usage

# Analyze your project
ng-upgrade analyze

# Upgrade to Angular 17
ng-upgrade upgrade --target 17

# Show upgrade plan without executing
ng-upgrade upgrade --target 20 --dry-run

# Conservative upgrade strategy
ng-upgrade upgrade --target 16 --strategy conservative

Interactive Mode

ng-upgrade upgrade

The CLI will guide you through:

1. Target version selection
2. Upgrade strategy configuration
3. Validation level settings
4. Confirmation and execution

Upgrade Strategies

Conservative Mode

• Maximum Safety: Minimal changes per version
• Compatibility First: Preserves all existing patterns
• Manual Opt-in: New features require explicit adoption
• Extensive Validation: Comprehensive testing at each step

Balanced Mode (Default)

• Moderate Modernization: Strategic updates with compatibility layers
• Smart Defaults: Sensible choices for most applications
• Gradual Enhancement: Progressive adoption of new features
• Balanced Validation: Essential checks with optional comprehensive testing

Progressive Mode

• Advanced Features: Enables cutting-edge Angular capabilities
• Modern Patterns: Migrates to latest best practices
• Performance Optimized: Leverages newest optimization features
• Future Ready: Prepares codebase for upcoming versions

CLI Commands

Upgrade Command

ng-upgrade upgrade [options]

Options:
  -t, --target <version>     Target Angular version (12-20)
  -p, --path <path>          Project path (default: current directory)
  -s, --strategy <strategy>  conservative|balanced|progressive (default: balanced)
  --dry-run                  Show upgrade plan without executing
  --no-backup                Skip automatic backup creation
  --validation <level>       basic|comprehensive (default: basic)

Analysis Command

ng-upgrade analyze [options]

Options:
  -p, --path <path>         Project path (default: current directory)

Checkpoint Management

ng-upgrade checkpoints [options]

Options:
  -p, --path <path>         Project path (default: current directory)
  --list                    List all checkpoints
  --rollback <id>           Rollback to specific checkpoint
  --create <description>    Create new checkpoint
  --cleanup                 Clean up old checkpoints

Content Preservation Example

# Upgrade with maximum user code preservation
ng-upgrade upgrade --target 20 --preserve-all

# Upgrade with custom preservation settings
ng-upgrade upgrade --target 18 \
  --preserve-comments \
  --preserve-custom-methods \
  --conflict-resolution user

Report Generation

Detailed upgrade reports are automatically generated after each upgrade:

# Reports are saved to .ng-upgrade/reports/
# - upgrade-report-16-to-17-2024-08-20T10-30-45.html (Visual report)
# - upgrade-report-16-to-17-2024-08-20T10-30-45.md   (Documentation)
# - upgrade-report-16-to-17-2024-08-20T10-30-45.json (Programmatic access)

# View the latest HTML report in your browser
open .ng-upgrade/reports/upgrade-report-*.html

Project Analysis

The analyzer provides comprehensive insights:

ng-upgrade analyze

Sample Output:

Analyzing Angular project

Analysis completed

Project Analysis Results:
Current Angular version: 12.2.0
Project type: Application
Build system: Angular CLI
Dependencies: 45 total, 3 require updates
Lines of code: 15,420
Components: 28
Services: 12
Risk level: Medium

Upgrade Recommendations:
  - Update deprecated dependencies before upgrade
  - Increase test coverage for better validation
  - Consider incremental upgrade strategy

Checkpoint System

Automatic Checkpoints

• Created before each major version upgrade
• Include complete project state and metadata
• Enable instant rollback to any point in upgrade journey

Manual Checkpoint Management

# List all checkpoints
ng-upgrade checkpoints --list

# Create manual checkpoint
ng-upgrade checkpoints --create "Before custom modifications"

# Rollback to specific checkpoint
ng-upgrade checkpoints --rollback checkpoint-id

# Cleanup old checkpoints
ng-upgrade checkpoints --cleanup

Supported Angular Versions

Configuration

Upgrade Options

interface UpgradeOptions {
  targetVersion: string;
  strategy: 'conservative' | 'balanced' | 'progressive';
  checkpointFrequency: 'every-step' | 'major-versions' | 'custom';
  validationLevel: 'basic' | 'comprehensive';
  thirdPartyHandling: 'automatic' | 'manual' | 'prompt';
  rollbackPolicy: 'auto-on-failure' | 'manual' | 'never';
  parallelProcessing: boolean;
  contentPreservation?: PreservationOptions;
}

interface PreservationOptions {
  preserveComments: boolean;        // Keep code comments (default: true)
  preserveCustomMethods: boolean;   // Preserve user-defined methods (default: true)
  preserveUserImports: boolean;     // Keep custom imports (default: true)
  preserveCustomProperties: boolean; // Preserve custom properties (default: true)
  preserveCustomLogic: boolean;     // Keep custom business logic (default: true)
  createDetailedBackup: boolean;    // Create backups with metadata (default: true)
  mergeConflictResolution: 'user' | 'migration'; // Conflict preference (default: 'user')
}

Safety Features

Zero Functionality Loss

• Compatibility-First Approach: Prioritizes maintaining existing functionality
• API Bridging: Creates bridge functions for deprecated APIs
• Gradual Migration: Allows mixed usage of old and new patterns
• Optional Modernization: New features are opt-in rather than forced

Multi-Version Safety Mechanisms

• Per-Version Validation: Comprehensive testing after each Angular version upgrade
• Cross-Version Compatibility: Runtime checks for deprecated APIs across versions
• Progressive Feature Adoption: Teams can adopt new features gradually
• Legacy Preservation: Maintains legacy code patterns until appropriate for modernization

Rollback Capabilities

• Granular Rollback: Rollback to any checkpoint in the upgrade sequence
• Automatic Recovery: Auto-rollback on failure if configured
• State Preservation: Maintains application state during rollbacks
• Dependency Synchronization: Rollback dependencies in sync with application state

Programmatic API

import { UpgradeOrchestrator } from 'ng-upgrade-orchestrator';

const orchestrator = new UpgradeOrchestrator('/path/to/project');

// Set up event listeners
orchestrator.on('progress', (report) => {
  console.log(`Progress: ${report.message}`);
});

orchestrator.on('step-complete', (step) => {
  console.log(`Completed: ${step.fromVersion} → ${step.toVersion}`);
});

// Execute upgrade
const result = await orchestrator.orchestrateUpgrade({
  targetVersion: '17',
  strategy: 'balanced',
  checkpointFrequency: 'major-versions',
  validationLevel: 'comprehensive',
  thirdPartyHandling: 'automatic',
  rollbackPolicy: 'auto-on-failure',
  parallelProcessing: false
});

if (result.success) {
  console.log('Upgrade completed successfully!');
} else {
  console.error('Upgrade failed:', result.error);
}

Breaking Changes Handled

Angular 12 → 13

• View Engine complete removal
• Angular Package Format changes
• Ivy renderer optimizations

Angular 13 → 14

• Standalone components introduction
• Optional injectors in ViewChild/ContentChild
• Angular CLI improvements

Angular 14 → 15

• Standalone APIs stabilization
• Image directive with optimization
• MDC-based Angular Material

Angular 15 → 16

• Required inputs API
• Router data as input
• New control flow syntax introduction

Angular 16 → 17

• New application bootstrap API
• Assets folder migration to public
• Control flow syntax stable
• SSR improvements

Angular 17 → 18

• Material 3 design system
• New lifecycle hooks
• Enhanced build optimizations

Angular 18 → 19

• Zoneless change detection (opt-in)
• Event replay for better UX
• Hybrid rendering capabilities

Angular 19 → 20

• Incremental hydration stable
• Signals ecosystem maturation
• Advanced SSR features

Best Practices

Before Upgrade

1. Create Backup: Always create project backup before starting
2. Update Dependencies: Resolve any known dependency conflicts
3. Run Tests: Ensure all tests pass in current version
4. Clean Build: Verify project builds successfully
5. Commit Changes: Commit all pending changes to version control

During Upgrade

1. Monitor Progress: Watch for any warnings or errors
2. Validate Each Step: Don't skip validation phases
3. Review Changes: Understand what each version brings
4. Test Incrementally: Test application after major milestones

After Upgrade

1. Run Full Test Suite: Comprehensive testing after completion
2. Performance Check: Verify performance hasn't degraded
3. Update Documentation: Update project documentation
4. Team Training: Educate team on new features and patterns

Troubleshooting

Common Issues

npm Installation Issues

# Check npm and Node.js versions
npm --version
node --version

# Clear npm cache
npm cache clean --force

# Remove and reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# If npm install still fails, try:
npm install --legacy-peer-deps
# or
npm install --force

Build Failures

# Check Node.js version compatibility
node --version

# Clear caches
npm run ng cache clean
rm -rf node_modules package-lock.json
npm install

Dependency Conflicts

# Analyze dependency tree
npm ls --depth=0

# Check for peer dependency warnings
npm install --dry-run

# Resolve conflicts with legacy peer deps
npm install --legacy-peer-deps

Angular Migration Issues

# If migrations fail, try running them individually:
npx ng generate @angular/core:standalone-migration --mode=convert-to-standalone
npx ng generate @angular/core:control-flow-migration
npx ng generate @angular/core:signal-inputs

# For TypeScript compilation errors:
npx tsc --noEmit
npm run build

Rollback Issues

# List available checkpoints
ng-upgrade checkpoints --list

# Validate checkpoint integrity
ng-upgrade checkpoints --validate <checkpoint-id>

Getting Help

• Generated API Documentation - Interactive documentation with search
• Documentation - Complete documentation index
• Issues
• Discussions

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/ng-upgrade-orchestrator/ng-upgrade-orchestrator.git
cd ng-upgrade-orchestrator
npm install
npm run build
npm link

License

MIT License - see LICENSE file for details.

Acknowledgments

• Angular Team for the amazing framework
• Community contributors for feedback and improvements
• All the developers who helped test and refine the orchestrator

Built with love for the Angular community