flutter

Detection Signals

Load this skill when any of the following are found:

Signal	File / Location
Flutter SDK in pubspec	`pubspec.yaml` → `sdk: flutter`
Main entry point	`lib/main.dart`
Flutter workspace	`flutter` key in `pubspec.yaml`
Platform directories	`android/` + `ios/` + `lib/` together

Project Structure

lib/
├── main.dart              # App entry, environment setup, runApp()
├── app/                   # MaterialApp/CupertinoApp, router, theme
├── features/              # Feature-first: each feature owns its own layers
│   └── auth/
│       ├── data/          # Repositories, data sources, DTOs
│       ├── domain/        # Entities, use cases, repository interfaces
│       └── presentation/  # Widgets, pages, state (BLoC/Riverpod/etc.)
├── core/                  # Shared: DI setup, network client, error handling
├── shared/                # Reusable widgets and utilities
└── l10n/                  # Localization ARB files

Feature-first structure is strongly preferred over layer-first for apps with > 3 features
lib/ contains only Dart — never put platform-specific Swift/Kotlin in lib/
Platform code goes in android/, ios/, linux/, macos/, web/, windows/ respectively

State Management

→ Load skills/mobile/flutter/references/state-management.md when choosing or implementing state management (BLoC, Cubit, Riverpod, Provider, GetX).

Dart Best Practices

Null Safety

All new code must be null-safe — never use ! (null assertion) without a preceding null check or a comment explaining why it is guaranteed non-null
Prefer ?? and ?. over null assertions
Use late only for variables that are genuinely initialized before first use (e.g., in initState) — not as a way to defer null handling

Async / Await

Always await Futures — never fire-and-forget unless intentional (document with a comment)
Use Future.wait() for parallel async operations, not sequential await
Wrap top-level async errors: FlutterError.onError + PlatformDispatcher.instance.onError

Isolates (Heavy Computation)

Use compute() or Isolate.run() for operations that block the UI thread > 16 ms:

// Decode large JSON on a background isolate
final parsed = await compute(parseHeavyJson, rawJsonString);

JSON decoding of large payloads, image processing, and cryptography must run on isolates
Do not share mutable state between isolates — pass data by message (serializable types only)

Code Style

Follow Effective Dart naming conventions: lowerCamelCase for variables/functions, UpperCamelCase for types, SCREAMING_SNAKE_CASE for constants
Enable and comply with flutter_lints (or very_good_analysis for stricter projects)
Max line length: 80 characters (enforced by formatter — run dart format . before committing)
Never suppress lints with // ignore: without a comment explaining the reason

Widget Best Practices

→ Load skills/mobile/flutter/references/widgets.md when working with widget composition, rebuilds, performance, or platform-adaptive UI.

Navigation

→ Load skills/mobile/flutter/references/navigation.md when working with routing, deep links, or navigation guards.

Flavors (Multi-Environment)

Flavors allow separate configurations for dev, staging, and production without code changes.

// lib/core/config/app_config.dart
enum Flavor { development, staging, production }

class AppConfig {
  static late Flavor flavor;
  static late String apiBaseUrl;

  static void setup(Flavor f) {
    flavor = f;
    apiBaseUrl = switch (f) {
      Flavor.development => 'https://api.dev.example.com',
      Flavor.staging => 'https://api.staging.example.com',
      Flavor.production => 'https://api.example.com',
    };
  }
}

Run with flavor: flutter run --flavor development -t lib/main_development.dart
Never use if (kDebugMode) as a substitute for flavors — debug/release and dev/prod are orthogonal concerns
CI must build each flavor separately and run tests against each

Platform Channels (Native Code)

Use platform channels only when a Dart/Flutter package does not exist for the required native API.

const _channel = MethodChannel('com.company.app/biometric');

Future<bool> authenticate() async {
  try {
    return await _channel.invokeMethod<bool>('authenticate') ?? false;
  } on PlatformException catch (e) {
    return false;
  }
}

Channel names must be namespaced: com.company.app/feature
Always handle MissingPluginException and PlatformException on the Dart side
Prefer Pigeon for type-safe, generated channel code in production apps

Integration Awareness

Service	Detection	Action
Firebase	`google-services.json` / `GoogleService-Info.plist`	Use `firebase_core`, initialize before `runApp()`
Supabase	`supabase_flutter` dep	Initialize with `Supabase.initialize()` before `runApp()`
Crashlytics	`firebase_crashlytics` dep	Pass `FlutterError.onError` to Crashlytics in `main()`
Push (FCM)	`firebase_messaging` dep	Request permission; handle background messages via top-level function

Testing

Layer	Tool	Scope
Unit	`flutter test` + `mocktail`	Business logic, use cases, repositories
Widget	`flutter_test` + `WidgetTester`	Individual widget rendering and interaction
Golden	`golden_toolkit`	Visual regression — pixel-diff screenshots
Integration	`integration_test` package	Full app flow on simulator / device

Mock dependencies with mocktail — never use real network or file I/O in unit/widget tests
Golden tests: generate goldens on CI; fail on diff; regenerate intentionally with --update-goldens
Integration tests must run on a physical device or a CI device farm (Firebase Test Lab, BrowserStack)
BLoC: test using bloc_test — assert emitted states for each event

App Store & Play Store — Publication Checklist

Both Platforms

version and build_number incremented in pubspec.yaml
Flutter and all dependencies on stable channel and up-to-date (flutter pub outdated)
Release build tested on physical device: flutter run --release
No print() statements in production code (debugPrint() only, or a proper logger)
Privacy policy URL configured in store listing
App icon generated in all sizes (flutter_launcher_icons package)
Splash screen configured (flutter_native_splash package)

iOS (App Store)

CFBundleIdentifier matches App Store Connect entry
CFBundleShortVersionString and CFBundleVersion match pubspec.yaml version/build
All required NSUsageDescription keys set in ios/Runner/Info.plist
Signed with distribution certificate via Xcode or Fastlane
TestFlight build validated before production submission
Bitcode setting matches App Store Connect requirements (disabled for most modern apps)

Android (Play Store)

applicationId matches Play Console entry
versionName and versionCode match pubspec.yaml
Release APK/AAB signed with the upload keystore (never commit keystore to git)
ProGuard/R8 rules verified — check for missing keep rules with a release build
targetSdkVersion ≥ current Google Play requirement
Adaptive icon configured in android/app/src/main/res/
Internal testing track validated before production rollout
Data safety section filled in Play Console