# Flutter Riverpod State Management

> Implement reactive state management using Riverpod 3.x with code generation in Flutter. Use when defining providers, building AsyncNotifiers, or overriding providers in tests.

- Skill: `hoangnguyen0403/flutter-riverpod-state-management` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hoangnguyen0403/flutter-riverpod-state-management`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/flutter-riverpod-state-management/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/hoangnguyen0403/flutter-riverpod-state-management

---

# 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

```text
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](references/implementation.md) for full provider and consumer patterns.

## Consuming Providers

Use `ConsumerWidget` with `ref.watch()` and `AsyncValue.when()` for reactive UI. See [implementation examples](references/implementation.md).

## 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

- [flutter-layer-based-clean-architecture](../flutter-layer-based-clean-architecture/SKILL.md)
- [flutter-dependency-injection](../flutter-dependency-injection/SKILL.md)
- [flutter-testing](../flutter-testing/SKILL.md)