Consider rethinking tutorial sequence

[markerikson]

I've had a few folks say that they had trouble following the tutorials for different reasons:

• The Advanced Tutorial is entirely written in TypeScript (example comment)
• Both the Intermediate and Advanced tutorials show converting existing apps (Intermediate: plain Redux todos, Advanced: React-only Github Issues), rather than trying to build up an app with RTK specifically (example comment)

I'd be open to the idea of redoing the tutorial sequence in some other way. Perhaps the existing pages could be semi-converted into "Usage Guides" of some kind: Intermediate -> "Migrating Existing Redux Apps", and Advanced -> some combo of "Adding Redux to a React App" and "TypeScript Example"?

But, that means we'd need to rethink what the tutorials should cover, and rebuild them from scratch.

I don't have time to do this myself right now, since I'm focused on the Redux core docs rewrite, but if someone else wanted to tackle this, I could offer guidance.

[PerpetualWar]

I would love to get involved with this, bit so far I haven't been using RTK, nor TypeScript with it. But I'm happy to discuss this further if you would be interested.

[sreetamdas]

Might need a little help but I'd love to work on this

[sreetamdas]

FWIW, I think we could try a different example which is a more verbose than a to-do app, especially in the advanced guide

[andreawyss]

What about a full App with router and multiple pages? Pages can grow in complexity. From simple basic ones that only use JS to more rich featured one using TS. All inside one single project that builds a real life App. Something that you can truly learn and use to build something real.

Maybe use: material-ui, axios, ...

Different routes could do similar things but using different libraries. ThunkItems route a full CRUD showings off Thunks. SagaItems route a full CRUD showing off Sagas.

Others could easily fork the project to show off a different way of doing something by just adding a new route.

Comparing code between folders makes it easy to see the pros and cons of different solutions/libraries.

This can help show off a reference architecture/best practices.

Simple hello worlds still can exist for some routes.

Tutorials will focus on explain the code in one route at the time. Building up from Basic to quite Advanced ones.

[markerikson]

@andreawyss : that sounds way more complicated than I want to do.

Remember, the goal here is to teach how to use Redux Toolkit, specifically. At the moment, we're orienting the docs towards "you already know how to use Redux, here's how RTK is different", but it would be nice if we could include some info on the Redux core concepts as well.

I don't want to show sagas at all, because most apps don't use them and we don't include them in RTK.

I don't want to spend time on things like using Material-UI, because that's not relevant to teaching RTK.

[mlynchdev]

Maybe build a counter, but as it counts, it does a new API call to avatars.adorable.io

That way you can sneak thunks in, the API is extremely simple and just change RTK0@adorable.io to RTK1, RTK2, RTK3 etc. etc. would display a different avatar face / color etc. it would be slightly more interesting as the pics are funny faces randomly generated by the email like identifier. While not adding too much complexity to explaining the key RTK concepts. Also would offer a chance to explain to novices the concept of a isLoading value and how that is handled in RTK?

[sreetamdas]

Actually, I think it'd be nice to have an example which isn't a counter for once :sweat_smile: Perhaps it could be another example besides the counter but it'd be refreshing to have a non-todo-list-or-counter example.

[mlynchdev]

@sreetamdas I think the concept of a beginner tutorial being simple enough to grasp yet engaging is important, and I think that async should be involved in beginner tutorial as well, in a very simple way. That was where my head was coming from.

[phryneas]

Just from my experience from workshops: The https://reqres.in/ API is pretty nice for example applications. Or the Chuck Norris joke API https://www.icndb.com/api/

[PerpetualWar]

@sreetamdas I think the concept of a beginner tutorial being simple enough to grasp yet engaging is important, and I think that async should be involved in beginner tutorial as well, in a very simple way. That was where my head was coming from.

I agree that async should be introduced much earlier in docs, but maybe not necessarily in tutorial, but rather in usage guide or something similar. Quick lookup section that explains the async necessities like how thunks are to be used now with RTK concepts.

[PepperAddict]

I would love to help out with this in any way I can. I'm coming from no Redux experience to using the toolkit. I'm going to be diving into Redux this weekend and will get started on the toolkit shortly after. I would love to share any insight and problems I face.

[landisdesign]

