Feedback for documentation

[whoisryosuke]

Greetings all! I recently tried Redux Toolkit in a project and had a tough time wrapping my head around it. I felt like the docs were lacking some key features that would help intermediate to advanced users integrate the Redux Toolkit paradigm into their app and state architecture.

1. Immer is hard to use and not documented well

Immer is great. It's what allows state mutation, which makes things much easier. BUT. I found it incredibly frustrating to do simple actions that seemed like they should just "work" - particularly in this "mutation" environment.

Needs to be more of a bridge between immer docs and Toolkit, like some quick examples of common workflows using immer in complex ways (like deeply nested arrays and objects).

Here's an example:

I kept having an issue updating my state and getting an error Cannot update property of undefined.

Really? Which prop? Lemme log this state out...oh wait it's a subscription so you can't see it. Ok, lets check Redux Devtools state -- yep, my data structure matches my object selection (even with dynamic properties). So what's happening here? Hard to tell, Immer does a bit of magic under the hood.

Or better yet, here's a great example. We push a new array to a nested object property:

state.groups[action.payload.group].items.push(action.payload.item);

Cannot update undefined.

Ok cool, using an array without it existing, I get it...lets try....

This! Aha...right?

state.groups[action.payload.group].items = [...state.groups[action.payload.group].items, action.payload.item]);

Cannot spread undefined.

And don't get me started on this not working 🤷🏻‍♂️

...(state.groups?.[http://action.payload.group]?.items ?? [])

I tried to find a similar example in the Redux Toolkit docs and couldn't find one. I popped over quickly to the Immer docs and gave up eventually.

Maybe it's me? But I find when I use Context Providers and setState, I don't have this kind of issue.

2. How do you log out state from mutations?

For example. If I need to know what's up with my context at any point, I just log it out of my provider. It lets me know what's occurring each render, or even during mutation methods.

Need to know Redux state during mutation? Good luck. I was informed by Mark that you can use a method on the state to get the current state. Is this in the docs? Is there an example of debugging actions?

3. The Toolkit documentation is too much Redux

I understand that a knowledge of Redux is required to use Toolkit, but the way the documentation is framed where it does a side by side comparison of traditional Redux to Toolkit gets confusing -- I can imagine moreso for someone with neither knowledge. It was hard for me to clearly distinguish where Redux and Toolkit started sometimes. Maybe it's the one-page nature of the docs?

And oddly enough, the docs feel short? I went though them fast, but feeling unprepared. If anything it definitely says that there's plenty room for more examples.

4. Better Typescript support?

Typescript was another area that it felt like the docs handled it odd. I understood most of it, but there were areas that seem missing (or maybe my projects TS config) -- like typing Actions and their payload.

For reference, here was the project I was working on with Redux Toolkit.

I hope this feedback helps! Let me know if you need any more detail on anything 👍

[markerikson]

Hey, thanks for writing this!

I'll try to read over it in more detail later, but yeah, point 3 is really a big struggle atm. Per #371, the RTK tutorials are currently written assuming you know the basics of Redux already, and want to migrate to RTK. It's really hard to know just how much info should be in which docs site, and in fact atm the best resources for learning RTK are actually in the Redux core docs.

Per the Immer usage aspect: agreed that there's some nuances we could cover better, but to a certain extent you can think of it as normal JS usage. You can't magically spread a JS array that doesn't exist yet in plain JS, so you can't do that in Immer either. You have to check to see if that array exists, and provide a fallback approach if it doesn't.

[markerikson]

FYI, I've just published some major updates to the RTK docs:

• Deleted the existing RTK tutorials
• Added brief "Quick Start" tutorials for RTK + JS and TS
• Added a "Tutorials Overview" page that points to the Redux core docs as the main RTK tutorials

New pages:

• https://redux-toolkit.js.org/tutorials/overview
• https://redux-toolkit.js.org/tutorials/quick-start
• https://redux-toolkit.js.org/tutorials/typescript

I did add a link from the "Tutorials Overview" page to the legacy "Basic/Intermediate/Advanced" tutorial Markdown files in the repo as they existed before I deleted them, so the content is still accessible.

I do also plan to add a "Writing Reducers with Immer" page in the near future.

If you get a chance, I'd appreciate it if you could look over the new pages and see if they at least partly address some of the points you've raised here.

[markerikson]

I also added a new Writing Reducers with Immer page. Does that answer the rest of the questions you had?

[markerikson]

I think the recent docs change sufficiently address the concerns raised here. If you do have any more concerns about the docs content, please feel free to comment and let us know!