Riverpod — Gerenciamento Compilado de Dependências para Flutter

O que é Riverpod?

Riverpod é uma biblioteca de gerenciamento de estado e injeção de dependências para Flutter que compila descrições de providers em código Dart seguro. Ao contrário do Provider, os providers do Riverpod não estão vinculados ao BuildContext: eles são criados globalmente ou no ProviderScope e são acessíveis de qualquer lugar. O compilador verifica tipos, dependências e a integridade do grafo de providers em tempo de compilação, eliminando erros em tempo de execução como ProviderNotFoundException.

Riverpod usa o modelo override para testes: cada provider pode ser sobrescrito via ProviderScope.overrideWith sem necessidade de criar subclasses ou mockar interfaces. Isso torna os testes isolados: cada teste obtém sua própria cópia do grafo de dependências que é totalmente controlada.

De acordo com a Flutter Community Survey 2025, Riverpod ocupa o terceiro lugar em popularidade depois de Provider e BLoC. No entanto, Riverpod é o pacote que mais cresce: +120% de instalações em 2024. Principais motivos: segurança em tempo de compilação, sem ProviderNotFoundException, suporte assíncrono integrado via AsyncValue.

Tipos de Providers

Riverpod fornece 8 tipos de providers, cada um para um cenário específico: Provider (constante/serviço), StateProvider (estado primitivo), StateNotifierProvider (lógica complexa com StateNotifier), ChangeNotifierProvider (para migração do Provider), FutureProvider (dados assíncronos, única vez), StreamProvider (fluxo reativo), NotifierProvider (nova API, Flutter 3.10+) e AsyncNotifierProvider (Notifier assíncrono).

final counterProvider = StateNotifierProvider<CounterNotifier, int>((ref) {
  return CounterNotifier();
});

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);

  void increment() => state++;
  void decrement() => state--;
}

class CounterScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

ProviderRef — um objeto passado para cada provider para acessar outros providers. ref.watch — assinatura de mudanças, ref.read — leitura única, ref.invalidate — reinicialização de cache. ProviderRef substitui o BuildContext do Provider: qualquer provider pode ler outros providers sem acesso à árvore de widgets. Isso permite construir um grafo de dependências fora da camada de UI.

ProviderScope — o widget raiz, obrigatório para o Riverpod funcionar. ProviderScope armazena todos os providers, gerencia seu ciclo de vida e armazena valores em cache. Sem o ProviderScope o aplicativo falhará com ProviderNotFoundException. ProviderScope pode ser aninhado — um escopo aninhado sobrescreve os providers pai, o que é usado para testes e isolamento de funcionalidades.

AsyncValue e Trabalho com Assincronia

AsyncValue — uma classe selada do Riverpod para representar estado assíncrono. AsyncValue tem três variantes: AsyncData (dados bem-sucedidos), AsyncError (erro), AsyncLoading (carregando). Em vez de alternar manualmente entre loading/error/data, cada FutureProvider ou StreamProvider retorna automaticamente AsyncValue, e o widget lida com todos os três estados via ref.watch.

final userProvider = FutureProvider((ref) async {
  final api = ref.watch(apiProvider);
  return await api.fetchUser();
});

class UserScreen extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final userAsync = ref.watch(userProvider);
    return userAsync.when(
      data: (user) => UserWidget(user),
      error: (e, _) => ErrorWidget(e.toString()),
      loading: () => CircularProgressIndicator(),
    );
  }
}

AsyncValue.when — um método para pattern-matching de todos os três estados. O compilador verifica se todos os três casos são tratados — se você esquecer loading ou error, o código não compilará. AsyncValue.whenData — apenas para data (se loading/error não forem necessários). AsyncValue.guard — um invólucro sobre try-catch para converter exceções em AsyncError. keepAlive — uma flag que impede que o cache do provider seja destruído ao sair do escopo.

Geração de Código e @riverpod

Geração de código — um recurso chave do Riverpod 2.0+. A anotação @riverpod em uma função gera automaticamente um provider com o tipo correto, suporte a refatoração e autocompletar. A geração de código usa riverpod_generator e build_runner. O desenvolvedor escreve uma função pura, e todo o resto — tipos, classes, construtores factory — é gerado automaticamente.

@riverpod
String helloWorld(HelloWorldRef ref) {
  return 'Hello World';
}

// Gerado: final helloWorldProvider = Provider((ref) => 'Hello World');

@riverpod
class Counter extends _$Counter {
  int build() => 0;
  void increment() => state++;
}

Notifier — a nova API para estado mutável com geração de código. Notifier é uma classe com um método build() e métodos de mutação de estado. Ao contrário do StateNotifier, o Notifier não requer uma classe de estado separada e fornece acesso direto a state via getter/setter. Riverpod gera automaticamente um NotifierProvider para cada classe Notifier anotada com @riverpod.

build_runner: a geração de código é executada com o comando dart run build_runner build. Os arquivos gerados têm o sufixo .g.dart e são importados no código fonte. Quando as anotações ou tipos de providers mudam, a geração de código precisa ser reexecutada. Riverpod 2.x recomenda geração de código para todos os projetos novos — a criação manual de providers está se tornando obsoleta.

Riverpod vs Provider

Principais diferenças entre Riverpod e Provider: independência do BuildContext, segurança em tempo de compilação, suporte assíncrono integrado, cache automático e testes via override. Provider requer BuildContext para acessar estado (context.watch, context.read), Riverpod usa WidgetRef e providers declarados globalmente.

Migração do Provider: Riverpod suporta ChangeNotifierProvider.adaptive para usar ChangeNotifier existente sem reescrever. Migração gradual: primeiro novos recursos são escritos com Riverpod, depois instâncias antigas do Provider são substituídas por providers do Riverpod via um adaptador. Ambos os pacotes podem coexistir em um projeto, permitindo migrar sem congelar o desenvolvimento.

Testando Riverpod

Testar Riverpod é baseado em ProviderScope.overrideWith. Cada provider é sobrescrito dentro de um ProviderScope de teste sem mocks ou contêineres DI. ProviderContainer — um ambiente isolado para testes sem Flutter (Dart puro), permitindo testar providers sem renderização de widgets.

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

void main() {
  test('Counter increments correctly', () {
    final container = ProviderContainer();
    container.read(counterProvider.notifier).increment();
    expect(container.read(counterProvider), 1);
  });

  testWidgets('UI updates on increment', (tester) async {
    await tester.pumpWidget(
      ProviderScope(
        overrides: [counterProvider.overrideWithValue(5)],
        child: CounterScreen(),
      ),
    );
    expect(find.text('5'), findsOneWidget);
  });
}

ProviderContainer — sem Flutter. Use ProviderContainer para testes unitários de providers sem widgets. overrideWithValue — substituir um provider por um valor específico. overrideWith — substituir por uma fábrica de providers (para mockar serviços). autodispose — em testes verifique se o provider é destruído ao sair do escopo usando container.dispose().