I'd love to give a crack at this. It seems the existing Todo app provides a decent starting point, just rewriting it from scratch. I'll take a look over the next week and come up with some text to poke at, if that's alright.

[landisdesign]

@markerikson I'm considering two substantial changes to the tutorial approach and wanted to get your thoughts before going down the rabbit hole:

1. Flipping the order of discussion between the tutorials. To me, it seems like the primary use case people have is creating slices, versus individual action creators or reducers with payload-free actions. It feels like those are special cases, versus everyday occurences.

By doing the slice tutorial first, I feel that lets programmers get what they came for up front. If they do need to create single action creators, or create payload-free reducers, or share actions between slices, these cases can be outlined in the last tutorial, as "expert features" in a sense.

This would introduce RTK from the top down versus the current bottom-up flow. I feel that could help developers see their code in action, get a feel for it, then let them dive into the details once they have a lay of the land.

Async would remain as the middle tutorial.

2. Significantly expand application design discussion. Since the current tutorial is a pure conversion, it didn't need to talk about why data is organized into slices or how actions align with reducer functions. The Redux tuorial does this, but I'd like to walk down those avenues in detail here as well. This would give the reader an idea of not just how RTK works, but also how to design for it, in a format that helps the reader see how to build the app start to finish.

The main drawback is this will make these tutorials much larger. I'm contemplating ways to signal experienced Redux users about the specific parts that are the meat of RTK, so they can skim the design elements, but I also want to help developers who are still somewhat new to Redux.

[markerikson]

@landisdesign : for reference, I'm planning on writing a new "Quick Start" tutorial page for the Redux docs in the very near future. That page will teach Redux itself, using a top-down approach, by showing how to use RTK. Once that's done, I intend to rewrite the existing Redux core tutorial sequence. It will still be a bottom-up approach, but it would culminate in "now that you know how to do this stuff by hand, here's how to use RTK so it's easier - use it as the default".

That brings up the question of what the RTK docs should be covering, and how.

My main points of concern with the existing RTK tutorials are:

• Focus on migrations instead of writing something from scratch
• The use of TS in the Advanced Tutorial is a blocker for some people

I'm less concerned about trying to teach Redux itself in the RTK tutorials, although I do think we need to actively direct folks over to the Redux core docs more clearly. I think I've got a note along those lines at the start of the Basic tutorial, but not in the RTK getting started page.

It would probably be good to list what points we want to cover and what target audiences we're aiming for, and try to sketch out a revised set of RTK docs based on those points.

[landisdesign]

@markerikson Makes sense. I'll put something together in the next couple of days.

[landisdesign]

@markerikson With your points in mind, I'll focus on rewriting the existing counter and to-do's from scratch. (Sorry, @sreetamdas!) For the advanced tutorial, I'm thinking of creating a color picker app that fetches data from https://reqres.in/ that @phryneas references.

For the Basic Tutorial, since we are starting from the ground up, versus conversion, I'd like to reverse the order of function introduction. My personal experience of action and reducer creation is working on the actions, then reducers, then using that to configure the store. So that introduces the functions as:

• createAction
• createReducer
• createSlice
• configureStore

For the Intermediate Tutorial, trying to rebuild the existing ToDo app seems way too big. Creating a much smaller version, with minimal styling, might do the trick. I would outline the components without attempting to explain them to any real extent, but the reader would be able to enter them in and see it work.

For the Advanced Tutorial, the color picker would be a simple drop-down of colors, fetched from the above source. Choosing a color shows the color as a PANTONE square below the drop-down. Perhaps adding to a list of "previously picked colors" with dispatch(clearList()) gives the opportunity to illustrate meshing thunks and traditional actions.

Thoughts?

[markerikson]

I'll have to think about it a bit. I'm admittedly still kind of attached to the current tutorial sequence in some ways, both because it's there already and because I wrote it.

Tell you what, go ahead and try sketching out what you think you might want to do for these, and we can discuss further.

Also interested in any thoughts on how we can reuse / repurpose the existing tutorials.

[landisdesign]

Ahh, yeah, I definitely know that feeling. Let's see how this comes together:

Overall, for each of the tutorials, I'm thinking of a basic outline of

