[Docs] Rework "Usage with TypeScript" page

The current “Usage with TypeScript” page has multiple issues, and we should rework it. When that page was written in 2018-ish, I still didn’t know TS yet. So, I couldn’t offer any meaningful feedback on the contents. Now that I actually have a decent TS background, I can see that there’s problems:

• The page shows patterns like hand-written action creators and creating unions of action types, which are both patterns we now discourage ( https://phryneas.de/redux-typescript-no-discriminating-union )
• It should show RTK as the default approach first, and hand-writing individual pieces as a fallback
• We have mismatched information between the three different TS usage pages in our docs (Redux core, React-Redux, and RTK), and we should harmonize them to have the same advice in all places
• We should better explain things like extracting the custom store Dispatch type to allow correctly dispatching thunks. (This is by far one of the most common questions I see lately, and I’m not sure how to easily address it through code, so we need to highlight the importance of this for thunk usage.)
• Per https://github.com/reduxjs/redux/issues/3690#issuecomment-790626067 , we don’t mention the Reducer type
• Along with all that, the CodeSandbox example link is apparently busted anyway.

and I’m sure there’s some other improvements we could make as well.

The recently updated “TS Quick Start” page in the RTK docs would be a good starting point for “here’s what to do”:

https://redux-toolkit.js.org/tutorials/typescript

and then we can give more details for specific situations after that.

[phryneas]

Hmm.

Let’s get the augmentation thing out of the way first.

I think for state it’s amazing if you look at it in separation. And enormously dangerous if you look at it in real life. If people start using that in libraries or library-style parts of monorepos, there is a good chance that these augmented types make it into projects where they don’t belong and state structure would seriously become weird at that point.

Pretty much the same goes with augmenting the Dispatch type. While I would totally love to see that augmented dispatch type in the redux-thunk types get released and would enthusiastically use it in my own projects, it is a fact that that type augmentation would always be in place - no matter if the middleware is only installed (e.g. as a dependency of RTK) or actually instantiated (it can be disabled after all).

Getting back from that to the actual concern of rewriting the “static typing” page: I’m not sure we should actually add any new information on that. People seem to skip all introduction and start wildly copy-pasting code. No matter how many warnings we attach that this is only meant for legacy projects and that we really recommend all TypeScript projects to use RTK as that is designed to work with TS: people will just start writing their JS code they learned from some crappy udemy course and adding types into it. Then they will get frustrated, start googling around wildly (still discarding the docs) and start using approaches like typesafe-actions, which were a great things back in 2018 but which I would not really recommend as the first choice nowadays.

My personal approach would honestly be to replace the whole “static typing” page with a section that emphazises that we really really really want people to use RTK. And then add a link to the github archive of that page so that people who need TS in a legacy project still can read up on it. But really just in the raw markdown form, to really empathize that this is part of the history of Redux and not how we suggest it to be done nowadays.

This might seem a bit drastic but I’m honestly getting frustrated by the amount of people ignoring all the blinking signs and doing themselves the disservice of learning only vanilla redux.

[markerikson]

@ricokahler I really do want to drop the “union of action types” thing. Per Lenz’s article, it doesn’t have any real benefit, and it’s even more useless when you’re writing code with RTK.

Agreed that we should rename the React-Redux TS page. I originally had thoughts of getting some Flow examples in there, but Flow is dead at this point.

Also agreed that we really need to emphasize how to type dispatch for use with thunks correctly.

Not sure I’m keen on the idea of augmented types, at least for now. I think Lenz has some opinions on that, though.

Paging @phryneas and @msutkowski for their thoughts here.

Tell you what, why don’t you go ahead and try to put up a PR so we’ve got some concrete changes for discussion.