Riverpod — Compiled Dependency Management for Flutter

What is Riverpod?

Riverpod is a state management and dependency injection library for Flutter that compiles provider descriptions into safe Dart code. Unlike Provider, Riverpod providers are not tied to BuildContext: they are created globally or in ProviderScope and are accessible from anywhere. The compiler checks types, dependencies and the integrity of the provider graph at build time, eliminating runtime errors like ProviderNotFoundException.

Riverpod uses the override model for testing: each provider can be overridden via ProviderScope.overrideWith without creating subclasses or mocking interfaces. This makes testing isolated: each test gets its own copy of the dependency graph that is fully controlled.

According to the Flutter Community Survey 2025, Riverpod ranks third in popularity after Provider and BLoC. However, Riverpod is the fastest-growing package: +120% installs in 2024. The main reasons: compile-time safety, no ProviderNotFoundException, built-in async support via AsyncValue.

Provider Types

Riverpod provides 8 types of providers, each for a specific scenario: Provider (constant/service), StateProvider (primitive state), StateNotifierProvider (complex logic with StateNotifier), ChangeNotifierProvider (for migration from Provider), FutureProvider (async data, one-time), StreamProvider (reactive stream), NotifierProvider (new API, Flutter 3.10+) and AsyncNotifierProvider (async Notifier).

final counterProvider = StateNotifierProvider<CounterNotifier, int>((ref) {
  return CounterNotifier();
});

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);

  void increment() => state++;
  void decrement() => state--;
}

class CounterScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

ProviderRef — an object passed to each provider for accessing other providers. ref.watch — subscription to changes, ref.read — one-time read, ref.invalidate — cache reset. ProviderRef replaces BuildContext from Provider: any provider can read other providers without access to the widget tree. This allows building a dependency graph outside the UI layer.

ProviderScope — the root widget, mandatory for Riverpod to work. ProviderScope stores all providers, manages their lifecycle and caches values. Without ProviderScope the app will crash with ProviderNotFoundException. ProviderScope can be nested — a nested scope overrides parent providers, which is used for testing and feature isolation.

AsyncValue and Working with Asynchrony

AsyncValue — a Riverpod sealed class for representing asynchronous state. AsyncValue has three variants: AsyncData (successful data), AsyncError (error), AsyncLoading (loading). Instead of manually switching between loading/error/data, each FutureProvider or StreamProvider automatically returns AsyncValue, and the widget handles all three states via ref.watch.

final userProvider = FutureProvider((ref) async {
  final api = ref.watch(apiProvider);
  return await api.fetchUser();
});

class UserScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final userAsync = ref.watch(userProvider);
    return userAsync.when(
      data: (user) => UserWidget(user),
      error: (e, _) => ErrorWidget(e.toString()),
      loading: () => CircularProgressIndicator(),
    );
  }
}

AsyncValue.when — a method for pattern-matching all three states. The compiler checks that all three cases are handled — if you forget loading or error, the code won't compile. AsyncValue.whenData — only for data (if loading/error are not needed). AsyncValue.guard — a wrapper over try-catch for converting exceptions to AsyncError. keepAlive — a flag that prevents the provider cache from being destroyed when it goes out of scope.

Code Generation and @riverpod

Code generation — a key feature of Riverpod 2.0+. The @riverpod annotation on a function automatically generates a provider with the correct type, refactoring support and autocomplete. Code generation uses riverpod_generator and build_runner. The developer writes a pure function, and everything else — types, classes, factory constructors — is generated automatically.

@riverpod
String helloWorld(HelloWorldRef ref) {
  return 'Hello World';
}

// Generated: final helloWorldProvider = Provider((ref) => 'Hello World');

@riverpod
class Counter extends _$Counter {
  int build() => 0;
  void increment() => state++;
}

Notifier — the new API for mutable state with code generation. Notifier is a class with a build() method and state mutation methods. Unlike StateNotifier, Notifier does not require a separate state class and provides direct access to state via getter/setter. Riverpod automatically generates a NotifierProvider for each Notifier class annotated with @riverpod.

build_runner: code generation is launched with the command dart run build_runner build. Generated files have the .g.dart suffix and are imported into the source code. When annotations or provider types change, code generation needs to be re-run. Riverpod 2.x recommends code generation for all new projects — manual provider creation is becoming deprecated.

Riverpod vs Provider

Key differences between Riverpod and Provider: independence from BuildContext, compile-time safety, built-in async support, auto-caching, and testing via override. Provider requires BuildContext to access state (context.watch, context.read), Riverpod uses WidgetRef and globally declared providers.

Migration from Provider: Riverpod supports ChangeNotifierProvider.adaptive for using existing ChangeNotifier without rewriting. Gradual migration: first new features are written with Riverpod, then old Provider instances are replaced with Riverpod providers via an adapter. Both packages can coexist in one project, allowing migration without freezing development.

Testing Riverpod

Testing Riverpod is built on ProviderScope.overrideWith. Each provider is overridden inside a test ProviderScope without mocks or DI containers. ProviderContainer — an isolated environment for tests without Flutter (pure Dart), allowing providers to be tested without widget rendering.

import 'package:flutter_test/flutter_test.dart';
import 'package:riverpod/riverpod.dart';

void main() {
  test('Counter increments correctly', () {
    final container = ProviderContainer();
    container.read(counterProvider.notifier).increment();
    expect(container.read(counterProvider), 1);
  });

  testWidgets('UI updates on increment', (tester) async {
    await tester.pumpWidget(
      ProviderScope(
        overrides: [counterProvider.overrideWithValue(5)],
        child: CounterScreen(),
      ),
    );
    expect(find.text('5'), findsOneWidget);
  });
}

ProviderContainer — without Flutter. Use ProviderContainer for unit testing providers without widgets. overrideWithValue — replacing a provider with a specific value. overrideWith — replacing with a provider factory (for mocking services). autodispose — in tests check that the provider is destroyed when it goes out of scope using container.dispose().