Riverpod 3 without code generation

Riverpod is the only tool for dependency injection, state management and async orchestration. Providers are declared explicitly by hand.

Rules and why

Pick the provider by role

One responsibility per provider. Name them xProvider / XNotifier.

final todayProvider = FutureProvider<Today>((ref) async {
  final result = await ref.watch(todayRepositoryProvider).getToday();
  return result.getOrThrow(); // the sanctioned throw: becomes AsyncError
});

watch, read, listen

State classes

• State is immutable and extends Equatable. Riverpod only notifies when the new state is not == to the old one, and select compares by value, so value equality is what makes both work as intended.
• Mutate with state = AsyncData(current.copyWith(...)); never mutate a list in place (the reference does not change, so nothing fires).
• On a failed reload or load-more, keep the previous state and drop only the spinner. Blanking what the user is reading is worse than a stale list.
• Mutating methods return AsyncResult so the caller can report the failure; the store itself changes only on success, so a failed attempt never wipes app-wide state. Template: assets/async_store_notifier.dart.

Lifecycle

• autoDispose for screen-scoped state and for per-attempt submissions, so a stale error resets when the screen is left.
• Never autoDispose a long-lived singleton that is read from callbacks (a text-to-speech engine, a socket): it can be torn down mid-use and crash on the next event. Release native resources with ref.onDispose.
• ref.onDispose for every timer, debouncer and stream subscription a provider creates.
• if (!ref.mounted) return; after every await in a notifier that can be disposed while a request is in flight; assigning state afterwards throws. Still hand the result back to the caller.
• ref.invalidate(provider) is the retry button: wire onRetry to it.

Automatic retry (Riverpod 3)

A provider that throws during build is retried automatically with exponential backoff. With Result-based errors that is usually wrong: an AuthFailure or ValidationFailure fails identically every time, and calling a store or payment SDK ten more times is harmful.

• Install one policy at the composition root that retries only NetworkFailure and 5xx, a couple of times: assets/retry_policy.dart.
• Opt out per provider with retry: (_, _) => null when the work is not safe to repeat.
• Tests switch retry off (see flutter-testing).

Verify the retry parameter against your Riverpod version.

Composition root

• A required config provider throws until overridden, so a missing override fails at startup rather than mid-session.
• An optional capability defaults to a disabled/no-op config so tests never initialise a platform SDK.
• Build the ProviderContainer yourself and use UncontrolledProviderScope when something must read providers before the first frame, or when a widget above the router needs the router instance. See assets/bootstrap_example.dart.
• A widget placed above the router cannot use context.router; read the router from a provider instead.

Rebuild performance

Measure first. These techniques add complexity; use them when a rebuild is observably expensive (a long list, a chart, dropped frames), not on suspicion.

1. Push the watch down. A small ConsumerWidget around the subtree that needs the state beats a select at the page root. Listener widgets exist for the same reason: they listen without watching.
2. Keep transient state out of app-wide providers. A submission in flight belongs in its own autoDispose provider, not in the session, or every screen watching the session rebuilds on every tap.
3. select the narrowest thing.

   final name = ref.watch(authProvider.select((s) => s.value?.user?.name ?? ''));
   final submitting = ref.watch(submissionProvider.select((s) => s.isLoading));

   Use selectAsync to derive from another provider's data without awaiting the whole AsyncValue.
4. const the leaves.

select rules: the selected value must be immutable and compared by value; do not select a property that changes as often as its parent.

Anti-patterns

• ref.read inside build for reactive data
• A provider that holds business rules which belong in the domain
• Reading failure.message for UI copy (see flutter-result-errors)
• Catching an error inside a provider to swallow it: fold the Result instead
• A single giant provider that every screen watches
• Creating a ProviderContainer inside a widget

Review checklist

• No generator, annotation, StateNotifier, Bloc, GetIt, provider package
• Each provider has one job and the right type for it
• watch in builds, read in callbacks, listen for side effects
• State classes are immutable and Equatable
• autoDispose where scoped; never on long-lived singletons
• ref.mounted checked after awaits; ref.onDispose for timers and subscriptions
• A retry policy is installed; unsafe providers opt out
• Required config providers throw until overridden