Flutter Upgrade Workflow
Upgrade Flutter SDK and all dependencies to the version specified in $ARGUMENTS (or the latest stable if not specified).
Usage
/flutter-upgrade 3.24
/flutter-upgrade 3.22.3
/flutter-upgrade # upgrades to latest stableGotchas
dart fix --apply(Step 6) runs AFTER quality gates (Step 5). If it changes code, quality gates need re-running — but no re-run step exists in the workflow. Re-run them manually.flutter pub upgrade --major-versionsupgrades all packages at once. If multiple break simultaneously, isolating the cause is very difficult. Consider upgrading high-risk packages individually.
Instructions
- Pre-upgrade checks:
- Run flutter pub outdated to see what will be upgraded - If $ARGUMENTS specifies a version, verify it exists: flutter version or check https://docs.flutter.dev/release/archive - Check for major version upgrades and research breaking changes on https://docs.flutter.dev/release/breaking-changes - Ensure git working tree is clean (git status)
- Upgrade Flutter SDK:
# To latest stable: flutter upgrade # To a specific version: flutter downgrade $ARGUMENTS # if pinning to older # or switch channel and upgrade as needed - Upgrade dependencies:
flutter pub upgrade --major-versions - Regenerate code (if using code generation):
make generate # or: dart run build_runner build --delete-conflicting-outputs - Run quality gates:
flutter analyze dart run custom_lint # if using Riverpod/custom linters make test # or: flutter test - Apply automated fixes (if analyzer suggests migrations):
dart fix --apply - Manual testing:
- Run on iOS simulator and Android emulator (or physical devices) - Test navigation flows (push, pop, deep links) - Test platform-specific features (camera, permissions, notifications) - Test areas affected by major version upgrades (check changelogs) - Verify release/profile builds, not just debug
- Document changes:
- List all packages that changed versions and why - Note any code modifications required by breaking changes - Record any deprecation warnings that remain (with plan to address)
Examples
Routine upgrade:
/flutter-upgrade
Runs flutter upgrade to latest stable, flutter pub upgrade --major-versions, regenerates code, runs analyze + tests. Reports any breaking changes found.
Targeted version upgrade:
/flutter-upgrade 3.24
Upgrades to Flutter 3.24 specifically. Checks the release notes at https://docs.flutter.dev/release/release-notes for 3.24, identifies breaking changes, upgrades SDK and dependencies, runs full quality gates.
Troubleshooting
| Problem | Solution |
|---|---|
flutter pub upgrade version conflicts | Run flutter pub outdated to identify the conflict. Try upgrading the blocking package first, or add a dependency override temporarily. |
build_runner fails after upgrade | Delete .dart_tool/ and build/ directories, then re-run. Check that build_runner version is compatible with new SDK. |
flutter analyze shows new deprecations | Run dart fix --apply for auto-fixable issues. For manual fixes, check the deprecation message for the replacement API. |
| iOS build fails after SDK upgrade | Run cd ios && pod repo update && pod install. If still failing, delete Podfile.lock and Pods/, then retry. |
| Android build fails with Gradle errors | Check android/gradle/wrapper/gradle-wrapper.properties matches the required Gradle version for the new Flutter SDK. Run cd android &&./gradlew clean. |
| Platform channel errors at runtime | Rebuild from clean: flutter clean && flutter pub get. Platform channel APIs may have changed — check the plugin's changelog. |
Guidelines
- For major version upgrades, always check package changelogs for breaking changes
- Search for migration guides:
[package-name] [old-version] to [new-version] migration - Upgrade incrementally when jumping multiple major versions
- Test thoroughly on both platforms before considering upgrade complete
- Clear caches after upgrade:
flutter clean && flutter pub get