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 stable
Gotchas
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-versions upgrades 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
- Determine current Flutter version with
flutter --version
- Determine target version: $ARGUMENTS if provided, else look up latest stable on https://docs.flutter.dev/release/archive
- Enumerate every stable release between current and target (e.g. 3.32 → 3.44 means 3.33, 3.34, … 3.44). For each one, fetch its entry on https://docs.flutter.dev/release/breaking-changes and its release notes / "What's new" post linked from https://docs.flutter.dev/release/release-notes. Collect every breaking change, deprecation, and required migration that touches this project (check Android/iOS/web/desktop sections based on what the app targets). Do this dynamically — don't rely on a hardcoded list, since this skill won't be updated for every release.
- Summarize the collected breaking changes back to the user before proceeding, and note any that require manual code changes vs. those handled by
dart fix --apply or CLI auto-migration.
- 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
1---2name: flutter-upgrade3description: Flutter upgrade workflow. Use when upgrading Flutter SDK, bumping Flutter version, migrating to a new Flutter release, or resolving breaking changes after a Flutter update.4argument-hint: <target version>5metadata:6 source: https://skillmd.com/skills/nielsmadan/flutter-upgrade7---89<!-- Generated from https://github.com/nielsmadan/agentic-coding — edits here are overwritten. -->1011# Flutter Upgrade Workflow1213Upgrade Flutter SDK and all dependencies to the version specified in $ARGUMENTS (or the latest stable if not specified).1415## Usage1617```18/flutter-upgrade 3.2419/flutter-upgrade 3.22.320/flutter-upgrade # upgrades to latest stable21```2223## Gotchas24- `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.25- `flutter pub upgrade --major-versions` upgrades all packages at once. If multiple break simultaneously, isolating the cause is very difficult. Consider upgrading high-risk packages individually.2627## Instructions28291. **Pre-upgrade checks:**30 - Run `flutter pub outdated` to see what will be upgraded31 - Determine current Flutter version with `flutter --version`32 - Determine target version: $ARGUMENTS if provided, else look up latest stable on https://docs.flutter.dev/release/archive33 - Enumerate every stable release between current and target (e.g. 3.32 → 3.44 means 3.33, 3.34, … 3.44). For each one, fetch its entry on https://docs.flutter.dev/release/breaking-changes and its release notes / "What's new" post linked from https://docs.flutter.dev/release/release-notes. Collect every breaking change, deprecation, and required migration that touches this project (check Android/iOS/web/desktop sections based on what the app targets). Do this dynamically — don't rely on a hardcoded list, since this skill won't be updated for every release.34 - Summarize the collected breaking changes back to the user before proceeding, and note any that require manual code changes vs. those handled by `dart fix --apply` or CLI auto-migration.35 - Ensure git working tree is clean (`git status`)36372. **Upgrade Flutter SDK:**38 ```bash39 # To latest stable:40 flutter upgrade4142 # To a specific version:43 flutter downgrade $ARGUMENTS # if pinning to older44 # or switch channel and upgrade as needed45 ```46473. **Upgrade dependencies:**48 ```bash49 flutter pub upgrade --major-versions50 ```51524. **Regenerate code** (if using code generation):53 ```bash54 make generate # or: dart run build_runner build --delete-conflicting-outputs55 ```56575. **Run quality gates:**58 ```bash59 flutter analyze60 dart run custom_lint # if using Riverpod/custom linters61 make test # or: flutter test62 ```63646. **Apply automated fixes** (if analyzer suggests migrations):65 ```bash66 dart fix --apply67 ```68697. **Manual testing:**70 - Run on iOS simulator and Android emulator (or physical devices)71 - Test navigation flows (push, pop, deep links)72 - Test platform-specific features (camera, permissions, notifications)73 - Test areas affected by major version upgrades (check changelogs)74 - Verify release/profile builds, not just debug75768. **Document changes:**77 - List all packages that changed versions and why78 - Note any code modifications required by breaking changes79 - Record any deprecation warnings that remain (with plan to address)8081## Examples8283**Routine upgrade:**84> /flutter-upgrade8586Runs `flutter upgrade` to latest stable, `flutter pub upgrade --major-versions`, regenerates code, runs analyze + tests. Reports any breaking changes found.8788**Targeted version upgrade:**89> /flutter-upgrade 3.249091Upgrades 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.9293## Troubleshooting9495| Problem | Solution |96|---------|----------|97| `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. |98| `build_runner` fails after upgrade | Delete `.dart_tool/` and `build/` directories, then re-run. Check that `build_runner` version is compatible with new SDK. |99| `flutter analyze` shows new deprecations | Run `dart fix --apply` for auto-fixable issues. For manual fixes, check the deprecation message for the replacement API. |100| iOS build fails after SDK upgrade | Run `cd ios && pod repo update && pod install`. If still failing, delete `Podfile.lock` and `Pods/`, then retry. |101| 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`. |102| Platform channel errors at runtime | Rebuild from clean: `flutter clean && flutter pub get`. Platform channel APIs may have changed — check the plugin's changelog. |103104## Guidelines105106- For major version upgrades, always check package changelogs for breaking changes107- Search for migration guides: `[package-name] [old-version] to [new-version] migration`108- Upgrade incrementally when jumping multiple major versions109- Test thoroughly on both platforms before considering upgrade complete110- Clear caches after upgrade: `flutter clean && flutter pub get`