Upgrading flutter_riverpod 2 to 3
Breaking2.6.1 → 3.4.3Breaking21Platform1Deprecated1New31Changed28Fixed24Other4
BreakingUpgrade verdict
20 breaking changes and a platform requirement change.
In plain terms
- 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.
Must act 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.
What you must change
Breaking20
ProviderObserver is now marked with base, so external classes can no longer implement it directly.
ProviderObserverRemoves FamilyNotifier and its variants in favour of Notifier.
FamilyNotifierNotifierRemoves all Ref subclasses such as FutureProviderRef; use Ref directly instead.
RefFutureProviderRefFutureProviderRef.futureAsyncNotifierRemoves AsyncValue.valueOrNull; use .value instead.
AsyncValue.valueOrNullAsyncValue.valueWhen an asynchronous provider rebuilds, previous provider subscriptions are removed only when the rebuild completes.
Offline's Storage is now base and requires overriding deleteOutOfDate.
StoragedeleteOutOfDateErrors rethrown by
ref.watch/ref.read are now wrapped in a ProviderException.ref.watchref.readProviderExceptionSimplifies parts of the API, such as fusing AutoDisposeNotifier and Notifier.
AutoDisposeNotifierNotifierMoves ChangeNotifierProvider, StateProvider and StateNotifierProvider out of hooks_riverpod.dart to hooks_riverpod/legacy.dart.
ChangeNotifierProviderStateProviderStateNotifierProviderAll providers now use == to compare previous and new values and filter updates.
updateShouldNotifyDeletes ProviderListenable.addListener, which is now internal-only.
ProviderListenable.addListenerProviderObserver methods now take a ProviderObserverContext parameter instead of provider and container.
ProviderObserverProviderObserverContextAll ref and notifier methods besides mounted now throw if used after disposal.
mountedAsyncValue.value now returns null during errors.
AsyncValue.valueNotifier and variants are now recreated whenever the provider rebuilds, enabling Ref.mounted to check dispose.
NotifierRef.mountedStreamProvider now pauses its StreamSubscription when the provider is not actively listened.
StreamProviderStreamSubscriptionCalling ref.watch multiple times now calls ref.onListen every time.
ref.watchref.onListenA 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.copyWithPreviousStops exporting some internal utils.
Platform1
Adds support for Dart 3.7.0.
Deprecations to plan for
Deprecated1
Deprecates
family.overrideWith in favour of family.overrideWith2, whose callback takes the argument as a parameter.family.overrideWithfamily.overrideWith2