Master Flutter State Management with Riverpod

This skill guides Flutter state management architecture using Riverpod. It covers the core provider types - StateProvider for simple values, Provider for computed/derived state, FutureProvider for async data, and StateNotifierProvider paired with a StateNotifier subclass for mutable, immutable-state-driven logic (typically backed by a Freezed state class with copyWith). It shows AsyncValue handling both in the UI (.when(data:, loading:, error:) inside a ConsumerWidget) and composed manually across providers, plus FutureProvider.family and .autoDispose.family for parameterized, memory-efficient providers (including manual ref.keepAlive() with a timed release).

It also covers advanced composition patterns: combining multiple async providers into one aggregate (ref.watch(x.future) chains for a dashboard-style provider), custom Provider.autoDispose with ref.onDispose() cleanup, and providers that depend on other providers (e.g. an authenticated API client built from a watched auth token). Testing guidance shows ProviderContainer with overrides to substitute mock repositories and asserting on notifier state after actions.

final todoProvider = StateNotifierProvider<TodoNotifier, TodoState>((ref) {
  final repository = ref.watch(todoRepositoryProvider);
  return TodoNotifier(repository);
});

Use this skill when building or refactoring Flutter apps that need structured, testable state management - especially apps with async data (API calls, streams), parameterized data fetching (per-ID lookups via family providers), or state shared across multiple widgets/screens. It is well suited to teams that want dependency injection and easy test overrides rather than ad-hoc setState calls.

It is not the right fit for trivial, purely local widget state (a single toggle or animation value scoped to one widget) - Riverpod's provider machinery, families, and autoDispose semantics add overhead that plain StatefulWidget/setState handles more simply for those cases.

Input: a description of the data/state the app needs to manage (user session, todo list, search results, dashboard aggregation) and its async/sync nature and lifecycle needs (cache-and-keep-alive vs auto-dispose). Output: provider declarations of the appropriate type (Provider, FutureProvider, StateNotifierProvider, family variants), an immutable state class (typically Freezed-based with copyWith), a StateNotifier implementing the state transitions, and UI code consuming the provider via ConsumerWidget/ref.watch with AsyncValue.when for loading/error/data branches.

Built on the Riverpod package's provider APIs (StateProvider, Provider, FutureProvider, StateNotifierProvider, .family, .autoDispose) and commonly paired with Freezed for immutable state classes with generated copyWith. Testing integrates with ProviderContainer overrides and mocking libraries (shown with a MockTodoRepository) run through standard Dart test/group blocks.

Flutter developers architecting or scaling an app's state layer - particularly those moving off ad-hoc state handling toward a provider hierarchy with clear data dependencies, async error handling, and mockable repositories for unit testing.