riverpod-faq-and-practices
Riverpod — FAQ and best practices
FAQ
ref.refresh vs ref.invalidate
ref.refresh = ref.invalidate + ref.read: it invalidates the provider and returns the new value. Use invalidate when you don't need the new value (e.g. "recompute when the user pulls to refresh"). Use refresh when you need the result right away. After invalidate alone, recomputation can happen at the next frame or when the provider is next read; refresh forces immediate recomputation by reading.
Why no shared interface between Ref and WidgetRef?
Ref (in providers) and WidgetRef (in widgets) are kept separate on purpose so you don't write code that conditionally depends on both; they have subtle differences and mixing would be error-prone. Prefer Ref: put logic in a Notifier and call ref.read(notifierProvider.notifier).yourMethod() from the UI; the method uses the Notifier's Ref.
Why ConsumerWidget instead of StatelessWidget?
InheritedWidget (and thus BuildContext) cannot support "on change" listeners like ref.listen, cannot know when widgets stop listening (needed for auto-dispose and family), and has lifecycle quirks (e.g. with GlobalKeys). Riverpod needs a Ref that isn't tied to BuildContext for these features. Hence ConsumerWidget (and Consumer) provide a Ref.
Why doesn't hooks_riverpod export flutter_hooks?
So each package can be versioned independently; a breaking change in one doesn't force the other to break.
More from serverpod/skills-registry
riverpod-codegen-and-hooks
Use Riverpod code generation (@riverpod, riverpod_generator) and hooks (hooks_riverpod, HookConsumerWidget, flutter_hooks with Riverpod). Use when the user asks about @riverpod, code generation, riverpod_generator, when to use codegen, or using flutter_hooks with Riverpod (HookConsumerWidget, HookConsumer).
30riverpod-providers
Declare and use Riverpod providers (Provider, FutureProvider, StreamProvider, NotifierProvider, AsyncNotifierProvider, StreamNotifierProvider); unmodifiable vs modifiable, top-level declaration, Ref, Notifier build method. Use when creating providers, choosing provider type, writing Notifier classes, or understanding Riverpod state. Use this skill whenever the user asks about Riverpod providers, provider types, or notifiers.
29riverpod-consumers
Use Riverpod Consumer, ConsumerWidget, and ConsumerStatefulWidget to read and watch providers in widgets; WidgetRef, builder ref parameter. Use when building widgets that need to access Riverpod providers, ref.watch or ref.read in the UI, or converting StatelessWidget to ConsumerWidget. Prefer this skill when the user asks how to use providers in Flutter widgets or why ConsumerWidget is required.
24riverpod-getting-started
Install Riverpod (flutter_riverpod or riverpod), wrap the app in ProviderScope, run a hello-world provider, and optionally enable riverpod_lint and code generation. Use when starting a Flutter or Dart project with Riverpod, adding the Riverpod dependency, or setting up ProviderScope and a first provider. For version highlights see the official Riverpod docs.
23riverpod-auto-dispose
Enable automatic disposal of Riverpod providers when they have no listeners; keepAlive, onDispose, invalidate, ref.keepAlive. Use when preventing memory leaks, caching only while used, or cleaning up resources when a provider is no longer needed. Use this skill when the user asks about auto-dispose, keepAlive, or when to dispose Riverpod state.
21riverpod-observers
Use ProviderObserver to log or debug Riverpod provider lifecycle; didUpdateProvider, ProviderScope observers, naming providers. Use when adding logging, analytics, or debugging for provider state changes. Use this skill when the user asks about ProviderObserver, logging Riverpod, or debugging provider updates.
21