• Here's our data, and the messages we're turning into actions.
• Here's how we do that with RTK.
• Here's how we connect the store and our actions to our components.
• Voila! You now have a functioning app.

This feels like this will give the reader steady progress to a satisfactory conclusion.

The counter example code feels good as-is. Its small size lends itself to being walked through quickly, start to finish, to cover the bases needed in the Basic Tutorial.

My concern with the ToDo example is that, as an example, it's sweet and elegant, but if we're aiming to show how to build from scratch with RTK, it feels rather large. I'm concerned about trying to walk a reader through from inception to finished product. Perhaps there can be a line drawn somewhere that says "From here on out, you can copy the components from the repo to hook up your RTK learnings to a real application." This could be a way to retain the current app's structure and leave the rest as a copy/paste exercise.

The same size concern applies to the example in the Advanced Tutorial as well, but to an even greater scale. Again, a nicely designed application, but doing it from scratch seems like it will be even longer than the conversion tutorial as it stands. I personally didn't have the stamina to walk through it when I was first learning.

The main focus for me in the Advanced Tutorial is using thunks. With that in mind, it feels like creating a small app devoted to that specific focus could lend itself to the subject in a shorter format. Data retrieval feels like the main example. The less data massaging or manipulation involved, the more the thunk usage would stand out. When I looked at the data coming from https://reqres.in, it looked nicely digestible and presentable.

It might make sense to separate the TypeScript usage into its own tutorial, perhaps rewriting one of the earlier apps with TypeScript in mind ("You've seen how to build this with RTK. Now let's look at it with RTK and Typescript.").

How does this sound? Let me know if there's things I should consider or change focus on.

[sadi304]

Advanced tutorial felt like a tutorial about using typescript with redux... It would be really great to have a separate advanced tutorial without typescript..

[markerikson]

Some feedback on the current RTK docs:

https://www.reddit.com/r/reactjs/comments/fx7dbr/reduxtoolkit_or_reactredux_vs_easypeasy_how_do/fmsiuzz/

Not sure I agree with the criticisms, but FYI.

[msutkowski]

Some feedback on the current RTK docs:

https://www.reddit.com/r/reactjs/comments/fx7dbr/reduxtoolkit_or_reactredux_vs_easypeasy_how_do/fmsiuzz/

Not sure I agree with the criticisms, but FYI.

I read through the reddit thread and jumped through those docs. I think they're just suggesting we split the Usage Guide up into simple, rapidly consumable sections that are the recommended conventions only and don't focus on the why so much. I suppose we could always add 🤛's to code samples as well. Overall, RTK's docs explain 'how and why' and elaborate on the reasoning a lot more than easypeasy's docs. The flow of RTK's content is the same, just presented differently and a bit more verbose.

I think I can see the benefit of splitting the usage guide into clear sections and doing the same with the TypeScript guide. Although we do that already, I think it's a presentation issue more so than anything. I could take a crack at that later this week after I address the other pending docs requests to see how it'd feel?

[markerikson]

Sure, interested in seeing what you come up with.

[Newbie012]

I have read the basic and the intermediate tutorials. In the advanced one, I gave up. There's too much mixed contents with RTK itself. It sounded like the docs assuming the following things:

1. You're familiar with react-redux and its corresponding libs (such as `react-thunk')
2. You're coming from an existing app (whether a simple app or an existing one with react-redux) implemented.

Don't get me wrong about 1, I do know what Redux is all about, but I'm used to write in Angular, so react-redux is foreign to me.

About 2, I have a fresh Typescript React app that I want to implement RTK in it, but the docs were mixing lots of non RTK specific stuff and I'll elaborate:

1. I don't think I need to know react-redux in order to understand how to use RTK (so modifications of a app based of react-redux doesn't make it any clearer).
2. I have a new app, I don't want to know how to migrate a totally different existing app into RTK.
3. I'm not entirely sure what HMR has to do with the reducers, but it was a part of the tutorial, plus I come from NextJS where it's implemented in a different way.
4. Typescript - I'm ok with Typescript, in fact, I prefer Typescript over JS since it's clearer for me to understand the flow, but that's because I'm used to it from Angular. In the contrary, most React devs are not familiar with Typescript, which add another learning curve to the tutorial.

