I'm going to be honest with you.
When I first saw Riverpod, I opened the docs, read three sentences, and closed the tab. It felt like someone was explaining rocket science using more rocket science.
But now? I actually enjoy using it. It makes my Flutter apps cleaner, easier to debug, and way more maintainable. And the journey from "what even is this" to "okay I get it now" wasn't that complicated I just needed someone to lay it out in the right order.
So that's exactly what this blog is. A proper roadmap. The kind I wish I had when I started.
Before Anything Else What You Need to Know First
Riverpod is a state management library. So if you don't have a basic grip on Flutter and Dart first, Riverpod will feel like learning to drive on a highway without knowing how the steering wheel works.
Here's the honest prerequisite checklist. You don't need to be an expert at all of these just comfortable enough.
✅ 1. Dart Basics
You need to understand Dart before Flutter makes sense, and Dart for sure before Riverpod.
The things that actually matter for Riverpod:
Futures and async/await — Riverpod handles async data constantly. If you write await someApi.getData() and you don't fully understand what that await is doing, learn this first.
Future<String> getName() async {
await Future.delayed(Duration(seconds: 2));
return "Imesha";
}
Generics — Riverpod uses types like Provider<List<User>> or AsyncValue<String>. You need to be okay with seeing <SomeType> and knowing what it means.
Null safety — You'll see String? vs String constantly in Riverpod. Know the difference.
Classes and constructors — Riverpod uses a lot of classes. Make sure you're comfortable creating them, using named params, and understanding this..
✅ 2. Flutter Fundamentals
You should know:
- The difference between StatelessWidget and StatefulWidget and when to use each
- How setState() works (and why it gets messy as your app grows — this is literally why Riverpod exists)
- Basic widget tree understanding — parent, child, context
- BuildContext — what it is and why Flutter asks for it everywhere
- How navigation works (Navigator.push, go_router is a bonus)
If you've built at least one small Flutter app — a todo list, a weather app, anything — you're ready to start Riverpod.
✅ 3. Understand Why State Management Exists
This is the one most people skip, and then Riverpod never clicks for them.
Here's a simple story:
You build a shopping app. The cart icon in the top bar shows 0. When someone taps "Add to Cart" deep inside a product screen, the number should go to 1.
The problem? The cart icon and the product screen are completely different widgets. They don't know about each other. How does the cart number update?
Option A: Pass data up and down through every widget manually (called "prop drilling") — works for small apps, becomes a nightmare with 10+ screens.
Option B: Use a state management solution — keep the cart data in one place, and any widget that needs it can just listen to it.
Riverpod is Option B, done really well.
Okay, Now — What Actually Is Riverpod?
Riverpod is a library that lets you store your app's data (state) in providers. A provider is basically a box that holds some data. Any widget in your app can read from that box. When the data in the box changes, only the widgets that are watching that box rebuild.
That's it at the core.
The creator of Riverpod is Remi Rousselet, who also created the original Provider package. He built Riverpod to fix the problems Provider had — mainly compile-time safety, no more context.watch depending on widget position, and better support for async data.
You might ask: "Should I learn Provider or Riverpod?"
Short answer: Learn Riverpod. It's where the Flutter community is heading, it's more powerful, and if you understand the concepts, you'll pick up Provider easily too if you ever need it.
The Roadmap 🗺️
I've broken this into 4 phases. Don't rush between them. Actually build something small in each phase before moving on.
📦 Phase 1 — Foundation (Week 1-2)
Goal: Understand what providers are and read data from them in a widget.
Step 1: Install and Set Up Riverpod
The current package you want is flutter_riverpod (not just riverpod — that's the Dart-only version).
dependencies:
flutter_riverpod: ^2.5.1
Then wrap your app with ProviderScope. This is the "container" that holds all your providers. Without this, nothing works.
void main() {
runApp(
ProviderScope(
child: MyApp(),
),
);
}
That's literally step one. Simple.
Step 2: Learn Your First Provider — Provider
A Provider holds data that never changes. Think of it like a constant with superpowers.
final greetingProvider = Provider<String>((ref) {
return "Hello from Riverpod!";
});
Step 3: Read It in a Widget — ConsumerWidget
To read a provider, your widget needs to extend ConsumerWidget instead of StatelessWidget. It gives you access to ref, which is your key to the Riverpod world.
class HomeScreen extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final greeting = ref.watch(greetingProvider);
return Text(greeting);
}
}
See ref.watch()? That's how you "listen" to a provider. When the value changes, the widget rebuilds automatically.
Step 4: StateProvider — Your First Mutable State
A plain Provider is read-only. StateProvider lets you store state that can change.
final counterProvider = StateProvider<int>((ref) => 0);
// In your widget:
final count = ref.watch(counterProvider);
// To update:
ref.read(counterProvider.notifier).state++;
Build something here: A simple counter app using StateProvider. Boring, yes. But this is where the concept clicks.
🔄 Phase 2 — Core Providers (Week 3-4)
Goal: Understand the different provider types and when to use each one.
This is where most tutorials dump everything on you at once. Let's go one at a time.
StateNotifierProvider — For Complex State
When your state has multiple fields or complex logic, StateProvider gets messy. That's when you create a Notifier class.
class CartNotifier extends StateNotifier<List<String>> {
CartNotifier() : super([]);
void addItem(String item) {
state = [...state, item];
}
void removeItem(String item) {
state = state.where((i) => i != item).toList();
}
}
final cartProvider = StateNotifierProvider<CartNotifier, List<String>>((ref) {
return CartNotifier();
});
Now your widget does:
final cart = ref.watch(cartProvider);
ref.read(cartProvider.notifier).addItem("Shoes");
The notifier holds your methods, the provider holds your state. This separation is what makes Riverpod clean.
Build something here: A simple shopping cart. Add items, remove items, show a total count. This alone will teach you 60% of Riverpod you'll use day to day.
FutureProvider — For Async Data (APIs, DB)
This is the one you'll use constantly in real apps.
final userProvider = FutureProvider<User>((ref) async {
final response = await ApiService().getUser();
return response;
});
In your widget, Riverpod gives you AsyncValue which wraps three states automatically: loading, data, and error.
final userAsync = ref.watch(userProvider);
return userAsync.when(
loading: () => CircularProgressIndicator(),
error: (err, stack) => Text("Something went wrong"),
data: (user) => Text(user.name),
);
No more manually managing isLoading = true, hasError = false. Riverpod handles all of that for you.
StreamProvider — For Real-Time Data
Same as FutureProvider but for streams — like Firestore listeners, WebSockets, live location updates.
final messagesProvider = StreamProvider<List<Message>>((ref) {
return FirebaseFirestore.instance.collection('messages').snapshots()
.map((snap) => snap.docs.map((d) => Message.fromMap(d.data())).toList());
});
Usage is identical to FutureProvider — use .when().
Understanding ref.watch vs ref.read vs ref.listen
This confuses everyone in the beginning. Here's the simple version:
Method
When to use
ref.watch()
Inside build() — watches for changes and rebuilds the widget
ref.read()
Inside button callbacks, methods — reads once without rebuilding
ref.listen()
To react to changes without rebuilding (like showing a snackbar)
The rule: never use ref.read() inside build(). Always ref.watch() there.
🏗️ Phase 3 — Real App Patterns (Week 5-7)
Goal: Start using Riverpod in a real multi-screen app with proper architecture.
The Modern Way: NotifierProvider and AsyncNotifierProvider
In Riverpod 2.0+, StateNotifierProvider got upgraded. Now you have:
- NotifierProvider — replaces StateNotifierProvider for sync state
- AsyncNotifierProvider — replaces FutureProvider when you also need methods
class UsersNotifier extends AsyncNotifier<List<User>> {
@override
Future<List<User>> build() async {
return await ApiService().fetchUsers(); // called automatically
}
Future<void> addUser(User user) async {
await ApiService().postUser(user);
ref.invalidateSelf(); // refreshes the data
}
}
final usersProvider = AsyncNotifierProvider<UsersNotifier, List<User>>(() {
return UsersNotifier();
});
Notice that build() replaces the constructor logic. And you can call ref.invalidateSelf() to force a refresh after mutations. This is very clean.
Provider Dependencies — ref.watch Inside Providers
Providers can depend on other providers. This is powerful.
final filteredUsersProvider = Provider<List<User>>((ref) {
final users = ref.watch(usersProvider).value ?? [];
final filter = ref.watch(searchQueryProvider);
return users.where((u) => u.name.contains(filter)).toList();
});
When usersProvider or searchQueryProvider changes, filteredUsersProvider automatically recalculates. No manual wiring needed.
Family Modifier — Parameterized Providers
What if you need a provider that takes an argument? Like fetching a specific user by ID?
final userByIdProvider = FutureProvider.family<User, String>((ref, userId) async {
return await ApiService().getUser(userId);
});
In your widget:
final user = ref.watch(userByIdProvider("user_123"));
Use .family whenever you need a provider that behaves differently based on an input.
AutoDispose — Clean Up After Yourself
By default, providers live as long as your app. Sometimes you only want a provider to exist while a certain screen is open.
final searchProvider = StateProvider.autoDispose<String>((ref) => "");
When the widget using this provider leaves the screen, the provider is automatically destroyed and memory is freed.
You'll combine this with .family a lot:
final productProvider = FutureProvider.autoDispose.family<Product, String>((ref, id) async {
return await api.getProduct(id);
});
Code Generation with @riverpod (Riverpod Generator)
At some point you should switch to the code-gen approach. Instead of writing providers manually, you annotate your classes and a generator writes the boilerplate.
Add these packages:
dependencies:
riverpod_annotation: ^2.3.3
dev_dependencies:
riverpod_generator: ^2.4.0
build_runner: ^2.4.8
Then write:
@riverpod
Future<List<User>> users(UsersRef ref) async {
return await ApiService().fetchUsers();
}
Run flutter pub run build_runner watch and it generates usersProvider for you automatically. This is the recommended approach for new projects.
Build something here: A notes app or a simple blog reader that fetches from an API. Use AsyncNotifierProvider, .family, and .autoDispose. This is your bridge to advanced usage.
🚀 Phase 4 — Advanced Riverpod (Week 8+)
Goal: Handle complex real-world scenarios — auth flows, caching, testing, large apps.
Riverpod with go_router — Auth-Aware Navigation
One of the most common real-world needs: redirect users to login screen if they're not logged in, automatically go to home when they log in.
final authProvider = StateProvider<AuthState>((ref) => AuthState.unauthenticated);
final routerProvider = Provider<GoRouter>((ref) {
return GoRouter(
redirect: (context, state) {
final auth = ref.read(authProvider);
final isLoggedIn = auth == AuthState.authenticated;
if (!isLoggedIn && state.location != '/login') return '/login';
if (isLoggedIn && state.location == '/login') return '/home';
return null;
},
routes: [...],
);
});
The router itself is a provider, and it watches auth state. When auth changes, the redirect logic reruns automatically.
Repository Pattern with Riverpod
Clean architecture is important for large apps. The pattern:
- Repository — talks to your data sources (API, local DB)
- Notifier — business logic, uses the repository
- Widget — just reads providers and shows UI
// 1. Repository provider
final userRepositoryProvider = Provider<UserRepository>((ref) {
return UserRepository(dio: ref.watch(dioProvider));
});
// 2. Notifier uses repository
class UserNotifier extends AsyncNotifier<List<User>> {
@override
Future<List<User>> build() {
return ref.watch(userRepositoryProvider).getAll();
}
}
This separation makes testing extremely easy.
Testing Riverpod Code
This is where Riverpod really shines compared to other solutions. You can override any provider in tests.
testWidgets('shows user list', (tester) async {
await tester.pumpWidget(
ProviderScope(
overrides: [
usersProvider.overrideWith(() => MockUsersNotifier()),
],
child: MyApp(),
),
);
expect(find.text('Imesha'), findsOneWidget);
});
No mocking black magic. Just override the provider with a mock version. Clean.
Offline-First with Riverpod + Drift (or Isar)
For mobile apps, you want data to load from local DB first and sync with server in the background.
@riverpod
Stream<List<Note>> notes(NotesRef ref) async* {
// First, emit local data immediately
yield await ref.watch(localDbProvider).getNotes();
// Then sync with server
final serverNotes = await ref.watch(apiProvider).getNotes();
await ref.watch(localDbProvider).saveNotes(serverNotes);
// Emit updated data
yield serverNotes;
}
The widget doesn't know or care where the data came from. It just shows whatever the provider gives it.
ref.invalidate() and Refresh Patterns
Knowing when and how to refresh providers is an advanced skill.
// Refresh a specific provider
ref.invalidate(usersProvider);
// Refresh from inside a notifier
ref.invalidateSelf();
// Listen to a provider and refresh another one when it changes
ref.listen(authProvider, (prev, next) {
if (next == AuthState.loggedOut) {
ref.invalidate(usersProvider); // clear user data on logout
}
});
🗂️ What to Build at Each Phase
Phase
Project to Build
Phase 1
Counter App → Profile Card (static data)
Phase 2
Shopping Cart → Weather App (API call)
Phase 3
Notes App with CRUD → Movie Browser with search
Phase 4
Full app with auth, navigation, local storage
Don't skip building. Reading about Riverpod teaches you the vocabulary. Building with it teaches you the language.
Quick Reference — Which Provider Should I Use?
If you need...
Use this
Read-only computed value
Provider
Simple changeable value (int, bool, String)
StateProvider
Complex state with methods
NotifierProvider
Async data (API call, DB query)
FutureProvider or AsyncNotifierProvider
Real-time data (streams)
StreamProvider
Provider that takes an argument
.family modifier
Provider that cleans up on dispose
.autoDispose modifier
The Mindset Shift You Need
Here's the thing nobody says clearly enough:
Stop thinking in widgets. Start thinking in data.
In normal Flutter, you think: "My widget needs this data, so I'll fetch it here and pass it down."
In Riverpod, you think: "This data exists. Any widget that needs it just asks for it."
When that mental shift happens, Riverpod goes from "confusing" to "obvious." It usually happens somewhere in Phase 2 or 3. You'll know it when you feel it.
Resources I Actually Recommend
- Official Riverpod docs — riverpod.dev — Actually pretty good once you have the foundation
- Remi's examples on GitHub — github.com/rrousselGit/riverpod/tree/master/examples
- Flutter Riverpod 2.0 course on YouTube — search "Riverpod 2.0 Andrea Bizzotto" — best video resource
- Code with Andrea (codewithandrea.com) — detailed written tutorials, highly recommended
- Riverpod GitHub discussions — when you get stuck on something specific, the community is active there
Final Thoughts
Learning Riverpod is not a weekend thing. That's okay.
The providers take time to get used to. The ref object feels weird at first. The difference between .watch and .read will confuse you more than once before it sticks.
But every time you refactor some tangled setState mess into a clean notifier — it's deeply satisfying. Your code becomes easier to test, easier to read, and easier to extend.
Take it phase by phase. Build something real at each step. Don't move forward until the current thing clicks.
You've got this. 🚀
If you found this useful, share it with someone learning Flutter. And if you're building something cool with Riverpod, I'd love to see it — find me at imesha.dev.