Conservative codemods that migrate Aurelia 1 projects toward Aurelia 2. It edits only the parts that are safe to transform automatically, then writes a comprehensive report for everything else.
🛡️ Conservative approach: Only transforms what's guaranteed safe, reports everything else
📊 Comprehensive reporting: Detailed analysis with migration guidance
🚀 Easy to use: Simple CLI with dry-run mode for safe exploration
- ✅ Removes
@autoinjectdecorators and converts toresolve()patterns - ✅ Removes
@computedFromdecorators (keeps getter methods) - ✅ Strips
PLATFORM.moduleName()calls - ✅ Converts template
.delegateto.trigger - ✅ Updates various template attributes and elements
- 🔍 Detects router patterns needing manual migration
- 🔍 Identifies lifecycle method changes required
- 🔍 Flags
NavigationInstructionusage - 🔍 Analyzes event handlers for
preventDefaultneeds - 🔍 Provides bootstrap migration examples
- 🔍 Suggests
@aurelia/compat-v1when beneficial
- 📄 Generates detailed Markdown and JSON reports
- 📋 Categorizes changes: edits, warnings, notes
- 📈 Shows before/after code diffs
- 📝 Provides specific migration guidance
# Install globally
npm install -g au-rogue
# Or run without installing
npx au-rogue --help# Navigate to your Aurelia 1 project root
cd my-aurelia-app
# Run in dry mode first (recommended)
npx au-rogue --dry
# Review the generated reports:
# - au-rogue.report.md (human-readable)
# - au-rogue.report.json (machine-readable)
# Apply the transformations
npx au-rogue# Show help
npx au-rogue --help
# Dry run (preview changes without modifying files)
npx au-rogue --dry
# Custom file patterns
npx au-rogue --sources "src/**/*.ts" --templates "src/**/*.html"
# Include compatibility suggestions
npx au-rogue --compat
# Custom report output directory
npx au-rogue --report-dir ./migration-reportsThe tool generates two report files:
- au-rogue.report.md - Human-readable migration report
- au-rogue.report.json - Machine-readable data for tooling integration
Running au-rogue on an Aurelia 1 project provides detailed feedback:
📊 Migration Summary
Edits: 23, Adds: 0, Removes: 5, Warnings: 12, Notes: 18
✅ Automatic transformations:
• Removed @autoinject decorators from 8 classes
• Removed @computedFrom decorators from 5 getters
• Removed 12 PLATFORM.moduleName() calls
• Updated .delegate to .trigger in 3 templates
⚠️ Manual review needed:
• Router configuration in App class needs migration
• 4 NavigationInstruction usages detected
• Event handlers may need preventDefault modifiers
💡 Migration guidance provided:
• Bootstrap migration example for main.ts
• Router migration strategies
• @aurelia/compat-v1 compatibility suggestions
- Dependency Injection:
@autoinject→resolve()patterns - Computed Properties: Remove
@computedFromdecorators - Platform Modules: Remove
PLATFORM.moduleName()wrappers - Templates:
.delegate→.trigger, attribute updates - Imports: Clean up unused imports
- Router patterns:
configureRouter(),NavigationInstruction - Complex DI: Interface types, non-runtime types
- Lifecycle methods: v1 hooks needing v2 equivalents
- Event handlers: Cases needing
preventDefault - Bootstrap:
main.tsconfiguration migration
- Complete bootstrap migration examples
- Router migration strategies (
@aurelia/routervs@aurelia/router-lite) - Compatibility package recommendations
- Lifecycle method mapping
- Best practices for manual migrations
- Conservative approach: Only transforms guaranteed-safe patterns
- Comprehensive testing: 107+ test cases covering edge cases
- Idempotent: Running multiple times is safe
- Dry-run mode: Preview all changes before applying
- Detailed reporting: Full transparency of all changes and decisions
See our examples directory for realistic test cases. The tool is designed to be:
- Extensible: Easy to add new transformation passes
- Well-tested: Every transformation has comprehensive test coverage
- Documented: Clear examples and explanations
MIT