Flutter Riverpod 2: Practical Patterns for Real Apps

Riverpod 2 with the riverpod_generator code-gen approach is the most ergonomic state management I have used in Flutter. The annotations remove boilerplate and the type safety catches errors at build time. Here is how I structure a real app with it.

Folder layout

I keep providers next to the feature they belong to: lib/features/auth/auth_providers.dart, lib/features/cart/cart_providers.dart. Avoid one big providers.dart at the root — that file becomes a coupling magnet.

Async data with @riverpod

dart@riverpod
Future<List<Order>> orders(OrdersRef ref) async {
  final api = ref.watch(apiProvider);
  return api.fetchOrders();
}

// In a widget:
final orders = ref.watch(ordersProvider);
orders.when(
  data: (list) => OrdersList(list),
  loading: () => const CircularProgressIndicator(),
  error: (e, _) => ErrorWidget('$e'),
);

AsyncValue's .when() makes loading and error states a native part of the UI, not an afterthought. Most production state-management bugs come from forgetting to handle one of those — Riverpod makes that hard.

Invalidation, not manual refresh

When a mutation should refetch related data, call ref.invalidate(ordersProvider) after the mutation. Riverpod re-runs the provider and notifies all watchers. No manual cache invalidation, no stale state — the dependency graph handles it.

Where I keep regular setState

Truly local UI state — a TextField's controller, a tab index, a checkbox in a settings page — stays in the widget. Riverpod is for application state that crosses widgets. Lifting everything to providers makes the codebase harder to follow.