I guess that what I'm trying to say is, split the tutorials from the actual usage. Maybe try to reorganize the docs by different topics. For example:

1. Basic usage (Step 1, 2, Ta-da!)
2. Migrate from react-redux
3. Usage with Typescript
4. HMR
5. Tutorials / Recipes
6. FAQ

[markerikson]

@Newbie012 thanks for the feedback. Responding to your comments:

• RTK, like the Redux core, is UI agnostic. That said, Redux is primarily used with React. So yes, we do assume that you are using React-Redux in both the core and RTK docs, especially since React-Redux is the only "official" UI bindings (ie, maintained by the Redux team).
• Per the discussion in this thread, yes, the tutorials are currently written under the assumption you know how the Redux core works, and are likely wanting to know the differences between writing Redux code by hand and using RTK.

Even if we do restructure the tutorials, I'm not sure there's going to be a set of pages that serve the "Angular user" viewpoint. Redux is ultimately going to be used with some UI layer, and since that's normally React, any examples will be using React-Redux.

The overall intent of the "Advanced" tutorial page was to show a more "real-world"-ish usage case. Since Create-React-App is the most common React app setup, the example is based on that. The point of the HMR was to be able to hot-reload both React components and reducer logic, without needing to refresh the whole page every time. I haven't worked with Next.js, so I don't know how you set up HMR for it. We can't cover every possible build tooling variation out there, even with multiple tutorial pages - it's just not feasible.

I do agree that the tutorials need to be rethought and split up, per this thread. We also need to explicitly list assumptions and prerequisites at the start of each page to help folks know what they're getting into. That's something I'm trying to do as I write a new set of tutorials for the Redux core docs.

Writing tutorials is hard, because we've got to balance trying to teach concepts, keeping things simple enough that the user can learn what's actually being taught, and at the same time meaningful enough that the user sees the purpose and motivation behind why and how to do things.

[Newbie012]

Even if we do restructure the tutorials, I'm not sure there's going to be a set of pages that serve the "Angular user" viewpoint

I didn't say that there should be tutorials for Angular users. I stated the fact that I'm a "newcomer," and I believe that this library can be perfect for people who don't want to learn deep the official React-Redux.

The overall intent of the "Advanced" tutorial page was to show a more "real-world"-ish usage case. Since Create-React-App is the most common React app setup, the example is based on that. The point of the HMR was to be able to hot-reload both React components and reducer logic, without needing to refresh the whole page every time. I haven't worked with Next.js, so I don't know how you set up HMR for it. We can't cover every possible build tooling variation out there, even with multiple tutorial pages - it's just not feasible.

And that's perfectly fine. I didn't ask for a tutorial that describes how to integrate with NextJS. The current tutorials will be very easy for developers who already experienced React-Redux and are looking for alternatives. If this is your only desired audience, then I guess you can keep the tutorials as they are. But if you want other people who didn't experience React-Redux, then I suggest a different approach that doesn't mix things with RTK.

I think you did an excellent job with this lib and the tutorials. I can't imagine how hard it was to create those very descriptive tutorials, and for that, I want to thank you. To wrap up, I guess that it's your decision if you wish just React-Redux devs to use the lib or any newcomer that interested in an alternative.

That's just my thoughts. I'm sure some people will disagree with my opinion :)

[markerikson]

Yeah, I'd certainly like any and all Redux users to use RTK, whether or not they're using React. That said, there's only so much effort we (I) can devote to writing the docs.

I do want to have a new "Using Redux with a UI" section in the Redux core docs, which would cover how to use it with React, Angular, Vue, vanilla JS, etc. That won't come for a while, though, and given how closely Redux is associated with React, it's reasonable to assume that they're being used together and write the tutorials accordingly.

[landisdesign]

To @Newbie012's point, do you want the RTK tutorials to build on Redux, or be able to stand alone?

[markerikson]

@landisdesign : sorta seeing two different interpretations of your question, so I'll try to answer them both.

I can write a state-only bunch of code with RTK, the same way I can write state-only code with a plain Redux store.

But, a real app will always have some actual UI, so a tutorial should also show how you'd use RTK as part of an actual app with UI setup, ie, React, meaning use of React-Redux.

