The docs for riverpod aren't really ready for it to replace provider

[csells]

**Context As soon as provider is deprecated, riverpod is going to be assumed to be the new "default" state management solution for Flutter. There are other possibilities, e.g. bloc, but provider is so much a part of the Flutter community's core assumptions that riverpod is already perceived as "provider 2.0." With that in mind, the docs should support existing provider users moving to riverpod as well as new Flutter devs starting with riverpod w/o ever having used provider.

Describe what scenario you think is uncovered by the existing examples/articles

• The "Long story short" section is short and sweet, but doesn't describe what's going on and doesn't mention the more common use case of mutating a UDT, e.g. how do I update a Person in a way that causes build to be called?
• The Motivation section assumes existing provider knowledge. It should start from scratch, assuming most users will be new to Flutter and/or state management and will not be existing provider users.
• The README should cover the common cases with sample snippets, e.g. rewriting the counter app and how to implement CRUD in a Todo app.

Describe why existing examples/articles do not cover this case Normally I'd be happy to submit a PR but to date, the onramp docs for riverpod have actually stopped me from adopting it. I want something that walks me through the core use cases like the existing provider docs do. I'm happy to submit PRs/give more detailed feedback once I've seem enough to help me grok riverpod like I do provider.

[csells]

related: https://github.com/flutter/website/issues/7455

[rrousselGit]

Hello!

I agree. The docs need a big update. There's one in progress, but I'll keep your feedback in mind :)

[mwawrusch]

So I just started converted a redux app to riverpod and the docs are somewhat helpful but, as the OP mentioned, don't cover the use cases that people stumble upon first.

For example this is something I try to figure out right now:

What is the correct way to create a widget + provider combo that authenticates with a third party service (Intercom) once, and when the widget is destroyed, performs cleanup with Intercom. First of all, guidance would be appreciated, secondly, for those use cases it's important to document the life cycle, preferably with graphics.

In general what people need for state management solution is a list of cook books that document the best solution (s) for specific scenarios, so that there is no guesswork.

[lucavenir]

Hi there,

@rrousselGit would it make sense to open a whole section named "Cookbooks" in the documentation (or something similar)? I feel like I can contribute there, it's been a while since my first Riverpod-based App.

Ideas that come up in my mind (in which I think I can deliver):

1. Basic example with proper explanation for new Flutter peeps (e.g. setState VS Consumer)
2. StateNotifier & ChangeNotifier (e.g. state management and immutability patterns, etc.)
3. Authorization / Redirection / Protected Routes (e.g. with GoRouter)
4. AsyncValue (FutureProvider, StreamProvider) usage (e.g. infinite scrollable list)
5. A whole subsection onto common pitfalls
6. etc.

[rrousselGit]

That's definitely planned.

But if you want to contribute, there are other things I'd like to cover first

In particular, I'd like to implement the following toggle from the VueJS docs:

That toggles allows changing the code snippets to switch between a different syntax.

I'd like to do the same, but for flutter_hooks, freezed, StateNotifier vs ChangeNotifier, and the upcoming code-gen-based syntax for providers.

[lucavenir]

Sure thing, even though I don't clearly understand (atm) which are the two "options" in the switch.

I'd like to ask you how to contribute with the docs, can I do it privately or is it there a contribution guide? Thanks.

[rrousselGit]

You can contact me on twitter :)

[mwawrusch]

Regarding the toggle: What does composition mean in this context? Hooks? (I am aware of the term composition from the OOP days). And if so, that would be very helpful.

[TimWhiting]

Regarding the toggle: What does composition mean in this context? Hooks? (I am aware of the term composition from the OOP days). And if so, that would be very helpful.

Composition is the hooks api versus class/object api for VueJS.

The intent is to show different code snippets / explanations for people who use: flutter_hooks vs no hooks freezed vs no freezed StateNotifier vs ChangeNotifier

So this is really three toggles or checkboxes. Then we need a way to write examples / code snippets & explanations so that where code would differ you can provide different text/code. I don't think the current method of providing code in separate files scales well to 3 options / potentially 8 different unique combinations.

Then ideally we would need a way to parse and validate code examples, this happens with the current file based code examples.

Finally we need to show the correct code example given the options selected.

One potential way to author these would be:

# Markdown file
Here is some explanation {{#hooks about hooks}}{{#nohooks about no hooks}}.

Then we could have a preprocessing step to publishing the website, or a preprocessing step to show the documentation that takes anything matching {{#id ...}} and only showing the text within when the id is enabled. I know there are a few templating formats similar to this, the main concern is being able to be able distinguish it from regular code.

[rrousselGit]

What Vue does with the togle doesn't really matter. It's more about the idea

For Riverpod, I was thinking of 2 toggles:

• hooks
• code generation

And maybe a third one for mutable/immutable state

[mwawrusch]

Perhaps less a toggle and more tabs, similar to what alchemy is doing (right part of page):

https://docs.alchemy.com/reference/getnftmetadata

Anyways, much appreciated. I'd really love to see some guidance, especially on hook side of things.

[rrousselGit]

Riverpod is already using tabs atm

But I don't think this scales well. There are too many combinations for tabs

[TimWhiting]

I'm happy to help with converting any code to code that uses hooks. For the most part it is the same except for the naming of the consumer widgets. Right now we just need the infrastructure in place to allow for a ChangeNotifier/StateNotifier toggle in addition to the hooks toggle that already is there using tabs.

[neiljaywarner]

this sounds fantastic :) (both getting Chris 'onboarded', getting featured more by flutter website and getting doc improvements, and the codegen).

[rrousselGit]

Closing in favor of the more appropriate issues for tracking the various points.