flutter-state-management

When to Use

• Creating any Riverpod provider or notifier
• Managing async data (API calls, Firebase queries)
• Handling loading/error/data states in UI
• Connecting presentation layer to use cases

Provider Types — Decision Tree

What kind of state do you need?

Computed value from other providers?      → Provider (read-only)
Simple sync state with mutations?         → NotifierProvider
Async data (API, DB) with mutations?      → AsyncNotifierProvider
Async data (read-only, auto-fetch)?       → FutureProvider
Real-time stream (WebSocket, Firestore)?  → StreamProvider

Patterns

1. Read-Only Computed Provider

For derived/computed values. No mutations.

Example: See assets/provider_read_only.dart

2. Notifier — Sync State with Mutations

For local, synchronous state that needs to be mutated.

Example: See assets/notifier_sync.dart

3. AsyncNotifier — Async State with Mutations (MOST COMMON)

For data that comes from an API/DB and can be mutated. Uses AsyncValue.guard() for safe state transitions.

Example: See assets/async_notifier_crud.dart

4. FutureProvider — Read-Only Async Data

For async data you only need to FETCH, not mutate. Supports .family for parameterized queries.

Example: See assets/future_provider.dart

5. StreamProvider — Real-Time Data

For Firestore listeners, WebSocket streams, etc.

Example: See assets/stream_provider.dart

Consuming Providers in UI

Handle AsyncValue (CRITICAL PATTERN)

Every async provider returns AsyncValue<T>. ALWAYS handle all 3 states: loading, error, data. Two approaches: .when() method or Dart 3.0 pattern matching.

Example: See assets/async_value_consumer.dart

Clean Architecture Integration

Page (ConsumerWidget)
  → watches provider
    → provider uses use case
      → use case calls repository interface (domain)
        → repository impl (infrastructure) calls API

Wiring — Dependency Injection

Repository providers and use case providers connect clean architecture layers via Riverpod's Provider.

Example: See assets/di_wiring.dart

autoDispose vs Keep Alive

| Scenario | Use | |----------|-----| | Screen-level data (detail pages) | autoDispose — clean up when leaving | | Global state (auth, user session) | Keep alive (no autoDispose) | | Lists that are expensive to re-fetch | Keep alive or cache manually | | Form state | autoDispose — reset on navigation |

Example: See assets/auto_dispose.dart

Naming Conventions

| Element | Pattern | Example | |---------|---------|---------| | Read-only provider | {thing}Provider | currentUserProvider | | Notifier class | {Thing}Notifier | BookingFilterNotifier | | NotifierProvider | {thing}Provider | bookingFilterProvider | | AsyncNotifier class | {Thing}Notifier | PetListNotifier | | FutureProvider | {thing}Provider | caregiverDetailProvider | | StreamProvider | {thing}Provider | chatMessagesProvider | | Repository provider | {feature}RepositoryProvider | authRepositoryProvider | | Use case provider | {useCase}Provider | loginUseCaseProvider |

Anti-Patterns

| ❌ Don't | ✅ Do | |----------|-------| | ref.read in build() method | Use ref.watch to rebuild on changes | | Business logic inside the widget | Put logic in Notifier or UseCase | | Ignore loading/error states | Always handle all 3 AsyncValue states | | One giant provider file for everything | One provider file per feature | | Call API directly from provider | Provider → UseCase → Repository | | Forget autoDispose on detail pages | Use autoDispose for screen-scoped data |

Resources

• Templates: See assets/ for provider patterns, consumer examples, and DI wiring