In terms of whether the RTK tutorials should assume pre-existing knowledge of Redux or not... that's kinda the question we're trying to figure out here.

If we assume no prior knowledge of Redux, how much of those Redux core concepts should we be explaining? Seeing createSlice isn't going to make much sense if you have no idea what an "action" or "reducer" are. At that point, you're basically devolving into a full-blown Redux tutorial first, before we can even get into the RTK-specific aspects.

What I'm trying to do with the new Redux core "Quick Start" tutorial is spend just enough time introducing the core Redux concepts, but then show the RTK APIs as the default way to write code for those concepts.

[landisdesign]

Good point, and one I'm curious to explore. I feel like there might be room for a brief intro that explains actions as messages to tell Redux what to do, and slices as ways to keep code focused and efficient, with a "If you want to go deeper, check out the Redux docs" nod. Not too much, but enough to be able to jump into RTK. If someone wants to look under the hood, they can go to the Redux docs.

[phryneas]

Even if we do restructure the tutorials, I'm not sure there's going to be a set of pages that serve the "Angular user" viewpoint

I didn't say that there should be tutorials for Angular users. I stated the fact that I'm a "newcomer," and I believe that this library can be perfect for people who don't want to learn deep the official React-Redux.

@Newbie012 Just gotta add that there: RTK will never replace react-redux in any way. RTK only contains helpers for the redux library, you will have to use react-redux in combination with RTK just as you would use it in combination with redux.

[RyanAtViceSoftware]

I just went through the docs for my first attempt using redux-toolkit after using and loving redux for 3+ years now and I have to agree with this feedback.

• The Advanced Tutorial is entirely written in TypeScript (example comment)
• Both the Intermediate and Advanced tutorials show converting existing apps (Intermediate: plain Redux todos, Advanced: React-only Github Issues), rather than trying to build up an app with RTK specifically (example comment)

I especially agree with the TS criticism. I realize that for folks who like types it's hard to imagine TS not being your destination/desired outcome but I found myself using a decompiler to remove all the type noise from the code when I was working through the docs.

My feedback (most likely already covered):

• Treat TS as a special case not a first class citizen
• Create examples that start from 0 and work up. I thought the first tutorial did this really well.
• Build up around concepts. Getting the information for Async pattern was very hard. If I'm an experienced user and I want to just evaluate or learn really quick how to do a proper async call it's not easy. I ended up having to cross reference the intro-page with the advanced tutorial page to figure out how things work. Ideally I'd want to have the side menu show the big road map of things I need to figure out and when I click those items I should be shown those details. Example below

Example Feature Tutorial Map

1. Create your store
2. Decrease reducer boilerplate
3. Deal with side effects (Async calls, writing to localStorage, etc...)
4. Improve your data flow (not sure if this is correct but working with the Entity stuff)
5. Advanced topics (not sure what these are configs, etc...)

I'd vote you take the simple app created in the beginning and then just keep building on it. I usually use an existing API for testing like jsonplaceholder or api.github. Then I start by just stubbing the data that say users would return in the early example. Later examples switch to call the live API.

You might also want to flesh out common patterns like dealing with cross cutting concerns showing busy indicators and error notifications (note that I ended up wrapping the createThunk API to do this, probably not the approach you all would want to use) "

How I Could Help I'm not sure what the urgency is here but I love writing, even wrote a book on React a few years back, and would be happy to chip in. However, I am ramping up a new project and would likely have limited time for next 2 weeks.

[RyanAtViceSoftware]

@markerikson @phryneas not sure if my post above is appealing but @phryneas just helped me out with cancelling a promise chain from within the payload creator on discord. his message is below.

@Ryan Vice just saw your message. You could do a throw { name: 'AbortError', message: 'your abort reason' }, which would be identical to what an external abort would do. You could also just use rejectWithValue, because any type of abortion will result in a rejection anyways. That was essentially designed for that purpose.

And I feel that this could be a good thing to flesh out in the advanced topics in my proposed Feature Tutorial Map above. Basically show an example of cancelling so folks could see how that works by example.

[slim-hmidi]

I read a lot of great suggestions mentioned by different people here. I wanna share with you my opinion:

