| name | flutter-dart-dependency-upgrade |
| description | Perform a controlled, maintenance-only upgrade of Flutter and Dart dependencies in a monorepo, including regeneration of code and localizations and reconciliation of iOS/macOS CocoaPods (notably Firebase SDK versions). Intended for manual or scheduled dependency hygiene tasks, not for routine feature development. |
| license | See LICENSE file in repository root |
| compatibility | Requires Flutter (via FVM), CocoaPods, and the Sharezone CLI (sz). Intended for Flutter monorepos with iOS and macOS targets. |
| metadata | {"author":"Sharezone UG (haftungsbeschränkt)","version":"1.0"} |
Goal
Safely upgrade Flutter/Dart dependencies across the repository, regenerate all derived artifacts, and ensure iOS and macOS CocoaPods (especially Firebase SDKs) are aligned.
When to use
This skill is intended for maintenance workflows, not for normal feature development.
Activate this skill only when the user asks for "Upgrade my Flutter dependencies" or similar
Procedure
1. Upgrade Flutter dependencies
Run from the repository root:
fvm flutter pub upgrade
2. Regenerate generated code
sz build_runner build
3. Regenerate localizations
sz l10n generate
4. Install CocoaPods (iOS and macOS)
Run CocoaPods for both platforms:
pod install --project-directory=app/ios
pod install --project-directory=app/macos
Common failure: Firebase SDK version mismatch
Example error
[!] CocoaPods could not find compatible versions for pod "FirebaseAnalytics":
In snapshot (Podfile.lock):
FirebaseAnalytics (= 12.2.0)
In Podfile:
firebase_analytics (...) depends on FirebaseAnalytics (= 12.8.0)
Root cause
The Firebase SDK version pinned in the Podfiles does not match the version required by the FlutterFire plugins.
In app/ios/Podfile and app/macos/Podfile, Firebase frameworks are pinned via Invertase git tags, for example:
pod 'FirebaseFirestore',
:git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
:tag => '12.2.0'
The error output indicates the required SDK version (e.g. 12.8.0).
Fix
- Read the required Firebase SDK version from the error message (e.g.
12.8.0).
- Update both Podfiles (
app/ios/Podfile and app/macos/Podfile) to use that version:
pod 'FirebaseFirestore',
:git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
:tag => '12.8.0'
- Remove existing lockfiles:
rm -f app/ios/Podfile.lock app/macos/Podfile.lock
- Reinstall CocoaPods:
pod install --project-directory=app/ios
pod install --project-directory=app/macos
Success is indicated by:
Pod installation complete!
with no errors.
Final checks
5. Format code
sz format
6. Run static analysis
sz analyze
7. Run tests
sz test
If golden tests (located in **/test_goldens) fail with less than 0.15% difference, update the golden files:
sz test --update-goldens
If non-golden tests fail, investigate and fix the issues.
Both commands must complete without errors.
Checklist
Notes
- If CocoaPods reports a minimum deployment target error, the required Firebase SDK may exceed the current iOS/macOS deployment target. Update the deployment target consistently across Podfiles and Xcode project settings before retrying.
- Always update both iOS and macOS Podfiles to the same Firebase SDK version.
