| name | flutter-riverpod-state-management |
| description | Implement reactive state management using Riverpod 3.x with code generation in Flutter. Use when defining providers, building AsyncNotifiers, or overriding providers in tests. |
| metadata | {"triggers":{"files":["**_provider.dart","**_notifier.dart"],"keywords":["riverpod","ProviderScope","ConsumerWidget","Notifier","AsyncValue","ref.watch","@riverpod"]}} |
Riverpod State Management
Priority: P0 (CRITICAL)
Targets Riverpod 3.x. Notifier/AsyncNotifier codegen surface is unchanged from 2.x; Riverpod 3 adds automatic retry with backoff and pause/resume for offline — do not hand-roll retry logic that the framework already provides.
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 Notifier/Provider.
- No local provider instantiation: Keep providers global; avoid dynamic creation.
Related Topics
