flutter_compat

Analyze Flutter project compatibility across environment, dependencies, Android, and iOS — before you add packages or upgrade.

Like flutter doctor and dart pub outdated, with deeper cross-platform checks.

Quick start

dart pub global activate flutter_compat

cd your_flutter_app
flutter_compat doctor
flutter_compat check
flutter_compat fix --dry-run

Point at another project:

flutter_compat doctor -C /path/to/your/app

Install

dart pub global activate flutter_compat

Or run from source:

dart pub get
dart run flutter_compat doctor

Global options

Flag	Meaning
-C, --directory	Project path (default: nearest pubspec.yaml)
-v, --verbose	Include unknown / OK rule findings
--offline	Use cached pub.dev data only (no network)
--timeout	pub.dev HTTP timeout in seconds (default: 20)

Cache location: ~/.flutter_compat/cache/packages/

Commands

doctor

Scan the project and print a human-readable report.

flutter_compat doctor
flutter_compat doctor --packages
flutter_compat doctor -v

Example:

✓ Flutter 3.44.9 (stable)
✓ Dart 3.12.2
✓ Gradle 8.14
✓ AGP 8.8.2
✓ Kotlin 2.1.20
✓ JDK 17
✓ Xcode 16.0
✓ Swift 6.0
✓ CocoaPods 1.16.0

Warnings:
⚠ Flutter support for AGP 8.8.2 will soon be dropped

Errors:
✗ Kotlin incompatible with AGP

check

CI/CD validation with exit codes:

Code	Meaning
0	Success
1	Warnings
2	Errors

flutter_compat check
flutter_compat check --packages --quiet

add

Pre-flight check a package (including transitive semver conflicts), then optionally run flutter pub add.

flutter_compat add firebase_core
flutter_compat add firebase_core --dry-run
flutter_compat add http --version ^1.2.0 --dry-run
flutter_compat add http --dev -y
flutter_compat add provider --dry-run --offline

Flow:

1. Fetch pub.dev metadata (cached under ~/.flutter_compat)
2. Check Flutter / Dart / Android / iOS constraints
3. Walk transitive deps and detect constraint conflicts
4. Show native requirements when known
5. Confirm, then run flutter pub add

remove

Safely remove a package with a pre-check.

flutter_compat remove firebase_core --dry-run
flutter_compat remove firebase_core
flutter_compat remove build_runner --dev -y

update

Check whether upgrades look safe for the current toolchain.

flutter_compat update

scan

Raw scanner / environment dump (useful for debugging).

flutter_compat scan
flutter_compat scan --json

report

Write JSON, Markdown, and HTML reports.

flutter_compat report
flutter_compat report -o build/reports --packages

Outputs:

• compatibility_report.json
• compatibility_report.md
• compatibility_report.html

fix

Apply safe toolchain upgrades when Flutter warns about Android/iOS versions.

flutter_compat fix --dry-run
flutter_compat fix -y

What fix may change

Area	Files
Gradle wrapper	android/gradle/wrapper/gradle-wrapper.properties (official services.gradle.org URL)
AGP	android/settings.gradle, build.gradle, libs.versions.toml
Kotlin	same Android Gradle files
minSdk	android/app/build.gradle(.kts)
Java 17	android/app/build.gradle(.kts) when AGP 8+ needs it
iOS platform	ios/Podfile deployment target

Always preview with --dry-run first.

Real project examples

flutter_compat doctor -C "/path/to/your_flutter_app"
flutter_compat check -C "/path/to/your_flutter_app"
flutter_compat add camera --dry-run -C "/path/to/your_flutter_app"
flutter_compat fix --dry-run -C "/path/to/your_flutter_app"

Troubleshooting

Gradle download fails after fix

If you see FileNotFoundException for a Gradle zip, run flutter_compat fix again.
Wrapper URLs are normalized to:

https://services.gradle.org/distributions/gradle-<version>-all.zip

Offline / network errors

# Use last cached pub.dev responses
flutter_compat add http --dry-run --offline

# Shorter HTTP timeout
flutter_compat doctor --packages --timeout 5

pub.dev download count not updating

pub.dev download stats are delayed and cached — often hours, sometimes a day.

Confidence levels

Symbol	Meaning
✓	Compatible
⚠	Possible conflict
✗	Confirmed issue
?	Unknown

Architecture

CLI (args / cli_util)
  └── AnalysisService
        ├── Scanners (Flutter, Dart, Pubspec, Gradle, AGP, Kotlin, JDK, Android, iOS, Xcode, Swift, Pods, Packages)
        ├── CompatibilityEngine + Android/iOS rule matrices
        ├── TransitiveResolver (add --dry-run)
        └── PubDevRepository (memory + disk cache)
              └── ReportWriter / DoctorPrinter / ToolchainFixer

Compatibility rules

• Flutter ↔ Dart / Packages
• Flutter Android toolchain (Gradle, AGP, Kotlin, minSdk)
• Flutter iOS toolchain (Xcode, Swift, CocoaPods, deployment target)
• AGP ↔ Gradle / Kotlin / JDK
• Package ↔ Native SDK
• Transitive semver conflicts on add --dry-run

Development

dart pub get
dart analyze
dart test
dart run flutter_compat doctor -C test/fixtures/sample_project

License

MIT