Skip to content

Upgrading flutter_riverpod 2 to 3

Breaking2.6.1 → 3.4.3Breaking21Platform1Deprecated1New31Changed28Fixed24Other4

BreakingUpgrade verdict

20 breaking changes and a platform requirement change.

  • Code that implements ProviderObserver directly must now extend it instead.
  • Code using FamilyNotifier and its variants must switch to Notifier.
  • Provider-specific Ref types are gone. Use Ref, and switch to AsyncNotifier for FutureProviderRef.future.
  • The valueOrNull getter is gone. Read .value instead.
Top 5 of 22 that need code or config changes

Dart SDK requirement changed in 3.4.1: >=2.17.0 <4.0.0 → ^3.12.0.

Breaking20
ProviderObserver is now marked with base, so external classes can no longer implement it directly.
ProviderObserver
Removes FamilyNotifier and its variants in favour of Notifier.
FamilyNotifierNotifier
Removes all Ref subclasses such as FutureProviderRef; use Ref directly instead.
RefFutureProviderRefFutureProviderRef.futureAsyncNotifier
Removes AsyncValue.valueOrNull; use .value instead.
AsyncValue.valueOrNullAsyncValue.value
When an asynchronous provider rebuilds, previous provider subscriptions are removed only when the rebuild completes.
Offline's Storage is now base and requires overriding deleteOutOfDate.
StoragedeleteOutOfDate
Errors rethrown by ref.watch/ref.read are now wrapped in a ProviderException.
ref.watchref.readProviderException
Simplifies parts of the API, such as fusing AutoDisposeNotifier and Notifier.
AutoDisposeNotifierNotifier
Moves ChangeNotifierProvider, StateProvider and StateNotifierProvider out of hooks_riverpod.dart to hooks_riverpod/legacy.dart.
ChangeNotifierProviderStateProviderStateNotifierProvider
All providers now use == to compare previous and new values and filter updates.
updateShouldNotify
Deletes ProviderListenable.addListener, which is now internal-only.
ProviderListenable.addListener
ProviderObserver methods now take a ProviderObserverContext parameter instead of provider and container.
ProviderObserverProviderObserverContext
All ref and notifier methods besides mounted now throw if used after disposal.
mounted
AsyncValue.value now returns null during errors.
AsyncValue.value
Notifier and variants are now recreated whenever the provider rebuilds, enabling Ref.mounted to check dispose.
NotifierRef.mounted
StreamProvider now pauses its StreamSubscription when the provider is not actively listened.
StreamProviderStreamSubscription
Calling ref.watch multiple times now calls ref.onListen every time.
ref.watchref.onListen
A provider is now considered paused if all of its listeners are also paused.
Makes AsyncValue.copyWithPrevious @internal since it was not meant to be public.
AsyncValue.copyWithPrevious
Stops exporting some internal utils.
Platform1
Adds support for Dart 3.7.0.
Deprecated1
Deprecates family.overrideWith in favour of family.overrideWith2, whose callback takes the argument as a parameter.
family.overrideWithfamily.overrideWith2