[Docs] Add a "Migration" Usage Guide page

[todortotev]

So, first of all, thank you guys for the magnificent work. As a fairly new user to Redux I'm really thankful for the job you have done, cause with the toolkit the usage of Redux is way easier and most importantly - very, very enjoyable.

I have seen acemark all round the web promoting the toolkit, which is awesome, but I think most people haven't realized yet what are the benefits of RTK, other will say it's new and not mature yet, but I am quite certain RTK is here to stay and the adoption will certainly come.

I think, that the current documentation is quite well explained (except the Middlewares part), but I think the missing part of it is "Migration". We have a "How to convert a "plain React" app to use Redux" chapter so I think having a similar approach for migrating would be useful.

I think in 2020, the era of "tutorials galore" RTK will benefit if it has it's own "Migrate your existing codebase to RTK" with code samples because people are usually too lazy to figure out for themself what has to be done. (I know we already have the Pre and After RTK code, but that's more like an explanation of the usage of RTK).

There's a guy who made a lovely video, comparing the previous and the current code you have to write, using RTK Source. Code

One could say - you should know the foundations before using abstractions over current implementation, but what would the situation be if Redux actually was introduced with RTK?

We would never get the "too boilerplate-ey" discussion, "too hard for starters" arguments and related stuff.

P.S: I think many of you could say this is childish, but another thing that would be really useful is an official discord/slack channel where people using Redux/RTK could discuss and help each other. I think that definitely will help to increase the adoption rate.

[markerikson]

Yeah, the migration aspect ties into #371 . Right now, the RTK tutorials basically are migration guides. But yes, a specific "Migration" page under the "Usage" section would be good.

Not sure why you'd say that there might be concerns that RTK is "not mature". It's entirely mature, which is why it's past 1.0 and we officially recommend using it.

We do already have an official Discord channel: #redux in Reactiflux, which is specifially linked in the docs at https://redux-toolkit.js.org/introduction/quick-start#help-and-discussion .

Finally, I'm specifically working on a new "Quick Start" tutorial for the Redux core docs, which will specifically teach RTK as the default way to write Redux code for people who have never used Redux before.

[todortotev]

@markerikson About the concerns being mature enough - I completely agree with your thought, but I have read some people asserting that "we should wait to see if it works" out. I personally don't think there is anything to wait about, cause you have done excellent work and the usage is very enjoyable. Of course, we cannot please everyone's wishes but just wanted to point out what I have seen so far.

If you need any help with any related stuff, let me know. Would love to lend a hand.

[markerikson]

Erm. Where are those sorts of comments happening? Got any links?

If you look at the RTK APIs, they're generally pretty small and straightforward. The TS types make the files quite a bit bigger and complex, but the resulting JS source isn't all that long. Example:

https://unpkg.com/browse/@reduxjs/[email protected]/dist/redux-toolkit.esm.js

function createReducer(initialState, mapOrBuilderCallback) {
  var actionsMap = typeof mapOrBuilderCallback === 'function' ? executeReducerBuilderCallback(mapOrBuilderCallback) : mapOrBuilderCallback;
  return function (state, action) {
    if (state === void 0) {
      state = initialState;
    }

    var caseReducer = actionsMap[action.type];

    if (caseReducer) {
      if (isDraft(state)) {
        var draft = state; // We can aassume this is already a draft

        return caseReducer(draft, action) || state;
      } else {
        return createNextState(state, function (draft) {
          return caseReducer(draft, action);
        });
      }
    }

    return state;
  };
}

Not a lot of complexity there to be concerned about :)

[todortotev]

@markerikson Apologies if I offended you somehow, but in my personal opinion everything about RTK is great and anyone who says otherwise is plain wrong. I am really thankful for the job you have done. The API is super simple and easy to use. The thunk API additions from March are incredible.

I spent the last hour trying to find the content I described earlier, but with no success. I remember it was a comment under a SO or Reddit topic, but I fail to find where it was. I can assure you I'm not pulling it out of my ass just for the sake of arguing. Later in the day, I'll try to dig it up again and if I find it, I'll add it to this post.

Last, but not least - I'm really willing to help so if you need a hand, let me know with what I could contribute.

Thank you for your time.

Edit 1:
Offtopic:
I kept trying to find it, but another article I come across is this which states

The advantages of the Redux Toolkit come at a price. You get an additional dependency through the Redux Toolkit and indirectly some dependencies through the libraries provided by the toolkit

Which was proved wrong in many other places we have seen this type of argument.

Edit 2:
Finally found it, but it seems like the OP has edited his post, thankfully I could find the "archive" so you could see it.

Fortunately, his post is edited and no longer includes this nonsense.

[markerikson]

Haha, no worries, wasn't upset at you :) Was just curious what comments you were referring to.

For this topic specifically, you could definitely help by working on adding a new "Migration" page in the usage guide section, which takes the kinds of explanations that are currently in the "Basic" and "Intermediate" tutorials, and turns them into a general guide format.

Also have lots of work on the Redux core and React-Redux docs that I need help with as well:

reduxjs/redux#3592

https://github.com/reduxjs/react-redux/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Adocs

[markerikson]

We added this to the core docs a while back, and I've copied this into the RTK docs as well.