riverpod

riverpod Best Practices

Riverpod is the definitive state management solution for modern Flutter applications. It provides compile-time safety, unparalleled testability, and a declarative API. This guide outlines our team's mandatory best practices for leveraging Riverpod effectively.

1. Code Organization and Structure

Organize providers by feature or domain, not by provider type. This enhances modularity and discoverability. Always use @riverpod for code generation.

✅ GOOD: Feature-based Provider Grouping

// features/auth/auth_providers.dart
import 'package:riverpod_annotation/riverpod_annotation.dart';
import 'package:your_app/features/auth/auth_service.dart';

part 'auth_providers.g.dart';

@riverpod
AuthService authService(AuthServiceRef ref) {
  return AuthServiceImpl(); // Or mock in tests
}

@riverpod
class AuthNotifier extends _$AuthNotifier {
  @override
  bool build() {
    // Initial auth state logic
    return false;
  }

  void login() => state = true;
  void logout() => state = false;
}

❌ BAD: Generic or Type-based Grouping

// providers/auth_provider.dart (too generic)
// providers/future_providers.dart (grouped by type, not feature)
final authServiceProvider = Provider<AuthService>((ref) => AuthServiceImpl());
final authNotifierProvider = StateNotifierProvider<AuthNotifier, bool>((ref) => AuthNotifier());

Action: Always run dart run build_runner watch during development to keep .g.dart files up-to-date.

2. Provider Types and Usage

Prefer generated @riverpod classes (Notifier, AsyncNotifier, StreamNotifier) for mutable state and FutureProvider/StreamProvider for immutable async data.

2.1. Mutable State: Notifier and AsyncNotifier

Use Notifier for synchronous mutable state and AsyncNotifier for asynchronous mutable state (e.g., API calls that modify state).

✅ GOOD: AsyncNotifier for state with async operations

// features/todos/todo_providers.dart
import 'package:riverpod_annotation/riverpod_annotation.dart';
import 'package:your_app/features/todos/todo_repository.dart';
import 'package:your_app/features/todos/todo_model.dart';

part 'todo_providers.g.dart';

@riverpod
class TodoListNotifier extends _$TodoListNotifier {
  @override
  Future<List<Todo>> build() async {
    // Initial fetch
    return ref.watch(todoRepositoryProvider).fetchTodos();
  }

  Future<void> addTodo(Todo todo) async {
    state = const AsyncValue.loading(); // Show loading state
    state = await AsyncValue.guard(() async {
      final newTodo = await ref.read(todoRepositoryProvider).addTodo(todo);
      return [...state.value!, newTodo]; // Update state immutably
    });
  }
}