Flutter State Management

Choose, implement, and maintain state management in Flutter apps. Covers the full decision framework: picking the right approach, setting it up correctly, and avoiding common anti-patterns.

First question always: "Is this state local to one widget, or shared across the app?" That single question eliminates most wrong choices.

Decision Framework

Riverpod vs Bloc:

• Riverpod → code generation, compile-time safety, built-in DI
• Bloc → explicit event log, strong team expertise required

Riverpod Setup

# pubspec.yaml
dependencies:
  flutter_riverpod: ^2.5.0
  riverpod_annotation: ^2.3.0
dev_dependencies:
  riverpod_generator: ^2.4.0
  build_runner: ^2.4.0

Always use @riverpod annotation with riverpod_generator. Hand-writing providers loses compile-time safety.

Wrap the app root with ProviderScope:

void main() => runApp(const ProviderScope(child: MyApp()));

Run code generation:

dart run build_runner watch --delete-conflicting-outputs

Riverpod Provider Types

See @references/state-management-snippets.md for full Riverpod code examples (AsyncNotifier, NotifierProvider, StreamProvider, family, testing).

ref.watch vs ref.read

Lifecycle

• autoDispose (default with code gen) — provider destroyed when no listeners remain. Use for screen-scoped data.
• keepAlive — opt-in to prevent disposal. Use for app-wide singletons.
• Force refresh: ref.invalidate(myProvider)
• Use ref.select((state) => state.field) to rebuild only when a specific field changes (avoids broad rebuilds).

Bloc / Cubit

# pubspec.yaml
dependencies:
  flutter_bloc: ^8.1.0
  freezed_annotation: ^2.4.0
dev_dependencies:
  bloc_test: ^9.1.0
  freezed: ^2.4.0

See @references/state-management-snippets.md for Cubit, Bloc, sealed state (freezed), BlocConsumer, and bloc_test examples.

Anti-Patterns

• setState for business logic — use it only for widget-local UI state (animation phase, focus). Never for data from a repository.
• Mixing two state managers in one feature — pick one per feature; mixing creates unpredictable rebuild chains.
• Not handling loading and error states — every async provider must handle all three states: loading, error, data.
• ref.read inside build — read does not subscribe; the widget will not rebuild. Use ref.watch in build.
• Holding BuildContext in providers — providers outlive widgets; capturing context causes memory leaks.
• Global state for widget-local concerns — promote state to the minimal scope that all consumers share.
• Watching too broadly — ref.watch(provider) on a large object rebuilds on any field change. Use select.

Output Artifacts

No dedicated docs artifact — state management decisions are recorded in:

• docs/architecture/architecture_decisions.md (ADR for chosen approach)
• docs/architecture/technical_plan.md (tech stack section)

Cross-references

• Decision context: flutter-architecture skill
• Code examples: @references/state-management-snippets.md
• Agent: state-management-specialist
• Error mapping from providers: @references/dart-error-mapping.md