flutter-expert

name	flutter-expert
description	Flutter/Dart gotchas and decision criteria. Covers Riverpod vs BLoC, widget optimization, and platform-specific pitfalls.
autoInvoke	false
priority	high
triggers	["flutter","dart","widget","bloc","riverpod"]
paths	["**/*.dart","pubspec.yaml"]
allowed-tools	Read, Grep, Glob, Edit, Write
user-invocable	false

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Flutter Expert — Gotchas & Decisions

Use Context7 for full Flutter/Dart docs.

Key Decisions

decisions[4]{choice,use_when}:
  Riverpod vs BLoC,"Riverpod: simpler apps + compile-safe. BLoC: complex event-driven + team conventions"
  StatelessWidget vs StatefulWidget,"Stateless default. Stateful only for local mutable state (animations/controllers)"
  go_router vs Navigator,"go_router for declarative deep linking. Navigator for simple stack-based"
  Feature-first vs Layer-first,"Feature-first: lib/features/auth/{data|domain|presentation}"

Gotchas

• Always const constructors for immutable widgets — huge rebuild savings
• BuildContext used after async gap → widget may be unmounted. Check mounted first
• ListView.builder not ListView(children:[...]) for long lists — avoids building all items
• sealed class for Result pattern (Success/Failure) — exhaustive switch
• Riverpod: ref.watch in build, ref.read in callbacks. Never ref.watch in callbacks
• BLoC: never emit state after close() — check isClosed in async operations
• Platform channels: always handle MissingPluginException for web/desktop
• TextEditingController and AnimationController MUST be disposed in dispose()
• MediaQuery.of(context) causes rebuilds — use MediaQuery.sizeOf(context) for just size