// Migrate Riverpod from 2.0 to 3.0; automatic retry, paused listeners, legacy providers import, Ref simplification, FamilyNotifier removal, ProviderException, updateShouldNotify. Use when the user asks about Riverpod 3 migration, upgrading to Riverpod 3, or breaking changes in 3.0.
Enable automatic disposal of Riverpod providers when they have no listeners; keepAlive, onDispose, invalidate, ref.keepAlive. Use when preventing memory leaks, caching only while used, or cleaning up resources when a provider is no longer needed. Use this skill when the user asks about auto-dispose, keepAlive, or when to dispose Riverpod state.
Cancel or debounce Riverpod async requests with ref.onDispose; cancel when user leaves the page, debounce rapid refreshes. Use when the user asks about cancelling requests, debouncing, or cleaning up when a provider is disposed.
Use Riverpod code generation (@riverpod, riverpod_generator) and hooks (hooks_riverpod, HookConsumerWidget, flutter_hooks with Riverpod). Use when the user asks about @riverpod, code generation, riverpod_generator, when to use codegen, or using flutter_hooks with Riverpod (HookConsumerWidget, HookConsumer).
Use Riverpod Consumer, ConsumerWidget, and ConsumerStatefulWidget to read and watch providers in widgets; WidgetRef, builder ref parameter. Use when building widgets that need to access Riverpod providers, ref.watch or ref.read in the UI, or converting StatelessWidget to ConsumerWidget. Prefer this skill when the user asks how to use providers in Flutter widgets or why ConsumerWidget is required.
Use ProviderScope in Flutter and ProviderContainer in Dart for Riverpod; where provider state is stored, overrides, observers, testing with ProviderContainer.test. Use when setting up Riverpod in Flutter or pure Dart, understanding where state lives, or writing tests with a fresh container. Use this skill when the user asks about ProviderScope, ProviderContainer, or where Riverpod stores state.
Eagerly initialize Riverpod providers at app startup by watching them in a root Consumer; handle loading/error in the initializer, AsyncValue.requireValue. Use when a provider must be ready before the rest of the app is used. Use this skill when the user asks about eager initialization or preloading providers.
| name | riverpod-3-0-migration |
| description | Migrate Riverpod from 2.0 to 3.0; automatic retry, paused listeners, legacy providers import, Ref simplification, FamilyNotifier removal, ProviderException, updateShouldNotify. Use when the user asks about Riverpod 3 migration, upgrading to Riverpod 3, or breaking changes in 3.0. |
For a full list of changes and highlights, see the official Riverpod docs (What's new in Riverpod 3.0). This skill summarizes the main migration steps.
Failing providers are retried by default in 3.0. To disable globally:
ProviderScope(retry: (retryCount, error) => null, child: MyApp())
// or ProviderContainer(retry: (retryCount, error) => null)
To disable per provider, pass retry: (retryCount, error) => null when defining the provider (or @Riverpod(retry: ...) with codegen). See riverpod-retry.
Listeners in widgets that are not visible (e.g. off-screen) are paused by default. There is no global switch. To keep a subtree from pausing, wrap it in TickerMode(enabled: true, child: ...) so the Consumer(s) inside do not follow the pause behavior.
These are moved to a legacy import. They are not removed but discouraged. To keep using them:
import 'package:flutter_riverpod/legacy.dart';
// or hooks_riverpod/legacy.dart, riverpod/legacy.dart
All providers now use == to filter updates (no longer identical). StreamProvider / StreamNotifier values are compared with ==. To customize, override updateShouldNotify(previous, next) on the Notifier (e.g. return true to always notify).
Observer methods now receive a single ProviderObserverContext (with container, provider, and optional mutation) instead of separate (provider, value, container) parameters. Update signatures, e.g.:
AutoDispose is still supported, but the separate type names (e.g. AutoDisposeProvider, AutoDisposeNotifier) are unified. Use Provider, Notifier, etc. with the same behavior. Migration: case-sensitive replace AutoDispose with a space (empty string) in type names.
FamilyNotifier, FamilyAsyncNotifier, FamilyStreamNotifier are removed. Use Notifier / AsyncNotifier / StreamNotifier and pass the parameter via the constructor (and store it in a field). Remove the parameter from build; build() takes no family argument. Example:
FamilyNotifier<int, String> with int build(String arg).Notifier<int> with constructor MyNotifier(this.arg) and final String arg;, and int build() using arg.When a provider throws, the exception is wrapped in ProviderException. If you catch the original type (e.g. on NotFoundException), change to on ProviderException catch (e) and check e.exception is NotFoundException. If you only use AsyncValue and value.hasError / value.error, no change needed.
For version highlights and more detail, see the official Riverpod documentation.