magnus919_agent-skills/mobile-development/references/flutter.md

Flutter Reference — Dart, flutter CLI, iOS + Android

Last Updated: 2026-08-03

Load this reference when the project is built with Flutter — a single Dart codebase compiled to native iOS and Android binaries. It complements the shared workflow in SKILL.md and the platform references (ios.md, android.md): Flutter delegates signing, lifecycle, and store mechanics to the underlying platforms, so this file focuses on the Flutter layer — scaffolding, builds, device workflows, and testing.

Flutter fundamentals

• Flutter SDK — install the current stable channel (flutter stable). Pin the Flutter version (via the flutter SDK manager or the repo's .fvmrc/FVM config) so CI and machines build the same binary.
• Project structure — lib/ (Dart source), test/ (tests), pubspec.yaml (dependencies and assets), and platform folders android/, ios/, linux/, macos/, web/, windows/. Cross-platform code lives in lib/; the platform folders are generated and rarely edited directly.
• Dependencies — pubspec.yaml with the pubspec.lock committed for reproducibility; flutter pub get resolves them. Prefer the Flutter ecosystem packages maintained by the Flutter team.
• Rendering — Flutter renders its own UI with Skia/Impeller; fonts, text, and layout behave consistently across platforms, which simplifies cross-device visual testing.

Scaffolding

flutter create --org com.example --project-name my_app --platforms ios,android my_app

• Project name matters — it becomes the Dart package name and the default bundle ID prefix; changing it later is disruptive. --org sets the bundle identifier base (com.example.my_app).
• App entry point — lib/main.dart runs runApp() with the root widget; keep it thin and delegate to feature-level code.
• State management — choose per app size: setState for local state, Provider/Riverpod/Bloc for shared state. Keep state logic testable in Dart without a device.
• Platform tooling — iOS targets still need Xcode, Android targets still need the Android SDK/JDK; flutter doctor verifies the whole toolchain.

Builds and signing

Build commands

# Debug build + hot reload on a connected device
flutter run

# Release APK (Android)
flutter build apk --release

# Release App Bundle (Android, for Play Store)
flutter build appbundle --release

# iOS archive + export (requires macOS + Xcode; produces .ipa via Xcode)
flutter build ipa --release

Signing

Flutter delegates signing to the platform toolchains:

• Android — signing is configured in android/app/build.gradle.kts exactly as for a native app: keystore + signingConfigs, with secrets via environment or a gitignored key.properties. flutter build appbundle produces the AAB that Play signs via Play App Signing.
• iOS — flutter build ipa runs the Xcode archive/export flow under the hood; configure automatic signing (developer team) in the Xcode project or supply an ExportOptions.plist. TestFlight and App Store upload work the same way as native iOS.
• Flutter specific — flutter build embeds the Dart AOT snapshot into the platform binary; --release differs from --debug in tree shaking and compilation, so test the release build.

Devices and emulators

flutter devices          # list connected devices and emulators
flutter emulators        # list available emulators
flutter run -d <device>  # run on a specific device

• Hot reload — flutter run supports hot reload (state preserved) and hot restart (state reset) for fast iteration; hot reload does not run on release builds.
• iOS simulator — boot via Xcode or open -a Simulator; flutter run -d "iPhone 16".
• Android emulator — start an AVD first; flutter run picks it up.
• Physical devices — USB debugging (Android) and trust the computer (iOS); test on real devices for networking, sensors, and performance.
• Debug vs release parity — flutter run (debug) enables hot reload but is slower and includes assertions; verify the release build (flutter run --release) before shipping.

Lifecycle and backgrounding

• App lifecycle — WidgetsBindingObserver + AppLifecycleState (inactive/paused/resumed/detached) tells the widget tree about backgrounding and resumption. Persist state on paused, not on resumed.
• Platform behavior underneath — iOS and Android still enforce their own background rules; Flutter code stops executing when the app is suspended. Use platform channels or plugins (WorkManager, background fetch) for background work, and be aware that plugins wrap the platform APIs covered in ios.md and android.md.
• Process death — the OS can kill the app at any time; persist state to local storage rather than relying on widget state.

Offline and sync

• Local persistence — sqflite/drift (SQLite) for structured data, shared_preferences for small settings, and file/asset storage for larger data. Keep database migrations versioned and tested.
• Sync pattern — persist locally first, queue mutations, and replay them against the API with retry and backoff when connectivity returns. connectivity_plus observes reachability; design for offline to degrade gracefully regardless.
• Conflict resolution — define an explicit strategy (last-write-wins, per-field merge, or conflict UI) so offline edits never silently clobber remote data.

Testing

flutter test                       # unit + widget tests
flutter test integration_test      # integration tests on device/emulator

• Widget tests — fast, headless tests of widget trees (WidgetTester, pumpAndSettle); cover state, navigation, and rendering logic without a device.
• Unit tests — plain Dart tests for models, reducers, and services; dependency-inject network and storage so tests run offline.
• Integration tests — integration_test runs the real app on a device or emulator, driving the UI and asserting end-to-end behavior; run these on the device matrix (locally or on Firebase Test Lab) before release.
• Golden/snapshot tests — matchesGoldenFile renders widgets to images for visual regression; commit golden files with reviewed diffs.

Store submission

Flutter apps ship through the same stores as native apps; the store-facing work is platform mechanics:

• Android — upload build/app/outputs/bundle/release/app-release.aab to Play Console (internal/closed/open testing, data-safety declaration, staged rollout). See android.md for the full checklist.
• iOS — flutter build ipa, upload the .ipa to App Store Connect (TestFlight first), complete privacy labels and listing, submit for review. See ios.md for the full checklist.
• Version parity — keep version/build aligned between pubspec.yaml and the platform configs so a release is identifiable across stores.

Key references

• Flutter documentation (docs.flutter.dev) — current stable channel releases, platform integration guides, and release notes.
• Per-platform references in this skill — ios.md and android.md for signing, lifecycle, and store mechanics.