gbbest15 / riverpod

A simple way to access state while robust and testable.

---

A state-management library that:

• catches programming errors at compile time rather than at runtime
• removes nesting for listening/combining objects
• ensures that the code is testable

riverpod
flutter_riverpod
hooks_riverpod

Welcome to Riverpod!

This project can be considered as a rewrite of provider to make improvements that would be otherwise impossible.

For learning how to use Riverpod, see its documentation: https://riverpod.dev

Long story short:

• Declare your providers as global variables:

  final counterProvider = StateNotifierProvider((ref) {
    return Counter();
  });
  
  class Counter extends StateNotifier<int> {
    Counter(): super(0);
  
    void increment() => state++;
  }

• Use them inside your widgets in a compile time safe way. No runtime exceptions!

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

See the FAQ if you have questions about what this means for provider.

Migration

With the release of version 1.0.0, the syntax for interacting with providers changed.

See the migration guide for more information

Index

• Migration
• Index
• Motivation
• Contributing
• FAQ
  • Why another project when provider already exists?
  • Is it safe to use in production?
  • Will this get merged with provider at some point?
  • Will provider be deprecated/stop being supported?
• Sponsors

Motivation

If provider is a simplification of InheritedWidgets, then Riverpod is a reimplementation of InheritedWidgets from scratch.

It is very similar to provider in principle, but also has major differences as an attempt to fix the common problems that provider face.

Riverpod has multiple goals. First, it inherits the goals of provider:

• Being able to safely create, observe and dispose states without having to worry about losing the state on widget rebuild.
• Making our objects visible in Flutter's devtool by default.
• Testable and composable
• Improve the readability of InheritedWidgets when we have multiple of them (which would naturally lead to a deeply nested widget tree).
• Make apps more scalable with a unidirectional data flow.

From there, Riverpod goes a few steps beyond:

• Reading objects is now compile-safe. No more runtime exception.
• It makes the provider pattern more flexible, which allows supporting commonly requested features like:
  • Being able to have multiple providers of the same type.
  • Disposing the state of a provider when it is no longer used.
  • Have computed states
  • Making a provider private.
• Simplifies complex object graphs. It is easier to depend on asynchronous state.
• Makes the pattern independent from Flutter

These are achieved by no longer using InheritedWidgets. Instead, Riverpod implements its own mechanism that works in a similar fashion.

For learning how to use Riverpod, see its documentation: https://riverpod.dev

Contributing

Contributions are welcomed!

Here is a curated list of how you can help:

• Report bugs and scenarios that are difficult to implement
• Report parts of the documentation that are unclear
• Fix typos/grammar mistakes
• Update the documentation / add examples
• Implement new features by making a pull-request

FAQ

Why another project when provider already exists?

While provider is largely used and well accepted by the community, it is not perfect either.

People regularly file issues or ask questions about some problems they face, such as:

• Why do I have a ProviderNotFoundException?
• How can I automatically dispose my state when not used anymore?
• How to make a provider that depends on other (potentially complex) providers?

These are legitimate problems, and I believe that something can be improved to fix those.

The issue is, these problems are deeply rooted in how provider works, and fixing those problems is likely impossible without drastic changes to the mechanism of provider.

In a way, if provider is a candle then Riverpod is a lightbulb. They have very similar usages, but we cannot create a lightbulb by improving our candle.

Is it safe to use in production?

Yes.

Riverpod is stable and actively maintained.

Will this get merged with provider at some point?

It is possible. Some experiments are being made that could make this doable. But their outcome isn't clear yet. (no link to an issue to avoid putting unnecessary pressure on the people involved)

If those experiments are successful (although unlikely), then Provider and Riverpod could be fused.

Will provider be deprecated/stop being supported?

Maybe.

Provider has numerous flaws that can't quite be fixed. At the same time, Riverpod has proven to fix many of those.
As such, deprecating Provider is being considered.

The only inconvenience of Riverpod is the need for a "Consumer", which Provider doesn't need. But some alternatives are being investigated to maybe remove this constraint.

Whatever the decision is, a migration tool is planned to help assist migration from provider to Riverpod. Along with whatever other tool necessary to help.

Sponsors