flutter-state-management git:20260822.e519e06A

Immutable. This exact content is served forever at /api/v1/blob/80a839ee675a083a.

---
name: flutter-state-management
description: Design or review Flutter state ownership, update flow, and package integration. Use for setState, Listenable, Provider, Riverpod, Bloc, Redux, or custom state problems; preserve the project's established approach unless migration is requested.
---

# Flutter State Management

Start with ownership and lifetime, then choose mechanics.

## Inspect

Identify which state is ephemeral UI state, feature state, shared application state, cached server data, or persisted data. Determine who creates, mutates, observes, and disposes it.

## Rules

- Keep state as local as its consumers allow.
- Maintain a single source of truth and derive secondary values instead of synchronizing copies.
- Make state transitions explicit and keep side effects outside widget `build` methods.
- Preserve an established package and its conventions when they are functioning.
- For a new project, choose based on complexity, team familiarity, testability, code generation tolerance, and lifecycle needs—not popularity alone.
- Expose immutable state or read-only views of mutable collections.
- Model loading, empty, success, and failure states deliberately where the UI distinguishes them.
- Avoid broad subscriptions that rebuild unrelated subtrees.

Do not introduce global service locators or package-level singletons as a shortcut for unclear ownership.

## Verification

Test meaningful transitions, failure recovery, disposal, and repeated events. Inspect rebuild scope for hot paths and run widget tests for state-to-UI behavior.

## Boundaries

Architecture-wide dependency direction belongs to `flutter-architecture`; persistence and remote caching belong to their data specialists.

## Sources

- [Flutter state management fundamentals](https://docs.flutter.dev/get-started/fundamentals/state-management)