Riverpod : les fondamentaux

Providers, ref.watch / read / listen, AsyncValue, Notifier et AsyncNotifier, cycle de vie et nouveautés de Riverpod 3. C'est le socle de toute question « state management » en entretien senior, et le point où un passé GetX doit se transformer en argument plutôt qu'en handicap.

Le problème que résout un state management

Flutter sait reconstruire un widget quand son état change : c'est setState. Le problème commence quand une donnée est utile à plusieurs écrans éloignés dans le widget tree (l'arbre de widgets). Le solde du wallet s'affiche sur l'accueil, conditionne le bouton de transfert et doit être rafraîchi après un paiement. Le faire remonter de parent en parent par les constructeurs (prop drilling) devient vite intenable.

Un state management répond à quatre questions :

• Où vit l'état ? Hors des widgets, pour survivre aux reconstructions et être partagé.
• Qui est notifié quand il change ? Uniquement les widgets qui en dépendent.
• Comment le modifier ? Par des méthodes explicites, pas en écrivant n'importe où.
• Comment le remplacer en test ? Sans toucher au code de production.

État éphémère et état applicatif

La documentation Flutter distingue l'ephemeral state (état local à un widget : onglet sélectionné, animation en cours, texte d'un champ) et l'app state (état partagé : session, solde, panier, préférences). Le premier reste dans un StatefulWidget. Le second va dans un state management. La frontière n'est pas dogmatique : un état local qui doit soudain être lu ailleurs migre.

Pourquoi Riverpod

Riverpod a été écrit par l'auteur de provider pour corriger ses limites. Ses arguments tiennent en quatre points, à savoir formuler en entretien.

• Compile-safe. Un provider est une variable globale finale et immuable : une déclaration, pas un état. Si vous le lisez, il existe forcément. Pas de ProviderNotFoundException à l'exécution comme avec provider, pas de Get.find qui échoue parce qu'un Get.put n'a pas eu lieu.
• Pas de dépendance au BuildContext. Un provider peut en lire un autre via ref, sans widget. La logique métier ne dépend pas de l'arbre de widgets.
• Testabilité. Chaque provider peut être remplacé (override) dans un ProviderScope ou un ProviderContainer, sans singleton à réinitialiser.
• Un graphe de dépendances. Quand un provider en watch un autre, Riverpod connaît l'arête. Si la source change, les dépendants sont recalculés. Si plus personne n'écoute, l'état peut être libéré (autoDispose).

ProviderScope et les widgets consommateurs

Les états des providers vivent dans un ProviderContainer. En Flutter, ProviderScope crée ce container et doit envelopper l'application. Sans lui, la première lecture lève une erreur.

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

void main() {
  runApp(const ProviderScope(child: WalletApp()));
}

Trois façons d'obtenir un WidgetRef dans un widget :