• In the Basic tutorial, let's try to use KISS principle (keep it stupid simple :) ), so no need to show difference between redux and redux-toolkit. Just create a simple app with redux-toolkit (counter app can do the stuff here); you can use createAction and createReducer at the first step (because someone who is used to creating reducers and actions will be surprised by createSlice from the beginning).

• In the intermediate tutorial, after being used to the basic apis of redux-toolkit, we can add a little bit of abstraction (not sure if it is the suitable word to be used) and mention createSlice and shows how it facilitates things and make stuff easier.

• According to advanced tutorial, now we can mention createAsyncThunk and createSelector and adding tests for the tutorial to show testing slices (I think the example of github-issues does the stuff no need to make another app). But for the different tutorials, no need to compare between redux and redux-toolkit, just developing app with redux-toolkit step by step and showing the different functionalities.

• We can use a tutorial to show how to use RTK with typescript in a separate section.

• Adding an example to show how to migrate from redux to RTK and in this section, we can mention the comparison between RTK and redux.

[danielrob]

As per conversation with mark https://twitter.com/danielrob_this/status/1261090971032289280, adding my two cents here.

IMO the most important thing documentation can provide is front page copy-paste examples (including imports) of most-common case usages of code, which redux-toolkit currently does not.

I've been using redux extensively for about three years, and recently went by the docs to check a couple of things and saw the awesome new style guide. This pointed me to the existence of redux-toolkit. It wasn't immediately relevant, as e.g. recently I've been using https://re-reduced.netlify.app/ which has overlapping functionality.

I'm currently in the process of adding a little npm library and thought I might as well use redux-toolkit for the example, but for that I just needed a quick copy-paste examples. I already understood the basic concepts of what the library was trying to achieve, but I'd never used it before, I just needed drop in code to get started on an example application.

I nearly bounced, but had read Mark's tweet about some substandard docs a few days earlier, and the irony wasn't lost on me, so here we are.

TL;DR: If it weren't for Mark and his tweets, the lack of immediate copy paste examples in es6 format in the first four link clicks at redux-toolkit.js.org would have meant I wouldn't have immediately adopted it in this instance.

[tim-rohrer]

Actually, I think it'd be nice to have an example which isn't a counter for once 😅 Perhaps it could be another example besides the counter but it'd be refreshing to have a non-todo-list-or-counter example.

Completely agree. Counters are too simple from my perspective, but it is also easy to get to a tutorial that is too complicated for me.

I am not experienced enough to write much for a tutorial. I am working on two apps from the ground up, and I'm trying to use RTK and TDD (and TS) for both. I really like all three as they are helping me immensely in my learning.

But RTK seems particularly challenging to use TDD with. I'm not trying to test RTK, but I do want to use TDD to develop and test my pieces of code, and I'm finding that difficult to do, especially with code associated with createAsyncThunk and createSelector.

I would like to see a tutorial that uses TDD. I am in a position to help, especially in validating the tutorial.

[RyanAtViceSoftware]

I usually like to have a master details flow in my tutorials

user list and clicking a user returns post for that user

something like that

[tim-rohrer]

• According to advanced tutorial, now we can mention createAsyncThunk and createSelector and adding tests for the tutorial to show testing slices (I think the example of github-issues does the stuff no need to make another app). But for the different tutorials, no need to compare between redux and redux-toolkit, just developing app with redux-toolkit step by step and showing the different functionalities.

I'm not sure I fully understand this paragraph, but I'll go through and read the advanced tutorial again.

I don't agree with relying upon GitHub Issues as examples. Perhaps they can be linked to for more details, but searching and extracting from them isn't smooth.

[markerikson]

@tim-rohrer: I think your specific situation is more complicated for a few reasons:

• You're trying to learn and work with a set of libraries that seem to be relatively new to you
• Thunks have always been considered somewhat harder to test, specifically because they involve async logic
• As I think I've said over in Reactiflux, the point of createAsyncThunk in particular is that it does all the hard work for you in terms of logic and behavior. You just call some API and return a promise.

Because of that, I don't think trying to write a bunch of tests for uses of createAsyncThunk is a good idea in the first place. I'd strongly recommend focusing your testing attention on reducers and selectors, because A) that's code you're actually writing yourself, and B) they're both pure functions and therefore very easy to test.

