riverpod

Riverpod Skill

This skill defines how to correctly use Riverpod for state management in Flutter and Dart applications.

---

1. Setup

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

• Wrap your app with ProviderScope directly in runApp — never inside MyApp.
• Install and use riverpod_lint to enable IDE refactoring and enforce best practices.

---

2. Defining Providers

// Functional provider (codegen)
@riverpod
int example(Ref ref) => 0;

// FutureProvider (codegen)
@riverpod
Future<List<Todo>> todos(Ref ref) async {
  return ref.watch(repositoryProvider).fetchTodos();
}

// Notifier (codegen)
@riverpod
class TodosNotifier extends _$TodosNotifier {
  @override
  Future<List<Todo>> build() async {
    return ref.watch(repositoryProvider).fetchTodos();
  }

  Future<void> addTodo(Todo todo) async { ... }
}

• Define all providers as final top-level variables.
• Use Provider, FutureProvider, or StreamProvider based on the return type.
• Use ConsumerWidget or ConsumerStatefulWidget instead of StatelessWidget/StatefulWidget when accessing providers.

---

3. Using Ref

Method	Use for
ref.watch	Reactively listen — rebuilds when value changes. Use during build phase only.
ref.read	One-time access — use in callbacks/Notifier methods, not in build.
ref.listen	Imperative subscription — prefer ref.watch where possible.
ref.onDispose	Cleanup when provider state is destroyed.

// In a widget
class MyWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final value = ref.watch(myProvider);
    return Text('$value');
  }
}

// Cleanup in a provider
final provider = StreamProvider<int>((ref) {
  final controller = StreamController<int>();
  ref.onDispose(controller.close);
  return controller.stream;
});

• Never call ref.watch inside callbacks, listeners, or Notifier methods.
• Use ref.read(yourNotifierProvider.notifier).method() to call Notifier methods from the UI.
• Check context.mounted before using ref after an await in async callbacks.