Flutter Riverpod Expert

# Flutter Riverpod Expert - 2025 Best Practices

You have expert knowledge in Flutter Riverpod state management following 2025 best practices. When the user is working with Riverpod or Flutter state management, apply these patterns and guidelines.

## When to Use This Skill

Activate this expertise when the user mentions:
- Riverpod, providers, state management, or StateNotifier
- AsyncNotifier, FutureProvider, StreamProvider, NotifierProvider
- Code generation with riverpod_generator or build_runner
- Data fetching, API integration, mutations, or reactive state
- State synchronization, caching, autoDispose, or memory management
- Provider testing, dependency injection, or repository patterns
- Performance issues with rebuilds, provider selection, or optimization
- Migration from old Riverpod patterns to modern approaches

## Core Principles (2025)

1. **Code Generation is STRONGLY RECOMMENDED** - Use `@riverpod` annotations and `riverpod_generator`
2. **AsyncNotifierProvider is PREFERRED** for async state (replaces FutureProvider/StreamProvider for consistency)
3. **AutoDispose by Default** - Codegen makes providers auto-dispose automatically
4. **Repository Pattern** - Separate data layer from state management
5. **Performance First** - Use `select()` to optimize rebuilds

## Provider Selection Guide

### Quick Decision Tree

**Immutable/Computed Values** - Use `Provider`:
```dart
@riverpod
String apiKey(Ref ref) => 'YOUR_API_KEY';

@riverpod
int totalPrice(Ref ref) {
  final cart = ref.watch(cartProvider);
  return cart.items.fold(0, (sum, item) => sum + item.price);
}
```

**Simple Synchronous State** - Use `NotifierProvider`:
```dart
@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
  void decrement() => state = max(0, state - 1);
}
```

**Async Data with Mutations (PREFERRED 2025)** - Use `AsyncNotifierProvider`:
```dart
@riverpod
class TodoList extends _$TodoList {
  @override
  Future<List<Todo>> build() async {
    final repo = ref.watch(todoRepositoryProvider);
    return repo.fetchTodos();
  }

  Future<void> addTodo(String title) async {
    state = const AsyncLoading();
    state = await AsyncValue.guard(() async {
      final repo = ref.read(todoRepositoryProvider);
      await repo.createTodo(title);
      return repo.fetchTodos();
    });
  }

  Future<void> deleteTodo(String id) async {
    // Optimistic update
    state = AsyncData(state.value!.where((t) => t.id != id).toList());

    try {
      await ref.read(todoRepositoryProvider).deleteTodo(id);
    } catch (e) {
      ref.invalidateSelf(); // Rollback on error
    }
  }
}
```

**Real-time Streams Only** - Use `StreamProvider`:
```dart
@riverpod
Stream<User?> authState(Ref ref) {
  return FirebaseAuth.instance.authStateChanges();
}
```

**Key Rule**: Prefer AsyncNotifierProvider over FutureProvider/StreamProvider for better consistency and mutation support.

## Code Generation Setup

### Dependencies (pubspec.yaml)
```yaml
dependencies:
  flutter_riverpod: ^2.5.0
  riverpod_annotation: ^2.3.0

dev_dependencies:
  build_runner: ^2.4.0
  riverpod_generator: ^2.4.0
  custom_lint: ^0.6.0
  riverpod_lint: ^2.3.0
```

### File Template
Every provider file needs:
```dart
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'filename.g.dart';  // REQUIRED

@riverpod
class MyProvider extends _$MyProvider {
  @override
  Future<Data> build() async => fetchData();
}
``