Mark createStore as deprecated, and add legacy_createStore alias

[markerikson]

This PR marks the createStore API as deprecated, and adds a new legacy_createStore API as an alias without the deprecation notice.

• Updated createStore's doc description to mark it as @deprecated,
  so that it shows up with a visual strikethrough in editors.
• Added new descriptive text to createStore to encourage users to
  migrate to RTK, and pointing to the "RTK is Redux Today" docs page
• Rewrote TS typedefs for createStore to define it as a function with
  overloads, rather than a varible, to get correct docs tooltips when
  hovering over variable usages
• Added legacy_createStore API as an alias without the deprecation

Goal

Redux Toolkit (the @reduxjs/toolkit package) is the right way for Redux users to write Redux code today:

https://redux.js.org/introduction/why-rtk-is-redux-today

Unfortunately, many tutorials are still showing legacy "hand-written" Redux patterns, which result in a much worse experience for users. New learners going through a bootcamp or an outdated Udemy course just follow the examples they're being shown, don't know that RTK is the better and recommended approach, and don't even think to look at our docs.

Given that, the goal of this PR is to provide them with a visual indicator in their editor, like createStore . When users hover over the createStore import or function call, the doc tooltip recommends using configureStore from RTK instead, and points them to that docs page. We hope that new learners will see the strikethrough, read the tooltip, read the docs page, learn about RTK, and begin using it.

To be extremely clear:

WE ARE NOT GOING TO ACTUALLY REMOVE THE createStore API, AND ALL YOUR EXISTING CODE WILL STILL CONTINUE TO WORK AS-IS!

We are just marking createStore as "deprecated":

"the discouragement of use of some feature or practice, typically because it has been superseded or is no longer considered efficient or safe, without completely removing it or prohibiting its use"

Rationale

• RTK provides a vastly improved Redux usage experience, with APIs that simplify standard usage patterns and eliminate common bugs like accidental mutations
• We've had suggestions to merge all of RTK into the redux core package, or fully deprecate the entire redux package and rename it to @reduxjs/core. Unfortunately, those bring up too many complexities:
  • We already had a package rename from redux-starter-kit to @reduxjs/toolkit, and all of our docs and tutorials have pointed to it for the last three years. I don't want to put users through another whiplash package transition for no real benefit
  • Merging or rearranging our packages would effectively require merging all of the Redux repos into a single monorepo. That would require hundreds of hours of effort from us maintainers, including needing to somehow merge all of our docs sites together. We don't have the time to do that.
• I don't want to add runtime warnings that would be really annoying

So, this is the minimum possible approach we can take to reach out to users who otherwise would never know that they are following outdated patterns, while avoiding breaking running user code or having to completely rewrite our package and repo structure.

Results

When a user imports createStore in their editor, they will see a visual strikethrough. Hovering over it will show a doc tooltip that encourages them to use configureStore from RTK, and points to an explanatory docs page:

Again, no broken code, and no runtime warnings.

If users do not want to see that strikethrough, they have three options:

• Follow our suggestion to switch over to Redux Toolkit and configureStore
• Do nothing. It's just a visual strikethrough, and it doesn't affect how your code behaves. Ignore it.
• Switch to using the legacy_createStore API that is now exported, which is the exact same function but with no @deprecation tag. The simplest option is to do an aliased import rename:

Plan

I intend to release this as Redux 4.2.0 as soon as this is merged.

More Details

See the extensive additional discussion in #4325 .

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit fdf5956:

Sandbox	Source
Vanilla	Configuration
Vanilla Typescript	Configuration

[github-actions]

Size Change: +1.32 kB (4%)

Total Size: 28.4 kB

Filename	Size	Change
./dist/redux.js	8.41 kB	+431 B (5%)	🔍
./dist/redux.min.js	1.67 kB	+18 B (1%)
./es/redux.js	8.29 kB	+431 B (5%)	🔍
./es/redux.mjs	1.58 kB	+12 B (0%)
./lib/redux.js	8.44 kB	+432 B (5%)	🔍

_{compressed-size-action}

[budarin]

I'm not agree with the decision -we will never use redux toolkit because of redundant dependencies

you need to leave createStore for those who know what to do and how to do it, and let beginners use the redux toolkit

[phryneas]

@budarin you did read the deprecation note that said that it will not go away, right?

[markerikson]

@budarin we made the release, and we're not changing it at this point.

That said, I am genuinely curious on what your reasons are to avoid using RTK. Can you give some more details on why?

[budarin]

@markerikson

because we want to use a unified approach in changing data in redux and in React - immutable.
mutating data in redux toolkit will form a bad habit of mutating data in React code, which will lead to errors and will confuse novices

we also are not satisfied with another dependency that increases the size of the application

I'm not agree with renaming createStore to legacy - it must be stay createStore

[markerikson]

@budarin : as I've said repeatedly in the other thread: it's our job as maintainers to make the decisions that we think will have the best results for our users, and we made this decision because we think it will help the most people.

As for understanding state update syntax and bundle size, reasons for wanting people to use Immer are listed here:

https://redux-toolkit.js.org/usage/immer-reducers#why-immer-is-built-in

[budarin]

@markerikson

I completely agree with you about using Immer in RTK, but this is a different level of using Redux - I think that it is not necessary to decriminalize those who prefer to use Redux Core and leave them the normal name of the createStore method

[markerikson]

@budarin : this feels really hyperbolic tbh :(

We most definitely did not "criminalize" anything. We are intentionally keeping all of our users' code running as-is! We didn't even add a runtime warning. In fact, the release notes explicitly say one of the options is "ignore this entirely, it doesn't affect how your code runs".

All of we've done is add a visual marker and a descriptive note saying "we recommend using RTK".

At this point there's nothing else worth debating here, because we've made the change, are not undoing it, and I'm getting tired of having our plainly stated reasoning ignored.