Migration Guide

Migrating directly from standard Riverpod to Riverpod Generator is easier than expected thanks to automated migration tools and similar syntax logic. Use this guide to translate specific provider concepts correctly.

StateProvider to Notifier

Pre-migration:

final themeProvider = StateProvider<ThemeMode>((ref) => ThemeMode.system);

Post-migration:

import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'theme_mode.g.dart';

@riverpod
class ThemeModeNotifier extends _$ThemeModeNotifier {
  @override
  ThemeMode build() => ThemeMode.system;

  void toggle(ThemeMode mode) => state = mode;
}

StateNotifier to Notifier

Pre-migration:

final cartProvider = StateNotifierProvider<CartNotifier, List<Item>>((ref) {
  return CartNotifier();
});

class CartNotifier extends StateNotifier<List<Item>> {
  CartNotifier() : super([]);
  // ... methods
}

Post-migration:

import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'cart.g.dart';

@riverpod
class CartNotifier extends _$CartNotifier {
  @override
  List<Item> build() => [];
  
  // ... methods (state is explicitly accessible via `state = `)
}

The Automation Tool

Riverpod author Remi Rousselet created a migration CLI to automatically parse legacy code into Riverpod Generator code. While imperfect, it severely reduces migration time.

• Step 1: Upgrade flutter_riverpod, riverpod.
• Step 2: Add riverpod_generator and riverpod_annotation to your pubspec.yaml.
• Step 3: Use dart run custom_lint (with Riverpod lint active).
• Step 4: Apply quick fixes provided by the linter directly in VS Code.