Riverpod: the async state is a value you match on, not an exception you catch

Three packages, and the one named riverpod is not the Flutter one

The README opens with a table that is really an installation decision. There are three published packages: riverpod, described with a link to its page on the language package server, then flutter_riverpod, and then hooks_riverpod. Only the first lacks a Flutter or hooks prefix. That split is the design in one line. The core package knows about caching and data binding and nothing about widgets, which is why the reference list at the bottom of the page links to the inherited widget API from the Flutter documentation and to the older state management package it grew out of, alongside the hooks package. The name itself is the joke that makes the lineage memorable: Riverpod is an anagram of Provider.

The generator is the centre, and the annotated function is the input

The long story short is two steps. First you define network requests by writing a function and annotating it:

@riverpod
Future<String> breweryName(Ref ref) async {
  final response = await http.get(
    Uri.https('api.openbrewerydb.org', '/v1/breweries/random'),
  );
  final json = jsonDecode(response.body) as List;
  return (json.first as Map)['name']! as String;
}

Then you watch the generated provider in your UI. So the unit you write and test is an ordinary asynchronous function that receives a ref and returns a value, with no widget and no context in sight. That is what makes the framework-agnostic package usable on its own, and it is also what makes the data layer testable without pumping a single frame.

Loading and error are branches of one value, and the wildcard branch is deliberate

The widget example is where the philosophy becomes concrete. You watch the provider and switch on the result:

      final breweryName = ref.watch(breweryNameProvider);
      // Perform a switch-case on the result to handle loading/error states
      return switch (breweryName) {
        AsyncData(:final value) => Text('data: $value'),
        AsyncError(:final error) => Text('error: $error'),
        _ => const Text('loading'),
      };

Three things are visible there. The states are variants of a single value rather than three separate mechanisms. The fallback is a wildcard rather than a named loading state, which keeps the code short at the cost of not distinguishing refreshing from first load. And the README states the behaviour in prose as handling errors and loading states by default with no need to manually catch errors, which is the sentence the design exists to justify.

Testable, scalable and reusable are claims about the data layer, not the widget

The four benefits listed near the top are worth separating because they are not the same kind of promise. Handling errors and loading states by default is a behaviour of the provider's value type. Natively supporting advanced scenarios, with pull-to-refresh named as the example, is about what the framework lets you express rather than about convenience. Separating logic from your UI is the architectural claim, and it is the one the generator supports directly, since a provider is produced from a function that knows nothing about the view. Testable, scalable and reusable follow from that separation, and they hold to the extent that you keep providers outside widgets. The README does not describe the refresh mechanism itself, so if pull-to-refresh is your reason to adopt, read the documentation site rather than the page.

Eight example apps, and two lint configurations that differ by plugins

The repository is a workspace rather than a package, and the top level shows how it is organised: a packages directory, an examples directory containing a counter, a first app, a marvel app, a pub example, a random number example, a stackoverflow example and a todos app, plus other projects, benchmarks, tools, scripts, a website and resources. Two configuration files at the root are the detail worth noticing. There is one analysis options file and another that is explicitly the same thing without plugins, alongside a file listing every lint rule and a development tools options file.

No release tags, and a push from the same day

Administratively the project is a pub package rather than a tagged release line. There are no GitHub releases at all, the repository is not archived, and the last push is dated 2026-11-01. The README itself points at the documentation site for learning, with the documentation link standing in the position where an install snippet would be. So if you are adopting this, your version comes from the package you depend on rather than from a tag you can pin. The contributing notes are short and specific, listing bug reports for difficult scenarios, unclear documentation, typos, documentation updates and examples, and new features through a pull request. That list is a fair description of what a project at this stage of its release process needs from outside.

Editorial conclusion

Adopt it if you build Flutter or hooks-based Dart apps and want your data layer to be a plain function you can test without a widget tree. Before you start, pick the package that matches your app, since the framework-agnostic one exists for a reason, and read the contributing notes rather than the README for guidance on the current state of the project.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. rrousselGit/riverpod on GitHub