state-management-riverpod

Use one Notifier, AsyncNotifier, or StreamNotifier per feature exposing a single immutable state value with value equality. Widgets call intent methods like notifier.rename(id, name) and never mutate state directly; every transition assigns a new instance via copyWith.

Use ref.watch or ref.watch with .select inside build() for display, ref.read(p.notifier) inside callbacks like onTap to invoke intent methods, and ref.listen inside build() for one-shot side effects such as navigation or snackbars. Reading a value in build() freezes on stale data.

StateProvider, StateNotifierProvider, and ChangeNotifierProvider are legacy in Riverpod 3.x and moved to package:flutter_riverpod/legacy.dart. The idiom is Notifier with NotifierProvider; the included CI script fails builds that import the legacy library.

Capturing a ref.watch'ed value into an onTap closure freezes the previous entity, so a fast re-tap after rebuild acts on stale data with no lint warning. Pass a stable key like an id and resolve the entity at tap time via ref.read inside the intent method.

No. Riverpod providers serve as the DI container: collaborators are plain Providers with throwing seams overridden once per flavor in main()'s ProviderScope. Mixing get_it, package:provider, or Bloc creates two competing state mechanisms and is banned by the CI gate.

Inject package:clock's Clock through a clockProvider seam instead of calling DateTime.now(). Tests override it with clockProvider.overrideWithValue(Clock.fixed(t)) inside ProviderContainer.test(), making time-dependent behavior deterministic.