Riverpod State Management

Priority: P0 (CRITICAL)

Type-safe, compile-time safe reactive state management using riverpod and riverpod_generator.

Structure

lib/
├── providers/ # Global providers and services
└── features/user/
    ├── providers/ # Feature-specific providers
    └── models/    # @freezed domain models

Provider Definition (Generator-First)

Use @riverpod annotations for all provider definitions. See implementation examples for full provider and consumer patterns.

Consuming Providers

Use ConsumerWidget with ref.watch() and AsyncValue.when() for reactive UI. See implementation examples.

Implementation Guidelines

• Generator First: Use @riverpod annotations. Avoid manual Provider definitions.
• Immutability: Use Freezed for all state models.
• ref.watch(): Inside build() to rebuild on changes.
• ref.listen(): Inside build() for side-effects (navigation, dialogs). Never in provider init.
• ref.read(): ONLY in callbacks (onPressed).
• Testing: Override providers with ProviderScope(overrides: [provider.overrideWithValue(Mock())]).
• Linting: Enable riverpod_lint and custom_lint for cycle detection.

Anti-Patterns

• No side-effects in provider init: Use ref.listen() in widgets instead.
• No BuildContext in Notifiers: Never pass BuildContext into a Notifier/Provider.
• No local provider instantiation: Keep providers global; avoid dynamic creation.

Related Topics

• flutter-layer-based-clean-architecture
• flutter-dependency-injection
• flutter-testing