sitory { @override Future<User> fetchUser(String id) async => User(id: id, name: 'Alice');

@override Future<void> updateUser(User user) async => Future.delayed(const Duration(milliseconds: 200)); }

**Repository Provider:**
```dart
final userRepositoryProvider = Provider<UserRepository>((ref) {
  return MockUserRepository();
});

Async State Provider:

class UserState extends AsyncNotifier<User> {
  @override
  Future<User> build() async {
    final repo = ref.watch(userRepositoryProvider);
    return repo.fetchUser('default_id');
  }

  Future<void> refresh(String id) async {
    state = const AsyncLoading();
    try {
      final repo = ref.read(userRepositoryProvider);
      state = AsyncData(await repo.fetchUser(id));
    } catch (e, st) {
      state = AsyncError(e, st);
    }
  }
}

final userProvider = AsyncNotifierProvider<UserState, User>(() => UserState());

Step 3: Wire to UI

Use ConsumerWidget to access the provider graph. Distinguish between ref.watch (triggers rebuilds) and ref.read (one-time access, safe for callbacks).

class DashboardScreen extends ConsumerWidget {
  const DashboardScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final userAsync = ref.watch(userProvider);

    return Scaffold(
      appBar: AppBar(title: const Text('Dashboard')),
      body: userAsync.when(
        data: (user) => Center(child: Text('Hello, ${user.name}')),
        loading: () => const Center(child: CircularProgressIndicator()),
        error: (e, _) => Center(child: Text('Error: $e')),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () {
          // ref.read is used here to avoid rebuild triggers
          ref.read(userProvider.notifier).refresh('new_id');
        },
        child: const Icon(Icons.refresh),
      ),
    );
  }
}

Step 4: Architecture Decisions

1. Separation of Concerns: Providers must never contain UI logic. Business rules, caching, and error mapping belong in the notifier/repository layer. UI handles rendering and user input only.
2. Explicit Scoping: Use autoDispose for ephemeral state (e.g., form fields, temporary filters). Omit it for application-wide state (e.g., auth session, feature flags).
3. Error Boundaries: Wrap async providers in try/catch or use AsyncError propagation. Never swallow exceptions; map them to user-facing states.
4. Testing Strategy: Leverage ProviderContainer and overrideProviderWithValue to isolate unit tests. Verify state transitions without rendering widgets.
5. Performance Optimization: Use ref.listen for side effects (navigation, snackbars) to decouple them from the build phase. Avoid ref.watch inside event handlers.

Pitfall Guide

1. Treating Global State as a Database
   State providers are not persistence layers. Caching belongs in repositories or local storage. Providers should reflect transient application state.

2. Ignoring ref.listen vs ref.watch
   Using ref.watch for side effects triggers rebuilds during the build phase, causing setState errors or navigation crashes. Use ref.listen for effects that must run after rendering.

3. Over-Scoping Without family or autoDispose
   Creating a single provider for list items or dynamic forms causes memory leaks and stale data. Use family for parameterized state and autoDispose for ephemeral UI state.

4. Mixing Side Effects with UI Rendering
   Calling APIs, navigating, or showing dialogs inside build() breaks Flutter's declarative model. Extract side effects into event handlers or ref.listen callbacks.

5. Skipping Provider Disposal & Memory Management
   Long-lived providers holding streams, controllers, or large objects drain memory. Implement @override void dispose() in notifiers to cancel streams and clear caches.

6. Building Monolithic Notifiers
   Combining auth, settings, and cart state into one notifier creates tight coupling and forces unnecessary rebuilds. Split by domain. One provider per bounded context.

7. Neglecting Testability from Day One
   Writing state logic without provider overrides forces integration tests. Design providers to be overridable. Verify state transitions in isolation before wiring to UI.

Production Bundle

Action Checklist

• Audit state boundaries: Separate ephemeral UI state from persistent application state.
• Implement autoDispose for screen-scoped providers to prevent memory leaks.
• Add explicit loading/error states to all async providers; never assume success.
• Configure provider overrides in test suites to verify logic without widget trees.
• Enforce ref.listen for side effects and ref.watch only for rendering dependencies.
• Document the provider graph: Map dependencies, lifecycles, and override points.
• Run flutter analyze with strict linting rules to catch implicit provider misuse.

Decision Matrix

Configuration Template

// lib/providers/app_providers.dart
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../repositories/auth_repository.dart';
import '../repositories/theme_repository.dart';
import '../states/auth_state.dart';
import '../states/theme_state.dart';

// Repository overrides for DI
final authRepositoryProvider = Provider<AuthRepository>((ref) {
  return AuthRepository();
});

final themeRepositoryProvider = Provider<ThemeRepository>((ref) {
  return ThemeRepository();
});

// State providers
final authProvider = AsyncNotifierProvider<AuthState, User?>((ref) {
  return AuthState(ref.watch(authRepositoryProvider));
});

final themeProvider = NotifierProvider<ThemeState, AppTheme>(() {
  return ThemeState(ref.watch(themeRepositoryProvider));
});

// Production container setup
ProviderContainer createTestContainer({
  ProviderContainer? parent,
  List<Override> overrides = const [],
}) {
  return ProviderContainer(
    parent: parent,
    overrides: [
      authRepositoryProvider.overrideWithValue(MockAuthRepository()),
      themeRepositoryProvider.overrideWithValue(MockThemeRepository()),
      ...overrides,
    ],
  );
}

Quick Start Guide

1. Initialize: Run flutter pub add flutter_riverpod and wrap runApp() with ProviderScope.
2. Define Boundaries: Create repository interfaces and provider definitions. Separate data fetching from state mutation.
3. Wire UI: Replace StatefulWidget with ConsumerWidget. Use ref.watch for rendering, ref.read for callbacks, ref.listen for side effects.
4. Test in Isolation: Write unit tests using ProviderContainer and overrideProviderWithValue. Verify state transitions before integrating with widgets.
5. Scale: Apply family for parameterized state, autoDispose for ephemeral UI, and domain-split notifiers for maintainability.

State management is not about picking a library. It is about establishing predictable data flow, explicit dependencies, and testable boundaries. When engineered correctly, it eliminates rebuild chaos, accelerates CI pipelines, and scales cleanly across teams. Treat it as infrastructure, not plumbing.