riverpod-3-0-migration

Riverpod — Migrating from 2.0 to 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.

Automatic retry

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.

Out-of-view providers are paused

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.

Legacy providers (StateProvider, StateNotifierProvider, ChangeNotifierProvider)

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

Updates use ==

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).

ProviderObserver API change

Observer methods now receive a single ProviderObserverContext (with container, provider, and optional mutation) instead of separate (provider, value, container) parameters. Update signatures, e.g.:

• didAddProvider(ProviderObserverContext context, Object? value) (and similar for other callbacks).

Ref simplified; Ref subclasses removed

• Ref no longer has a type parameter. Use Ref everywhere (e.g. replace MyProviderRef with Ref in codegen).
• ProviderRef.state, Ref.listenSelf, FutureProviderRef.future are moved onto Notifier/AsyncNotifier: use Notifier.state, Notifier.listenSelf, AsyncNotifier.future instead of on ref. If you need these, use a class-based Notifier/AsyncNotifier and call them on the notifier.