How rrousselgit/riverpod works
1. This is a monorepo for the Riverpod ecosystem
The repository is centered on the riverpod state-management framework and related packages. It is not a single app: it contains runtime libraries, Flutter integrations, code generators, lints, a devtool, persistence helpers, a documentation website, benchmarks, and many example apps.
2. The core runtime lives in packages/riverpod
This is the main engine. Its architectural center is the provider system: ProviderContainer, ProviderScope, Ref, provider elements/subscriptions, and the AsyncValue model for async state. Providers are the unit of state/logic, and the container is the boundary that stores, resolves, overrides, and disposes them.
3. packages/flutter_riverpod and packages/hooks_riverpod adapt the core to Flutter
These packages are thin presentation-layer bridges over the core runtime. They provide Flutter-facing consumer widgets and widget references so UI can read/watch providers without directly managing lifecycle plumbing. The boundaries here are: Flutter widget tree on one side, Riverpod container/ref APIs on the other.
4. Generated providers are a first-class part of the architecture
The repo heavily supports code generation. packages/riverpod_annotation defines annotations such as @riverpod, while packages/riverpod_generator parses annotated Dart source and emits *.g.dart provider glue. Generated code appears throughout examples and docs, showing that handwritten logic is often transformed into provider declarations automatically.
5. Static analysis and developer feedback are handled separately from runtime
packages/riverpod_analyzer_utils, packages/riverpod_lint, packages/internal_lint, and packages/lint_visitor_generator form the analysis/linting layer. These packages inspect Dart ASTs, infer provider usage, detect Riverpod-specific mistakes, and offer fixes/assists. This layer enforces architectural rules such as provider dependency correctness, scoping, and safe notifier usage.
6. The devtool is a separate introspection subsystem
packages/riverpod_devtool is a Flutter web app that connects to the Dart VM service. It inspects live provider state, frames, and object graphs, and includes search/filtering utilities. This is the runtime observability boundary: the app does not manage state itself, it queries a running app for Riverpod internals and renders them in a UI.
7. Persistence and offline support are modeled as extensions
packages/riverpod_sqflite and the experimental persistence APIs in riverpod/flutter_riverpod add storage-backed state. The architecture here is provider state flowing through a persistence adapter into local storage, enabling offline restore and cached state behavior without changing the app’s provider model.
8. Examples demonstrate the intended app architecture
The examples/ folder contains multiple small applications (counter, todos, pub, marvel, stackoverflow, random_number, first_app). These show the standard flow: domain/data layer feeds providers, providers expose async or synchronous state, and UI widgets consume that state. Many examples include generated files, reinforcing the codegen-based architecture.
9. The documentation website is itself a content application
website/ is a Docusaurus site with React/TypeScript UI components plus embedded Dart example code. It is not just static markdown: it has custom components, snippet generation, localization, and many runnable example fragments. The docs system is part educational content, part executable reference implementation.
10. Benchmarks and tooling are isolated from the product runtime
benchmarks/ measures provider operations such as creation, reads, listener add/remove. scripts/ and tools/ provide repo-wide automation and generation utilities. These are supporting subsystems, not part of the app runtime, but they validate performance and keep generated artifacts consistent.
11. Tests are broad and stratified by layer
Each package has its own tests, and the repo includes integration fixtures with generated outputs. The runtime packages test provider mechanics and lifecycle behavior, generator packages test emitted code, lint packages test diagnostics and fixes, and devtool/tests validate VM-service-driven inspection. This shows a layered architecture with strong contract testing between core, generator, analyzer, and UI-facing packages.
12. Main data flow across the repo
In the common Riverpod flow, user code declares providers or annotations, the generator/lints analyze and enrich that code, the runtime container executes providers and caches results, Flutter consumers read state and rebuild UI, and optional tooling such as the devtool or persistence layers observe or store the same provider state. The repository’s architecture is built around those boundaries rather than around a single application server/client split.
Main entry points: riverpod.dart Riverpod core · riverpod_generator.dart Generator · index.tsx Website · flutter_riverpod.dart Flutter Riverpod
Components 20
Core runtime
Provider engine, state model, and runtime extensions.
- Riverpod core · Main provider container, ref, provider, and AsyncValue runtime.
packages/riverpod/lib/riverpod.dart - Container · Creates, resolves, overrides, and disposes provider state.
packages/riverpod/lib/src/core/provider_container.dart - Providers · Functional, notifier, async, stream, and family provider implementations.
packages/riverpod/lib/src/core/provider/provider.dart - Ref API · Provider-side access to dependencies, lifecycle, and mutations.
packages/riverpod/lib/src/core/ref.dart - AsyncValue · Represents loading, data, and error states for async providers.
packages/riverpod/lib/src/core/async_value.dart
Flutter adapters
Widget-facing Riverpod integrations.
- Flutter Riverpod · Flutter widget integration over the core runtime.
packages/flutter_riverpod/lib/flutter_riverpod.dart - Consumer UI · Consumer widgets and widget refs for reading providers in Flutter.
packages/flutter_riverpod/lib/src/core/consumer.dart - ProviderScope · Widget-tree boundary that injects and overrides provider containers.
packages/flutter_riverpod/lib/src/core/provider_scope.dart - Hooks Riverpod · Flutter hooks integration layered on top of the core runtime.
packages/hooks_riverpod/lib/hooks_riverpod.dart
Generation
Annotations and source generation for providers.
- Annotations · Defines @riverpod and related opt-in annotations for code generation.
packages/riverpod_annotation/lib/riverpod_annotation.dart - Generator · Parses annotated Dart and emits provider glue and generated files.
packages/riverpod_generator/lib/src/riverpod_generator.dart - Templates · Reusable snippets for providers, notifiers, families, and hashes.
packages/riverpod_generator/lib/src/templates/template.dart
Analysis
Static analysis, lints, and assist infrastructure.
- Analyzer utils · AST and type utilities for Riverpod-specific static analysis.
packages/riverpod_analyzer_utils/lib/riverpod_analyzer_utils.dart - Riverpod lint · Diagnostics, fixes, and assists for Riverpod usage patterns.
packages/riverpod_lint/lib/main.dart - Internal lint · Repository-specific lint rules and visitors.
packages/internal_lint/lib/main.dart
Tooling
Devtool, persistence, benchmarks, and repo automation.
- Devtool · Live provider inspection UI backed by VM service data.
packages/riverpod_devtool/lib/main.dart - Sqflite persist · Local storage persistence for provider state and offline restore.
packages/riverpod_sqflite/lib/riverpod_sqflite.dart - Benchmarks · Measures provider creation, reads, and listener operations.
benchmarks/lib/main.dart
Connections 25
- Riverpod core → Container: contains · Core runtime centers on the container boundary.
- Riverpod core → Providers: implements · Provider types are the primary runtime abstraction.
- Riverpod core → Ref API: exposes · Provider logic runs through Ref.
- Riverpod core → AsyncValue: models · Async state is represented through AsyncValue.
- Container → Providers: manages · Container stores and disposes provider instances.
- Providers → Ref API: uses · Providers interact with dependencies and lifecycle through Ref.
- Flutter Riverpod → Consumer UI: provides · Flutter-facing consumer widgets wrap the core APIs.
- Flutter Riverpod → ProviderScope: provides · ProviderScope creates widget-tree container boundaries.
- Consumer UI → Riverpod core: reads · Widgets watch provider state from the core runtime.
- ProviderScope → Container: hosts · Scopes inject a ProviderContainer into Flutter trees.
- Hooks Riverpod → Riverpod core: adapts · Hooks integration builds on the same core engine.
- Annotations → Generator: drives · Annotations are input to generated provider glue.
- Generator → Templates: renders · Generator emits provider and notifier templates.
- Generator → Riverpod core: targets · Generated code instantiates core provider types.
- Analyzer utils → Riverpod lint: supports · Shared analysis helpers power lint diagnostics.
- Riverpod lint → Generator: aligns with · Lint rules reflect the generated-provider architecture.
- Internal lint → Riverpod lint: complements · Internal linting adds repository-specific rules.
- Devtool → Riverpod core: inspects · The devtool reads live Riverpod provider state.
- Sqflite persist → Riverpod core: extends · Persistence adapter stores provider state offline.
- Benchmarks → Riverpod core: measures · Benchmarks evaluate provider runtime operations.
- Examples → Riverpod core: uses · Sample apps demonstrate the core provider flow.
- Examples → Generator: shows · Examples commonly include generated provider glue.
- Website → Riverpod core: documents · Docs explain core concepts and provider behavior.
- Website → Flutter Riverpod: documents · Documentation includes Flutter consumer patterns.
- Website → Generator: documents · Docs include codegen-oriented examples.