class ClockConsumer extends StatelessWidget {
  const ClockConsumer({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(children: [
      const Text('Statique, jamais reconstruit'),
      Consumer(
        builder: (context, ref, child) {
          // Seul ce builder est reconstruit à chaque seconde.
          final now = ref.watch(clockProvider).value;
          return Text(now?.toIso8601String() ?? '');
        },
      ),
    ]);
  }
}

Les types de providers

Riverpod 3 recommande cinq types, plus leurs variantes .family et .autoDispose. StateProvider, StateNotifierProvider et ChangeNotifierProvider sont legacy : ils ont été déplacés dans package:flutter_riverpod/legacy.dart et ne doivent plus apparaître dans du nouveau code.

Il existe aussi StreamNotifierProvider, moins courant. Règle simple : lecture seule, Provider / FutureProvider / StreamProvider ; état modifiable par l'UI, un Notifier.

Deux syntaxes : manuelle et codegen

Chaque provider peut s'écrire à la main ou être généré par riverpod_generator (annotation @riverpod, outil build_runner). Les deux sont officiellement supportées.

final walletRepositoryProvider = Provider<WalletRepository>((ref) {
  return HttpWalletRepository(ref.watch(dioProvider));
});

final walletProvider = FutureProvider.autoDispose<Wallet>((ref) {
  final repo = ref.watch(walletRepositoryProvider);
  return repo.fetchWallet();
});

final clockProvider = StreamProvider.autoDispose<DateTime>((ref) {
  return Stream.periodic(const Duration(seconds: 1), (_) => DateTime.now());
});

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'wallet_providers.g.dart';

@Riverpod(keepAlive: true)
WalletRepository walletRepository(Ref ref) {
  return HttpWalletRepository(ref.watch(dioProvider));
}

// Génère walletProvider, autoDispose par défaut.
@riverpod
Future<Wallet> wallet(Ref ref) {
  return ref.watch(walletRepositoryProvider).fetchWallet();
}

Le générateur déduit le type de provider de la signature : une fonction qui renvoie un Future donne un équivalent de FutureProvider, une classe qui étend _$Nom donne un Notifier. Le nom du provider est le nom de la fonction ou de la classe suivi de Provider. Détail vérifié avec riverpod_generator 4 : pour une classe nommée TodoNotifier, le suffixe est retiré et le provider s'appelle todoProvider.

ref.watch, ref.read, ref.listen

C'est la question la plus fréquente en entretien Riverpod. Chaque méthode a un rôle précis.

@override
Widget build(BuildContext context, WidgetRef ref) {
  // Lu une seule fois : l'écran ne se mettra jamais à jour.
  final visible = ref.read(balanceVisibleProvider);
  return Text(visible ? 'Solde visible' : 'Masqué');
}

class BalanceLabel extends ConsumerWidget {
  const BalanceLabel({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final visible = ref.watch(balanceVisibleProvider);
    final balance = ref.watch(walletProvider.select((w) => w.value?.balance));
    return GestureDetector(
      // Dans un callback : read, jamais watch.
      onTap: () => ref.read(balanceVisibleProvider.notifier).toggle(),
      child: Text(visible ? '${balance ?? '-'}' : '••••'),
    );
  }
}

Les erreurs typiques :

• read dans build pour « optimiser ». La documentation est explicite : n'utilisez pas ref.read pour éviter ref.watch. Si vous voulez moins de reconstructions, utilisez select.
• watch dans un callback ou après un await. Un abonnement n'a de sens que pendant un build : dans un callback, le résultat est imprévisible et le code ne passera pas une revue.
• listen pour afficher une donnée. listen sert aux effets de bord, pas à produire l'UI.
• listen dans initState. Interdit : utilisez ref.listenManual, qui renvoie une subscription à fermer si besoin.

@override
Widget build(BuildContext context) {
  ref.listen(beneficiariesProvider, (previous, next) {
    if (next case AsyncError(:final error)) {
      ScaffoldMessenger.of(context)
          .showSnackBar(SnackBar(content: Text('Échec : $error')));
    }
  });
  // ... reste du build
}

AsyncValue

FutureProvider, StreamProvider et AsyncNotifier exposent un AsyncValue<T>. En Riverpod 3, c'est une sealed class à trois sous-types : AsyncLoading, AsyncData, AsyncError. Le switch Dart 3 est donc exhaustif : le compilateur vous signale le cas oublié.

class HomeScreen extends ConsumerWidget {
  const HomeScreen({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final wallet = ref.watch(walletProvider);
    return RefreshIndicator(
      // refresh renvoie le Future du nouveau calcul : l'indicateur attend la fin.
      onRefresh: () => ref.refresh(walletProvider.future),
      child: ListView(
        children: [
          switch (wallet) {
            AsyncData(:final value) => BalanceCard(wallet: value),
            AsyncError(:final error) => ErrorView(
                error: error,
                onRetry: () => ref.invalidate(walletProvider),
              ),
            AsyncLoading() => const Center(child: CircularProgressIndicator()),
          },
          if (wallet.isRefreshing) const LinearProgressIndicator(),
        ],
      ),
    );
  }
}

La méthode when reste disponible et donne le même résultat, avec des options skipLoadingOnRefresh (vrai par défaut) et skipLoadingOnReload (faux par défaut). Le switch a l'avantage d'être du Dart standard, lisible par quelqu'un qui ne connaît pas Riverpod.

Un AsyncValue porte plusieurs informations à la fois

Un AsyncValue n'est pas un simple trois-états. Pendant un rafraîchissement, l'état conserve la valeur précédente et signale un chargement. Comportement vérifié sur flutter_riverpod 3.4.3 :

Conséquence pratique : dans le switch ci-dessus, un pull-to-refresh garde la carte du solde affichée (branche AsyncData) et la barre fine signale le chargement. C'est le comportement attendu par un utilisateur.

value, requireValue, hasValue

• value : la donnée ou null, y compris pendant un chargement ou une erreur si une donnée précédente existe. En Riverpod 3, valueOrNull a été renommé value (l'ancien value qui relançait l'erreur a disparu).
• requireValue : la donnée, ou une exception s'il n'y en a pas. À réserver aux endroits où vous avez la garantie qu'elle existe. Depuis 3.1, il sert aussi à combiner de façon synchrone des providers asynchrones dans un FutureProvider ou un AsyncNotifier.
• hasValue, hasError, isLoading, isRefreshing, isReloading : des drapeaux indépendants, pas exclusifs.

Notifier et AsyncNotifier

Un Notifier est une classe qui possède un état et expose des méthodes pour le modifier. C'est l'équivalent conceptuel d'un view model. Trois règles :

• build() calcule l'état initial. C'est le seul endroit où l'on watch d'autres providers.
• state est l'état courant. L'affecter notifie les écouteurs (si la nouvelle valeur est différente selon ==, nouveauté de la 3.0 pour tous les providers).
• Les méthodes publiques sont les seules façons de modifier l'état depuis l'extérieur. L'état doit être immuable : on remplace, on ne modifie pas en place.

final balanceVisibleProvider =
    NotifierProvider<BalanceVisibleNotifier, bool>(BalanceVisibleNotifier.new);

class BalanceVisibleNotifier extends Notifier<bool> {
  @override
  bool build() => true; // état initial

