Flutter

Flutter Skill

When to use

• Creating or modifying Flutter screens, widgets, or navigation flows
• Choosing a state management approach (Riverpod, Bloc, Provider, GetX)
• Integrating platform channels for native iOS/Android APIs
• Configuring pubspec.yaml, flavors, or build variants
• Diagnosing jank, excessive rebuilds, or memory leaks
• Setting up CI builds for iOS, Android, web, or desktop targets

Workflow

1. Confirm Flutter channel and target platforms — check flutter --version and which platforms are enabled in pubspec.yaml. Use stable channel for production; beta only if a specific fix is needed.
2. Plan widget tree before coding:
   • Identify which parts of the UI are stateless (pure display) vs. stateful (user interaction, async data)
   • Keep StatelessWidget the default; only use StatefulWidget when local ephemeral state is genuinely needed
   • Prefer const constructors everywhere possible — they short-circuit the rebuild cycle
3. Choose state management (confirm with team; do not switch mid-project):
   • Riverpod (recommended default): AsyncNotifierProvider for async data, NotifierProvider for sync state; co-locate provider declarations near the feature
   • Bloc: Cubit for simple state, Bloc for event-driven flows; one Bloc per feature/screen
   • Provider: acceptable for smaller apps; avoid nested ChangeNotifierProvider chains
4. Navigation: use go_router for declarative, deep-link-aware routing. Define all routes in a single router.dart; avoid Navigator.of(context).push calls scattered through the widget tree.
5. Data layer:
   • HTTP: dio or http package; wrap in a typed repository class
   • Local storage: drift (SQL) for structured data, hive / isar for simple key-value/object stores
   • Never call network or DB code inside build()
6. Async in widgets: use FutureBuilder / StreamBuilder only for one-off display; for anything the user can refresh or that changes over time, use a state management provider that holds the async state.
7. Platform channels: define the method channel in a dedicated service class; keep channel names namespaced (com.example.app/channelName); implement both iOS (Swift) and Android (Kotlin) sides before writing the Dart wrapper.
8. Performance pass before each release:
   • Run flutter run --profile on a real device; open DevTools → Performance
   • Identify widgets rebuilding unnecessarily with the Widget Rebuild tracker
   • Use RepaintBoundary around independently animated sections
   • Ensure all Image widgets use cacheWidth/cacheHeight or ResizeImage
9. Build and sign:
   • iOS: manage certificates and provisioning in Xcode or Fastlane; never commit .p12 or ExportOptions.plist with embedded secrets
   • Android: store keystore outside the repo; reference via key.properties (git-ignored)
   • Use flavors (--flavor) for dev/staging/prod; map to separate Firebase projects if applicable

Standards

Common mistakes to avoid

• setState on a disposed widget — always check mounted before calling setState after an await.
• Rebuilding expensive widgets on every parent rebuild — lift the expensive widget out, wrap in const, or use Selector/Consumer scoped to the exact state slice it needs.
• BuildContext across async gaps — after any await, the context may be invalid. Store what you need before the await, or check mounted.
• pubspec.yaml asset paths with trailing slash not listing all files — Flutter does not glob recursively; each subfolder must be listed, or files will be missing in release builds.
• Platform channel calls on the main isolate for heavy work — offload to a background Isolate or use compute(); blocking the main isolate causes dropped frames.
• Not handling deep links in go_router on both platforms — iOS requires CFBundleURLTypes in Info.plist; Android requires intent filters in AndroidManifest.xml. Test both.
• Forgetting flutter pub run build_runner build after model changes — generated files (*.g.dart, *.freezed.dart) go stale silently.

Output format

Typical feature deliverable structure:

lib/
  features/
    <feature>/
      data/
        <feature>_repository.dart   # Network/DB calls; returns typed models
        <feature>_model.dart        # Freezed or plain Dart model + fromJson/toJson
      domain/
        <feature>_state.dart        # State class (Freezed union or sealed class)
      presentation/
        <feature>_screen.dart       # Root screen widget; provides BLoC/Riverpod scope
        widgets/
          <feature>_card.dart       # Extracted sub-widgets; prefer const
  core/
    router/
      router.dart                   # All go_router route definitions
    theme/
      app_theme.dart
test/
  features/
    <feature>/
      <feature>_repository_test.dart
      <feature>_screen_test.dart

Related checklists

• .claude/checklists/security.md
• .claude/checklists/performance.md
• .claude/checklists/accessibility.md
• .claude/checklists/production.md

Related agents

• .claude/agents/engineering/mobile-engineer.md
• .claude/agents/design/mobile-ux-specialist.md
• .claude/agents/quality/performance-engineer.md
• .claude/agents/quality/security-auditor.md
• .claude/agents/quality/accessibility-auditor.md