I personally am not a big fan of TDD overall, and I don't want to try to have an RTK tutorial that uses TDD as a teaching basis.

[RyanAtViceSoftware]

@tim-rohrer I'd go one step further and question the tradeoffs of testing reducers and selectors. IMHO Kent Dodds has the right ideas when it comes to testing: https://testing-library.com/docs/react-testing-library/intro. Isolated tests that test how things work are brittle and make refactoring expensive. Test your features instead :)

[landisdesign]

@RyanAtViceSoftware that becomes more of a philosophy question than a "what should the tutorial/API provide" question.

@tim-rohrer, in terms of testing code that takes advantages of the RTK, I'd definitely recommend testing your logic, not RTK's. Test the functions being passed into RTK, not the output. Let RTK handle the rest.

[tim-rohrer]

@landisdesign, I agree with that and remain happy to be testing the code I write. I do understand the idea of testing features, and avoiding testing implementation details, but am not convinced those are black and white scenarios. Reducers and their associated action creators reflect the results of things done by users. I want to be confident those results are predictable and repeatable. That said, I also recognize most of the code I add to createAsyncThunk and createSelector is pretty minimal and probably does not warrant a tremendous amount of time spent testing. So I nod my head to the comments above.

Given that I am quite possibly the least experienced developer in this thread, I am a primary consumer of tutorials. I believe I have finally developed enough basic methods to test most of my code without retesting this great library; however, imo, it took me too long to get to this point, and I am hopeful that future documentation can shorten that curve.

@markerikson, and others: Thank you for your hard work and conversations here and in Reactiflux.

[FredericLatour]

I will add my voice here. The way the documentation is written even for the basic tutorial makes it more or less necessary to study the old way of using Redux. I'm relatively knew to React but can perfectly understand the concepts behind Redux. However, understanding Redux concepts should not make it necessary to know or lean how those concepts were previously implemented. Learning Redux now, I just want to dive into the most recent and boilerplate free approach.

I believe you should have a completely separate section for comparison or migration concerns. The tutorials should only explain how to write Redux the new idiomatic way using RTK.

Have a look at easy-peasy documentation:

• They provide a very basic simple example of creating a perfectly working store. Ok it's quite basic but you get the essence.
• Then you get a more advanced tutorial divided into clear section (and not things like introducing createSlice ;))

Their documentation is crystal clear and there must be a reason if they have 3.5k stars.

I understand you certainly spent a lot of time on the documentation but believe me, as said, by several people, the current documentation is confusing as hell and is too much work and ceremony for those who start learning Redux now.

[markerikson]

I do want to reiterate that RTK truly is a layer on top of the Redux core. Even if you're not writing a bunch of action creators by hand, you do still need to know what "actions", "action creators", "reducers", "immutability", and "dispatching" are. Those are all Redux core concepts, not RTK concepts.

I realize that this does make it a bit difficult to teach RTK by itself.

I'm starting to think that maybe what we ought to do is put, very very clearly, that you should spend time reading the Redux core docs first, and then come back to the RTK docs specifically.

As I've said a couple times in this thread, the new Redux "Quick Start" tutorial I'm working on will be the "intro to Redux with RTK as the default way to write Redux code" that people are asking for. I'd rather not duplicate that content between both docs sites.

[FredericLatour]

It has nothing to do with having to deal with actions, reducers, dispatching and immutability. The fact is that your tutorial is really a tutorial on how to convert an existing redux application the RTK way.
I don't have any existing application to convert. I just want to be exposed to Redux using the optimal up-to-date syntax. Honestly, it's too much work to go through the old syntax first..

Take the following sentence at the very beginning of the basic tutorial from the point of view of someone that decided to learn Redux :

Normally, you create a Redux store by calling createStore() and passing in your root reducer function. Redux Toolkit has a configureStore() function that wraps createStore() to do the same thing, but also sets up some useful development tools for you as part of the store creation process. We can easily replace the existing createStore call with configureStore instead. configureStore accepts a single object with named fields, instead of multiple function arguments, so we need to pass our reducer function as a field named reducer:

It's not that this is conceptually difficult ... it's just that one suddenly realizes that he will basically have to learn the old way for making sense of this documentation ;).

