Riverpod — Reactive Caching and Data-Binding Framework for Flutter

Introduction

Riverpod is a reactive state management and data-caching framework for Flutter and Dart created by the author of Provider. It was designed from scratch to fix Provider's limitations around compile safety, testability, and combining multiple providers without BuildContext constraints.

What Riverpod Does

• Declares state as global provider objects that are compile-time safe and refactor-friendly
• Caches async data (HTTP responses, database queries) and handles loading and error states automatically
• Allows providers to depend on other providers with automatic rebuilds when dependencies change
• Supports code generation via riverpod_generator for reduced boilerplate
• Enables easy testing by overriding any provider in a ProviderScope without mocking frameworks

Architecture Overview

Riverpod providers are declared as top-level variables or annotated functions. At runtime, a ProviderContainer (wrapped by ProviderScope in Flutter) holds the actual state instances. When a widget calls ref.watch, Riverpod subscribes that widget to the provider's state; changes trigger a targeted rebuild of only that widget. Providers can read other providers via ref.watch or ref.read, forming a dependency graph that Riverpod automatically manages, including disposal when no widget listens.

Self-Hosting & Configuration

• Add flutter_riverpod (or hooks_riverpod for Flutter Hooks users) to pubspec.yaml
• Wrap the root widget in ProviderScope to initialize the provider container
• For code generation, add riverpod_annotation and riverpod_generator as dependencies and run build_runner
• Override providers in tests by passing overrides to ProviderScope or ProviderContainer
• Use riverpod_lint as a dev dependency to catch common mistakes with custom lint rules

Key Features

• Compile-safe providers that produce errors at build time rather than runtime, unlike Provider
• Built-in async support with AsyncValue that wraps loading, data, and error states
• No dependency on BuildContext, so providers can be read from anywhere including background isolates
• Provider families that accept parameters to create dynamic per-key state instances
• Auto-dispose mechanism that cleans up state when no widget is listening

Comparison with Similar Tools

• Provider — predecessor by the same author; requires BuildContext and has runtime errors for missing providers
• GetX — simpler API with less boilerplate but no compile-time safety or dependency graph
• BLoC — event-driven pattern with strict architecture; more ceremony but clearer separation of concerns
• MobX — annotation-based reactivity requiring code generation; similar reactivity model but different API philosophy
• Redux — single-store predictable state; familiar to web developers but verbose for Flutter

FAQ

Q: What is the difference between Riverpod and Provider? A: Riverpod removes the dependency on BuildContext, catches missing providers at compile time, and supports combining providers without nesting. Provider is simpler but has runtime failure modes.

Q: Does Riverpod require code generation? A: No. You can use Riverpod entirely without code generation by declaring providers manually. The generator reduces boilerplate but is optional.

Q: Can Riverpod handle server-side Dart applications? A: Yes. The core riverpod package (without flutter_riverpod) works in pure Dart, making it usable in server-side or CLI applications.

Q: How does auto-dispose work in Riverpod? A: When a provider is marked as autoDispose, Riverpod tracks listeners. Once no widget or provider watches it, the state is disposed. You can use ref.keepAlive() to prevent disposal when needed.

Sources

• https://github.com/rrousselGit/riverpod
• https://riverpod.dev/