  void toggle() => state = !state;
}

@riverpod
class BalanceVisible extends _$BalanceVisible {
  @override
  bool build() => true;

  void toggle() => state = !state;
}
// Utilisation : ref.watch(balanceVisibleProvider)
//               ref.read(balanceVisibleProvider.notifier).toggle()

void add(Beneficiary b) {
  state.add(b); // même instance : == renvoie vrai, personne n'est notifié
}

void add(Beneficiary b) {
  state = [...state, b];
}

AsyncNotifier, AsyncValue.guard et Ref.mounted

final beneficiariesProvider =
    AsyncNotifierProvider.autoDispose<BeneficiariesNotifier, List<Beneficiary>>(
  BeneficiariesNotifier.new,
);

class BeneficiariesNotifier extends AsyncNotifier<List<Beneficiary>> {
  @override
  Future<List<Beneficiary>> build() {
    return ref.watch(beneficiaryRepositoryProvider).fetchAll();
  }

  Future<void> add({required String name, required String phone}) async {
    state = const AsyncLoading(); // la liste précédente reste dans state.value
    final result = await AsyncValue.guard(() async {
      final repo = ref.read(beneficiaryRepositoryProvider);
      await repo.add(name: name, phone: phone);
      return repo.fetchAll();
    });
    if (!ref.mounted) return; // le provider a pu être détruit pendant l'await
    state = result;
  }
}

AsyncValue.guard exécute le Future et renvoie AsyncData en cas de succès ou AsyncError (avec la stack trace) en cas d'exception. Il remplace un try/catch répétitif. Un second paramètre optionnel permet de ne capturer que certaines erreurs et de relancer les autres.

Le test ref.mounted est indispensable en Riverpod 3 : utiliser un Ref ou affecter state après la destruction du provider lève désormais une exception (UnmountedRefException). Avec un provider autoDispose, l'utilisateur qui quitte l'écran pendant la requête suffit à déclencher le cas.

Invalidation et refresh

• ref.invalidate(p) : marque l'état comme périmé. S'il a des écouteurs, il est recalculé (au plus tard à la prochaine lecture) ; sinon il est simplement détruit. Ne renvoie rien.
• ref.refresh(p) : invalide puis relit immédiatement, et renvoie la nouvelle valeur. Avec p.future, renvoie le Future du nouveau calcul, idéal pour RefreshIndicator.onRefresh.
• ref.invalidateSelf() : depuis l'intérieur d'un provider ou d'un Notifier.

Préférez invalidate quand vous n'utilisez pas le résultat : c'est plus explicite et cela évite un calcul si plus personne n'écoute. Après un transfert réussi, invalider walletProvider suffit : l'accueil se mettra à jour.

select pour limiter les reconstructions

Par défaut, ref.watch reconstruit à chaque nouvel état. select ne reconstruit que si la partie sélectionnée change (comparaison par ==).

// Reconstruit seulement si le booléen change, pas à chaque item ajouté.
final isSaving = ref.watch(beneficiariesProvider.select((s) => s.isLoading));

// Sur un AsyncValue : sélectionner une partie de la donnée.
final balance = ref.watch(walletProvider.select((w) => w.value?.balance));

Dans un provider asynchrone, selectAsync joue le même rôle et renvoie un Future. Le sélecteur doit renvoyer une valeur comparable : renvoyer une nouvelle liste à chaque appel annule le bénéfice.

Cycle de vie : autoDispose, keepAlive, onDispose

Riverpod compte les abonnements (watch et listen) sur chaque provider. Quand le compteur tombe à zéro, ref.onCancel est appelé. Si le provider est autoDispose et toujours inutilisé à la frame suivante, son état est détruit et ref.onDispose est appelé.

• Codegen : autoDispose par défaut. Désactivation : @Riverpod(keepAlive: true).
• Sans codegen : pas d'autoDispose par défaut. Activation : .autoDispose (ou le paramètre isAutoDispose: true).
• ref.keepAlive() renvoie un KeepAliveLink : l'état est conservé jusqu'à link.close().
• ref.onDispose : fermer un StreamController, annuler un Timer, un CancelToken Dio.

extension CacheForExtension on Ref {
  void cacheFor(Duration duration) {
    final link = keepAlive();
    final timer = Timer(duration, link.close);
    onDispose(timer.cancel);
  }
}

final cachedWalletProvider = FutureProvider.autoDispose<Wallet>((ref) async {
  final wallet = await ref.watch(walletRepositoryProvider).fetchWallet();
  ref.cacheFor(const Duration(minutes: 2)); // seulement après un succès
  return wallet;
});

Les nouveautés de Riverpod 3

Retry automatique

Un provider dont le calcul échoue est relancé automatiquement avec un backoff exponentiel. Valeurs par défaut lues dans le code source 3.4.3 : 200 ms, doublé à chaque essai, plafonné à 6,4 s, au plus 10 essais. Les sous-types de Error (erreurs de programmation comme StateError) et les ProviderException ne sont pas réessayés.

void main() {
  runApp(
    ProviderScope(
      retry: (retryCount, error) {
        if (error is AuthFailure) return null; // inutile de réessayer
        if (retryCount >= 3) return null; // on abandonne
        return Duration(milliseconds: 200 * (1 << retryCount));
      },
      child: const WalletApp(),
    ),
  );
}

// Par provider : désactiver.
final noRetryProvider = FutureProvider.autoDispose<Wallet>(
  (ref) => ref.watch(walletRepositoryProvider).fetchWallet(),
  retry: (retryCount, error) => null,
);
// Avec codegen : @Riverpod(retry: maFonctionDeRetry)

Ref.mounted

Équivalent de BuildContext.mounted : vaut faux une fois le provider détruit. À tester après chaque await avant d'utiliser ref ou state.

Pause des providers non visibles

Les listeners d'un widget sont mis en pause quand le widget n'est plus visible, en s'appuyant sur TickerMode (écran recouvert par une route, onglet inactif). Un provider dont tous les abonnés sont en pause est lui-même en pause : un StreamProvider qui interroge le serveur cesse de travailler pour un écran caché. Pour garder un écran actif malgré tout, l'envelopper dans TickerMode(enabled: true, ...). ref.listen renvoie aussi une subscription avec pause() et resume().

ProviderContainer.test

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  test('walletProvider expose le solde du repository', () async {
    // Disposé automatiquement à la fin du test.
    final container = ProviderContainer.test(
      overrides: [
        walletRepositoryProvider.overrideWithValue(FakeWalletRepository()),
      ],
    );
    // listen garde le provider autoDispose en vie pendant le test.
    container.listen(walletProvider, (previous, next) {});

    final wallet = await container.read(walletProvider.future);
    expect(wallet.balance, 125000);
  });
}

En widget test, tester.container() renvoie le container du ProviderScope pompé. La documentation recommande de ne jamais partager un container entre tests et de mocker les repositories plutôt que les Notifiers.

Autres changements à connaître

• AsyncValue est sealed ; valueOrNull devient value.
• Tous les providers filtrent les notifications avec == (surcharge possible via updateShouldNotify).
• Les erreurs relues via ref.read / watch sont enveloppées dans ProviderException ; AsyncError garde l'erreur d'origine.
• FamilyNotifier et les interfaces AutoDispose* disparaissent (voir chapitre 07).
• Mutations et persistance hors ligne existent en expérimental (chapitre 07).

De GetX à Riverpod : table de correspondance

Si vous venez de GetX, vous connaissez déjà les besoins : un objet qui porte l'état, un widget qui réagit, un moyen de retrouver l'objet. Riverpod répond aux mêmes besoins avec deux différences de fond : l'état est immuable et remplacé (pas des variables .obs mutées), et les dépendances sont déclarées (pas enregistrées à l'exécution).

Questions d'entretien

Exercices

Quiz

12 questions. Corrigez, relisez les explications, refaites-le 48 h plus tard.

Pour aller plus loin

• Riverpod : What's new in 3.0
• Riverpod : migration de 2.x vers 3.0
• Riverpod : Refs (watch, read, listen)
• Riverpod : auto dispose et cache
• Riverpod : tester ses providers
• Changelog de flutter_riverpod
• riverpod_lint
• Flutter : état éphémère et état applicatif