state-management-riverpod

State management (Riverpod)

State and dependency injection are one mechanism: Riverpod 3.x. Each feature has one Notifier/AsyncNotifier/StreamNotifier ViewModel that exposes an immutable state value; dumb ConsumerWidgets read it. Widgets hold only ephemeral UI state; every durable mutation routes through one repository (the single write path). This skill covers the state-agnostic core first, then the Riverpod "how", then a Provider/ChangeNotifier appendix for the official Flutter-guide stack.

Read the reference for the task at hand:

• references/ownership-and-lifecycle.md — the ownership table (which provider shape), family/autoDispose/onDispose rules, composition-root DI.
• references/reads-and-side-effects.md — watch vs read vs listen vs select, the stale-closure hole, void action methods, ref.mounted/BuildContext guards.
• references/riverpod3-api-and-testing.md — Riverpod 3.x API shifts (legacy moves, overrideWithValue, retry, ProviderContainer.test), what 2023 tutorials get wrong, and testing seams.

Run scripts/ban-legacy-providers.sh before a PR.

Non-negotiable rules

These hold regardless of the state library.

1. One ViewModel per feature over one immutable state value. The state is a value type with value equality (freezed/sealed + copyWith), never a mutable field bag. Cross-feature/shared state lives in a repository, not a ViewModel — two ViewModels owning the same fact is two facts that will disagree.
2. State is private; mutate only through intent methods. No widget reaches into the state to poke a field. A view calls notifier.rename(id, name); it never sets state. This is the one door through which state changes, so every change is reviewable in one place.
3. Every transition assigns a new value. Value-equality listeners diff by value — a mutated-in-place instance reassigned to the same reference is missed and the UI silently stales. Always copyWith into a new instance.
4. Derive, don't store. A value computable from existing state (a total, a filtered count, a streak) is a getter or a stream projection, never a second stored field — a stored derivation is a second source of truth that drifts out of sync.
5. Single write path. Every durable mutation is one repository method that persists transactionally and returns only after commit; the UI updates because a stream re-emits, not because you optimistically republished. Persist-before-publish makes crash-safety structural, not a matter of discipline.
6. Unidirectional data flow. Intent → ViewModel → repository/service → new state → view. The view never mutates data it reads and never short-circuits back up the chain. Data flows down; events flow up.
7. Depend on abstractions, injected — never constructed. A ViewModel receives its repositories/services/clock; it never news a live collaborator and never holds a BuildContext. This is what makes it testable with fakes and swappable per flavor.
8. Model async as an explicit state, not loose flags. One AsyncValue (or a status enum + data + error) rendered exhaustively — never scattered isLoading/hasError booleans that can encode a half-set, impossible state.
9. Cascade-clean references on delete. Deleting an entity must drop every reference to it (assignments, foreign keys, selection) — an item left pointing at a deleted parent is a latent crash. Never silently drop the orphan; re-home or unassign it explicitly.
10. No DateTime.now() in state logic. "Now" enters through an injected Clock (from package:clock) exposed as clockProvider, so time-dependent behaviour is deterministic in tests (clockProvider.overrideWithValue(Clock.fixed(t))). Never DateTime.now(), never a bespoke ClockService. service-boundary-and-native owns the clockProvider seam.