Riverpod — Migrating from Provider

Motivation

Riverpod was created as a successor to Provider, addressing InheritedWidget limitations:

• Same type: Provider can't have two Provider<Item> in the tree (only the nearest is found). Riverpod has no such limit; providers are identified by variable, not type.
• Combining providers: ProxyProvider is tedious and error-prone. In Riverpod, use ref.watch inside a provider to depend on others; composition is straightforward.
• AsyncValue: Riverpod can expose previous data while loading (e.g. show old list + loading indicator). Provider doesn't offer this cleanly.
• Safety: Provider can throw ProviderNotFoundException at runtime. Riverpod avoids this by design.
• Disposal: Provider can't react when consumers stop listening; scoping is tricky. Riverpod offers autoDispose and ref.keepAlive for clear lifecycle and caching.
• Parameters: Riverpod's .family gives type-safe, parameterized providers with per-parameter state; with autoDispose, state is disposed when unused. Equivalent in Provider is impractical.
• Testing: With Provider you must re-define providers per test. With Riverpod, override with overrides to mock.
• Side effects: Riverpod offers ref.listen for reacting to changes (e.g. navigation, snackbars). Provider has no built-in equivalent.

The main API change: use ConsumerWidget (and WidgetRef) instead of StatelessWidget, and ref.watch / ref.read instead of context.watch / context.read.

---

Quickstart

• Read the Riverpod getting started guide (riverpod-getting-started) and try a small example.
• Migrate incrementally. You can run Provider and Riverpod side by side (use import aliases if needed).

Start with ChangeNotifierProvider

Keep existing ChangeNotifier classes and wrap them in Riverpod's ChangeNotifierProvider:

final myNotifierProvider = ChangeNotifierProvider<MyNotifier>((ref) => MyNotifier());

Use ProviderScope at the root. Replace context.watch with ref.watch where this provider is used (e.g. in a ConsumerWidget). No need to convert every ChangeNotifier to a Notifier immediately.

Start with leaves

Migrate providers that have no dependencies first (the "leaves"), then those that depend on them. Avoid migrating ProxyProviders until their dependencies are migrated.

One provider at a time

Migrate and test one provider at a time. Full migration of a ChangeNotifier means: (1) convert to Notifier + NotifierProvider, (2) replace every context.watch for it with ref.watch.

ProxyProvider → ref.watch

In Riverpod, combining providers is done with ref.watch inside another provider:

final labelProvider = Provider<String>((ref) {
  final userIdNotifier = ref.watch(userIdNotifierProvider);
  return 'The user ID is ${userIdNotifier.userId}';
});

For stateful combined objects (like ChangeNotifierProxyProvider), use ref.listen in the provider to react to another provider and update your notifier.

Eager initialization

Riverpod providers are lazy. To warm data at startup, watch the provider at the root (e.g. in a Consumer under ProviderScope that returns your app as child). See riverpod-eager-initialization.

Code generation

Code gen doesn't generate ChangeNotifierProvider. You can use a small extension (listenAndDisposeChangeNotifier) to expose ChangeNotifier with @riverpod during migration; once you switch to Notifier, remove the extension. See the official quickstart for the snippet.

---

Provider vs Riverpod

Defining providers

• Provider: Providers are widgets (e.g. inside MultiProvider).
• Riverpod: Providers are top-level final variables. No widget tree for definitions. Add ProviderScope at the root of the app.

Reading

• Provider: context.watch<T>(), context.read<T>(), context.select<T,R>(...).
• Riverpod: Use ConsumerWidget (or Consumer) to get WidgetRef ref; then ref.watch(provider), ref.read(provider), ref.watch(provider.select(...)).
• Use watch in build, read in event handlers. Same mental model as Provider.

Consumer

Riverpod has Consumer with (context, ref, child). No need for Consumer2, Consumer3, etc.: just multiple ref.watch calls in one builder.

Scoping vs family + autoDispose

Provider uses scoping to destroy state or have per-page state. In Riverpod:

• autoDispose destroys state when there are no listeners (ref.onCancel / ref.onDispose).
• .family gives parameterized providers (one state per parameter). Use with autoDispose to avoid unbounded cache.

So: use .family for "state per X" and .autoDispose for "destroy when unused" instead of scoping.

See riverpod-getting-started, riverpod-providers, riverpod-family, and riverpod-auto-dispose for details.