Structure a Flutter Riverpod application
Riverpod is most effective when providers describe dependencies instead of becoming an unstructured global namespace. Place feature providers beside the feature, keep shared service providers near the composition root, and use modern Notifier APIs for mutable state.
How the pieces connect
A starting folder structure
lib/
features/catalog/
presentation/catalog_page.dart
state/catalog_provider.dart
domain/catalog_repository.dart
data/api_catalog_repository.dart
core/dependency_injection/container.dartSeparate reading state from performing actions
A Consumer widget watches a provider to rebuild when state changes. Event handlers read the notifier and invoke an action. Do not trigger repeated side effects from a build method. Keep derived values in providers when multiple consumers need the same calculation.
Make lifetime an explicit decision
An automatically disposed search provider is useful for temporary screens. A session provider may need a longer lifetime. Persistence belongs in a repository or storage service, not in the assumption that a provider will remain mounted. Test navigation away and back before relying on retained state.
Design async states around the screen
Use AsyncNotifier for asynchronous state ownership. Distinguish initial loading from refreshing existing data, and expose actionable failures. Invalidate only the relevant dependencies after a write. Broad invalidation can trigger unnecessary requests across unrelated screens.
Test with isolated provider containers
Override a repository provider with a fake, create an isolated container, and dispose it after each test. Assert the initial state, the action result, and failure behavior. For widgets, wrap the screen in a ProviderScope with the same overrides. Generated code is optional; handwritten NotifierProvider declarations avoid a build step.
Try this configuration
Clean Architecture · Riverpod · Dio · Riverpod DI
The generator includes a working counter example with a repository contract, selected dependencies, navigation, and local setup instructions. Extend the example around your own domain before shipping.
Configure your Flutter project →Continue reading
- A practical guide to Flutter Clean Architecture
- BLoC vs Riverpod: choose by how your team works
- A maintainable GetX project structure
Primary references
Flutter application architecture documentation explains architectural recommendations. For state APIs, consult Riverpod documentation and BLoC documentation.