implementing-riverpod

Riverpod State Management (v3.3.x)

Goal

Implement compile-time safe, context-free state management using Riverpod. Use @riverpod code generation for all new code — the generator handles auto-dispose, family, and type safety automatically.

Process

Phase 1: Install Dependencies

Code Generation (Recommended):

dependencies:
  flutter_riverpod: ^3.3.1
  riverpod_annotation: ^4.0.2

dev_dependencies:
  build_runner: ^2.14.1
  riverpod_generator: ^4.0.3
  riverpod_lint: ^3.1.3

Manual only (no code generation):

dependencies:
  flutter_riverpod: ^3.3.1

Phase 2: Setup ProviderScope

void main() {
  runApp(ProviderScope(child: MyApp()));
}

Phase 3: Create Providers

Notifier (synchronous mutable state):

part 'counter.g.dart';

@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
  void decrement() => state--;
}
// Generated: counterProvider

AsyncNotifier (async mutable state):

@riverpod
class TodoList extends _$TodoList {
  @override
  Future<List<Todo>> build() async => fetchTodos();

  Future<void> addTodo(String title) async {
    state = const AsyncValue.loading();
    state = await AsyncValue.guard(() async {
      final todo = await apiClient.createTodo(title);
      return [...await future, todo];
    });
  }
}
// Generated: todoListProvider

FutureProvider with auto-retry:

@Riverpod(retry: myRetryStrategy)
Future<User> userProfile(Ref ref, String userId) async {
  return fetchUser(userId);
}

Duration? myRetryStrategy(int retryCount, Object error) {
  if (retryCount >= 5) return null;
  return Duration(milliseconds: 200 * (1 << retryCount));
}

→ See riverpod.md for manual providers, testing, Mutations, and offline persistence.

Phase 4: Consume Providers

Prefer Consumer to scope rebuilds to the smallest subtree. ConsumerWidget rebuilds the entire widget on every state change; Consumer rebuilds only its builder.