But I feel stupid here, I did not realize that you were writing a new tutorial using the RTK way. I will check it as soon. Thanks.

[markerikson]

@FredericLatour right , like i just said, I agree that focusing the tutorials on migrating existing apps isn't the right approach.

Problem is, you're then left with two options :

• assume the reader already knows what Redux is, and focus on the differences
• assume the reader doesn't know what Redux is, and start from scratch

But if we go with the second option, now we're basically duplicating the Redux core docs, albeit maybe with a different spin on the explanation, and I don't want to have to maintain either copy-pasted docs pages or come up with equivalent but different tutorial content.

So yeah, I'm still struggling to figure out what the RTK tutorials should explain, and how they should explain it.

[RyanAtViceSoftware]

@markerikson there is no way that someone shouldn't understand how redux works before using RTK. I don't even understand how that would work. I think

assume the reader already knows what Redux is, and focus on the differences

Is the right idea. But I'd probably rephrase it to be more

assume the reader already knows what Redux is, and focus on the pain points and how RTK alleviates them

at the end of the day, all RTK is is a boilerplate plate reducing tool for doing idiomatic redux.

[FredericLatour]

@RyanAtViceSoftware I completely disagree with your comment (with all due respect). The redux/flux concepts are not tied to a particular syntax/approach. I can't see why you could not learn Redux from the ground up using a major syntax/structure revamping without having to care with the former approach. Considering RTK as a boilerplate is a mental shift for those already using Redux.

Now I completely understand the maintenance burden that @markerikson has to deal with. At the very least, he will need a guide using the new syntax from the ground up if he wants to attract people more largely. And this is what he is doing.

[RyanAtViceSoftware]

@FredericLatour no need to worry about disagreeing that's the point of these discussions is to find the right idea by debating the merits of the various options. In that spirit I'd have to vote against your recommendation. Thinking you can have developers be successful with RTK on a real project without them being intimately familiar with not only the basic concepts of redux but also the idiomatic approaches is a recipe for failure and big delays late in your project. Things that RTK obfuscates:

1. actions types, action creators and reducers
2. idiomatic async pattern
3. immutable updates

The moment that their is a need to get closer to the metal with Redux everything will come crashing down if your devs don't understand these concepts.

Additionally, if users don't understand the boilerplate involved then what's the motivation for using RTK in the first place? It's simply a tool that encourages best practices while reducing boilerplate.

My vote is that the goal of this project needs to be a tool that reduces boilerplate while allowing folks to follow best practices. Not as a tool that encourages folks to use Redux without having the read the manual first.

[FredericLatour]

@RyanAtViceSoftware You can have a clear understanding of the overall Redux concepts without having even started to learn the implementation details.

The moment that their is a need to get closer to the metal with Redux everything will come crashing down if your devs don't understand these concepts.

You can come up with this remark with mostly any changes/improvement in the computing area. Abstracting complexity away is always a balance.

Additionally, if users don't understand the boilerplate involved then what's the motivation for using RTK in the first place? It's simply a tool that encourages best practices while reducing boilerplate.

The motivation of using RTK would be to use a state management solution with as less boilerplate as possible. If RTK is a tool that encourages best practices, why should I even care with the boilerplate it removes.

It's difficult to counter-argue any better because obviously, I don't know much about the implementation details of redux vs rtk and can't say for sure if it's a vital information to know the older way. If what you say is true anyway, maybe Redux is just not for me after all.

I'm not completely set on everything but in most cases, I believe I will be happy to handle state (with swr or react-query) at the component/view level. My need for an application level cache is quite light and I guess that react context API or easy-peasy (that has the advantage to expose a redux store in case any extension would be necessary) could be just enough.

[RyanAtViceSoftware]

@FredericLatour if you can't clearly articulate the benefits of redux you are leveraging then IMHO you probably shouldn't be using it.

Dan goes through this in this excellent blog post: https://medium.com/@dan_abramov/you-might-not-need-redux-be46360cf367

The motivation of using RTK would be to use a state management solution with as less boilerplate as possible. If RTK is a tool that encourages best practices, why should I even care with the boilerplate it removes.

RTK isn't a state management solution. It's a set of utilities for working with Redux. If you don't want to learn redux, then you shouldn't use redux or RTK.