🔧 FlutterFix #

Make any Flutter project run instantly.
Automatically fixes Flutter, Gradle, Kotlin, and Java version conflicts with a single command.

🚀 Why FlutterFix? #

Ever cloned a Flutter project and spent hours debugging build errors?

❌ The Android Gradle plugin supports only Kotlin Gradle plugin version 1.5.20 and higher.
❌ Unsupported class file major version 61
❌ java.lang.NoClassDefFoundError: Could not initialize class org.codehaus.groovy

FlutterFix solves this in seconds.

It automatically:

• ✅ Detects incompatible Flutter/Gradle/Kotlin/Java versions
• ✅ Updates configuration files with correct versions
• ✅ Fixes Android SDK mismatches
• ✅ Cleans build caches
• ✅ Makes any project buildable instantly

📦 Installation #

Option 1: Global Installation (Recommended) #

dart pub global activate flutterfix

Option 2: Local Installation #

dart pub global activate --source path .

Verify Installation #

flutterfix --version

🎯 Quick Start #

Basic Usage #

Navigate to your Flutter project and run:

flutterfix

That's it! The tool will:

1. 🔍 Analyze your project
2. 🔧 Fix version conflicts
3. 🧹 Clean build caches
4. ✅ Make your project ready to run

Install Compatible Flutter Version #

Auto-install based on project requirements:

flutterfix install

This will:

1. 🔍 Detect your project's Flutter version requirement
2. 📦 Install FVM (Flutter Version Management) if needed
3. ⬇️ Download and install the compatible Flutter version
4. 🔧 Configure your project to use the installed version

List all available Flutter versions:

flutterfix install --list

Install a specific Flutter version:

flutterfix install --version 3.24

Show version compatibility information:

flutterfix install --version 3.24 --info

Common Use Cases #

Fix a specific project:

flutterfix sync --path /path/to/flutter/project

Install compatible Flutter version:

flutterfix install

List available Flutter versions:

flutterfix install --list

Install specific Flutter version:

flutterfix install --version 3.24

Diagnose without fixing:

flutterfix doctor

Rollback changes (restore from backup):

flutterfix rollback

List all backups:

flutterfix rollback --list

Restore latest backup:

flutterfix rollback --latest

Upgrade FlutterFix:

flutterfix upgrade

Get help:

flutterfix --help

Rollback & Backup System #

FlutterFix automatically creates backups before modifying any files. You can easily restore previous versions:

Undo last changes (interactive):

flutterfix rollback

List all backups:

flutterfix rollback --list

Restore most recent backup:

flutterfix rollback --latest

Restore specific backup by ID:

flutterfix rollback --id <backup-id>

Clear all backups:

flutterfix rollback --clear

Backups are stored in .flutterfix/backups/ directory within your project. Each backup includes:

• Original file path
• Timestamp
• Description of changes
• Unique backup ID

✨ Features #

🛠️ What It Fixes #

1. Gradle Version Issues #

• Updates Gradle wrapper to compatible version
• Fixes Android Gradle Plugin (AGP) version
• Optimizes Gradle settings for performance

2. Kotlin Version Conflicts #

• Sets correct Kotlin version based on Flutter version
• Ensures Kotlin plugin is properly configured
• Fixes ext.kotlin_version declarations

3. Java Compatibility #

• Updates compile options (source/target compatibility)
• Checks Java version compatibility with Gradle
• Configures kotlinOptions.jvmTarget

4. Android SDK Configuration #

• Updates minSdkVersion to modern standards (21+)
• Sets appropriate compileSdk and targetSdk
• Ensures AndroidX compatibility

5. Build Cache Issues #

• Cleans Flutter build directory
• Removes Android build artifacts
• Clears Gradle cache

6. Flutter Version Management #

• Auto-installs compatible Flutter version
• Uses FVM (Flutter Version Management) for easy switching
• Supports standalone installations
• Lists available Flutter versions

7. Backup & Rollback System #

• Automatic backups before any file modifications
• Restore files to previous state with one command
• List all available backups with timestamps
• Clear old backups to save space
• Backup metadata includes descriptions and timestamps

📋 Example Output #

╔═══════════════════════════════════════════╗
║       🔧 FlutterFix v1.0.0 🔧             ║
║   Auto-fix Flutter Build Errors           ║
╚═══════════════════════════════════════════╝

🔍 Detecting installed versions...
  Flutter: 3.24.0
  Dart: 3.5.0
  Java: 17
  Gradle: 7.5
  Kotlin: 1.7.10

🔎 Analyzing project structure...
  ✓ Valid Flutter project
  Project: my_app
  SDK: >=3.0.0 <4.0.0
  ✓ Android configuration found

🔧 Fixing Gradle configuration...
  ✓ Gradle version updated to 8.3
  ✓ Android Gradle Plugin updated to 8.1.0
  ✓ Gradle settings optimized

🔧 Fixing Kotlin configuration...
  ✓ Kotlin version updated to 1.9.0
  ✓ Kotlin plugin configured

🔧 Fixing Java & SDK configuration...
  ✓ Java 17 is compatible with Gradle 8.3
  ✓ Java compile options fixed
  ✓ Android SDK versions updated

═══════════════════════════════════════════
📊 Summary
═══════════════════════════════════════════
✅ Fixed (7):
   • Gradle configuration
   • Kotlin configuration
   • Java & SDK configuration
   • Build cache cleaned
   • Dependencies fetched

✅ Project fixed successfully!
You can now run: flutter run

🧪 Compatibility Matrix #

🚀 CI/CD Integration #

FlutterFix can be integrated into your CI/CD pipeline to automatically fix version conflicts.

GitHub Actions #

Add FlutterFix to your GitHub Actions workflow:

name: Flutter CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Flutter
        uses: subosito/flutter-action@v2
        with:
          channel: 'stable'
      
      - name: Install FlutterFix
        run: dart pub global activate flutterfix
      
      - name: Fix version conflicts
        run: flutterfix sync
      
      - name: Run tests
        run: flutter test

For more examples, see examples/ci-cd/ directory.

Benefits in CI/CD #

• ✅ Automatic version fixing - No manual intervention needed
• ✅ Consistent builds - Same configuration across all environments
• ✅ Catch issues early - Detect conflicts before merging
• ✅ Zero configuration - Works out of the box
• ✅ Fast execution - Completes in seconds

🤝 Contributing #

Contributions are welcome! Here's how you can help:

1. 🍴 Fork the repository
2. 🔨 Create a feature branch (git checkout -b feature/amazing-feature)
3. 💾 Commit your changes (git commit -m 'Add amazing feature')
4. 📤 Push to the branch (git push origin feature/amazing-feature)
5. 🎉 Open a Pull Request

Development Setup #

# Clone the repo
git clone https://github.com/haraprosad/flutterfix.git
cd flutterfix

# Install dependencies
dart pub get

# Run tests
dart test

# Activate locally
dart pub global activate --source path .

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Built with ❤️ for the Flutter community
• Inspired by countless hours debugging version conflicts
• Thanks to all contributors and users

📞 Support #

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🐦 Twitter: @haraprosad