Mark `createStore` as deprecated

[markerikson]

We don't want anyone using the core createStore method directly in their apps today. We want them using configureStore from RTK instead.

We should tag createStore as @deprecated on both the 4.x and 5.x branches, and do another 4.x release.

edit

After a bunch of discussion, it's become clear that a lot of people aren't familiar with what RTK actually is, or what the technical differences are between the core createStore API and RTK's configureStore. Let me provide some background resources.

First, I had a chance to do a livestream with Jason Lengstorf where we explained what people disliked about Redux historically, and how RTK was created to solve those issues. We then built a small example app with RTK+TS:

• https://www.youtube.com/watch?v=9zySeP5vH9c

Next, the "Modern Redux with RTK" tutorial page shows the differences in usage between "vanilla" Redux and RTK for things like store setup and writing reducers:

• https://redux.js.org/tutorials/fundamentals/part-8-modern-redux

And for a lot of additional background on why RTK was created and how it evolved, see my "Redux Toolkit 1.0" announcement post.

For the actual technical differences, Lenz had a very good explanation on Twitter today:

In short: configureStore calls applyMiddleware and combineReducers for you and sets up the devtools, all while having a more "sane" api than createStore. For that reason alone, it should be a technical successor of createStore.
In dev, it also adds two additional middlewares per default (middleware added by configureStore is freely configurable): One checks for accidental store mutations, both between renders as well as inside the reducer.
That means it eliminates a whole class of bugs that only surface in "UI sometimes not rerendering" or things "being out of order some time later" - hard and frustrating to find. The other warns if you put non-(de)serializable values like classes into the store.
Not only do these make a lot of problems with the devtools or libraries like redux-persist, even something as simple as a Date instance can mutate itself out of the normal Redux data flow.
So, even if you were not to use the rest of RTK (which still makes you life a lot easier beyond that, removing the need for action types and manual immutable logic), it would still be a good idea to install RTK and use only configureStore out of it, instead of createStore.

There's some comparisons of the before and after setup here:

• https://redux.js.org/usage/configuring-your-store
• https://redux.js.org/tutorials/fundamentals/part-8-modern-redux#store-setup

[phryneas]

Just a first wording suggestion:

 * @deprecated 
 * In most cases, you should be using the `configureStore` method
 * of the `@reduxjs/toolkit` package instead of calling `createStore` directly.
 * As `configureStore` is calling `createStore` internally, it will not be going
 * away, and your code will continue working but if you are just starting a 
 * new project, please be aware that we recommend using the official 
 * Redux Toolkit for any newly written Redux code since 2019. 
 * 
 * You should not be using this in a new project or when following a tutorial, 
 * except for learning purposes.

[timdorr]

Hmm, I don't really think this is a good idea for the core library. It's not truly deprecated; we're not getting rid of the API. This is giving the false impression this API is going away.

Also, I don't really think it's our job to tell users how to use the library. If they want to do dumb, bad, illogical things with it, that's up to them. As long as we're pointing them in the better direction of RTK everywhere else, that's what we should focus on.

[phryneas]

The problem is that this is essentially the last resort how we can "contact" users that either never revisited the documentation or are following outdated tutorials.

Honestly, I'm less concerned about users that never revisited the documentation: it's on them.

But I deeply care for users that are learning from an outdated tutorial - or from e.g. a bootcamp where the teacher is still teaching vanilla Redux because they never revisited the documentation. (And there is even a bunch of teachers who should know better and still teach wrong stuff because they don't want to rework their course as long as it brings in money - and those courses keep getting good ratings because the users themselves don't know better. It doesn't help that one of those courses is the highest-rated "Redux" course on udemy)

They are not "at fault" here, but are being steered in a very wrong direction and will be deeply hurt as a result. And there is no other way to contact them than a "strikethrough" in the editor at this point. We will not be able to reach these users by an extra bright-red warning on the homepage or 10 new points in the style guide.
But to keep Redux relevant, we have to reach them.

I would be very fine to add another non-deprecated createStore__iKnow or something for people that really want to use createStore and don't want to see the @deprecated message.
But I am very convinced that we need to step up to this "next level of communication".

[timdorr]

Is it really a problem that people are using Redux directly without RTK? People do dumb stuff with other libraries. Heck, I do dumb stuff with other libraries all the time. It's not really up to the library to judge how I use it.

This is also an issue that naturally ages out over time. As those outdated tutorials get more and more outdated, they get seen less and less. There are plenty of old React tutorials still suggesting React.createClass() usage, but the React team hasn't put a warning on that API. Just because it's no longer the best way to use the library doesn't mean it needs to get marked as deprecated.

At the very least, I'm against this because it hijacks the usage of @deprecated in the code. What happens when we want to actually deprecate things? Now it's confusing to know which is which.

[phryneas]

I spend time in Discord every single day. I see people struggling hours and days to wrap their head around concepts they don't need and having actual frustration of pain they would not have to have.
And honestly, telling someone about that afterwards is not a nice conversation to have.

In the last two years I have observed hundreds on Discord, another few hundred on Twitter and yet another few hundred on StackOverflow. And those are only the places I am looking. Those are the places where knowledge of Redux Toolkit already has spread and yet, still people are going a painful way. Not because they have a way of choosing, but because they do not know better.

One of too many examples:
Stephen Grider's horribly outdated "Modern React with Redux Training Course" on udemy had at this point 260.000 people taking it, with 75.500 mostly positive reviews averaging at 4.7 stars.
Even if the next 10.000 users would give it 1 star, it would stick around for another year without losing it's top spot.
And people are not giving it one star, because he explains Redux-Form (which is deprecated on the homepage of Redux-Form, on the github page and in the npm README since 2019) nicely. They think they learn relevant information. They don't.
And to add insult to injury the course author regularly does minor changes to the course so it is "recently updated" and more people will fall for it. He knows about Redux Toolkit for years now and has chosen to ignore us trying to contact him.

People not only buy into this shit, they also fall victim to the sunken cost fallacy. They already have put money and lots of time into this course, so they will keep following what they learned there. At that point I can tell them that I am a Redux maintainer and that they learn outdated stuff and a good chunk of these people goes on for days, weeks and even multiple months until they come around to try RTK. (And then almost nobody goes back. I think I've seen three people go back so far to vanilla Redux, out of all those hundreds.)

I have spent the last few years telling every single person that they are learning from outdated sources. I spend at least half an hour each day (realistically: probably more around two hours) going through twitter, StackOverflow and Discord telling people. Thinking that this "naturally ages out over time" at this point is naive. I have tried. Mark does too.
It will not happen within the next 2, 3 or 4 years.
The current situation actively damages the reputation of Redux because to this day people tell the story that Redux has a lot of unneccessary boilerplate and that they would rather chop their arm off than take another stab at it.

We can do more to change that.

Adding a deprecation warning is the least we can do. Also, I do not agree that we are hijacking the intended @deprecated usage. @deprecated does not mean that something will disappear anytime soon. Only that it is outdated and not recommended. In the spritit of "not breaking the web", deprecated browser features sometimes stay around for decades after their deprecation.
A deprecation tag alone says nothing unless the person seeing it also reads the deprecation message attached to it. We can be very clear in our messaging there that createStore is a fine function to use if you need very low level control and want to do things by hand, but that we are nowadays recommending alternatives that are better suited in almost all cases.

But newbies would at least get an indicator that they are wasting their time.

[markerikson]

I'm inclined to agree with Lenz here.

This doesn't prevent anyone from using createStore. All existing and new code will work fine.

But we really don't want people using it directly today.

This would at least give a visual indication to users in their editors that we encourage use of RTK instead. And frankly, as far as I can tell a majority of learners are coming into Redux without seeing that RTK exists, even today.

Ideally, users would:

• See the createStore deprecation message
• Learn that RTK exists
• Go read up on it and install it
• Also see that other APIs like createSlice exist and realize they can use those

[Brianzchen]

Hi, I'm chiming in because why not. I've used redux since 2016, I saw Mark posting about rtk last year or something and I've opted to not read it beyond the homepage cause it didn't interest me. I don't consider myself a newbie or a complete dumbass I hope.

But that doesn't mean using createStore is wrong. I like to create my own store and tooling around it. Sure it's not standard but I build hooks with react and custom middleware that fulfils my usecase well. Redux was always a simple core library and essentially telling everyone that if you want to use it directly means you're wrong then that just isn't right.

Yes redux has initial boilerplate cost and maybe it's complicated for new Devs but please, deprecation as a means to encourage rtk is not the correct move, that's not real deprecation unless you really plan to remove createStore some day. The right tool should be used for the job. Update the jsdocs to tell me to use rtk if I want an easier life but don't deprecate the API just because you don't like people using it.

Honestly it makes me sad how opinionated the JS ecosystem has become.

[phryneas]

If this is about the word "deprecation", we can happily also just add a runtime console warning that is visible in dev on every app start and can be disabled by setting global._IReallyWantToUseVanillaRedux.

Or we deprecate it with intent of future removal and add a __internal_createStore function in the next version.
Tbh., I'd be fine with that, too. I just don't think it's necessary.

Let's be real: Every other way of telling the users will be more disruptive than a strikethrough in the editor.

@Brianzchen I hope you don't take it personal, but you have just now given a prime example why that warning should be there:

• At the point you have heard the first time about RTK, it has already been the officially recommended approach for any newly written Redux code for two years.
• When you heard about it, you didn't check it out much further.
• You somehow have the impression that configureStore would lock you in and not allow you to use custom middleware.
• You also have the impression that this is just about initial boilerplate cost and not a massive improvement in day-to-day use and reduction of potential bugs.

Also, those subscribed to this issue might have noticed that there was one more comment here that was deleted by the author again. The author expressed anger because now Redux would become "all about React". Clearly the messaging that the RTK core has nothing to do with React and should be used by everyone independently of Framework did not get through there in the past three years.

Taking a step back, frankly Redux is probably one of the only libraries I can think of that did not introduce a breaking change to make life for their users easier because an old core api was replaced with a newer, more user-friendly one.

Thinking about libraries I am using in the ecosystem:

• Apollo has done so in what feels like almost every major version.
• Material UI has breaking changes left and right. (As most UI libs in general have regularly.)
• React Router had really breaking changes, because their approach shifted.
• React itself has had big paradigm shifts and they did officially declare mixins as harmful.
• RxJs had massive api/usage changes as well.

Those are just what comes to mind.

Maintaining a library is also about finding better ways for our users to use it. About giving them better ergonomics.

This is nothing to be fearful of. Yes, the old stuff still works. That doesn't mean there isn't a better way of doing it and maybe we should help our users to find the right tools instead of going "yeah there are docs here, if they don't read them it's their own fault".

[ematipico]

I really like that you authors care about the users, and I share the same sentiment.

There's also the fact that if people still rely on old documentation or don't care about updating themselves, it means that they don't care about the software they intend to use, or to be more specific, they care only about the software they intend to use to begin with, and redux might not be among them.

Software changes and it's harsh, sometimes. If the change brings positive outcome in the long run, so be it.

I think this is a good move and you should go ahead. RTK is more newbie friendly and lowers the barrier to adopt redux.

It could be called "archived" if deprecated is not the right wording. Or a warning might work too.

[zdhr]

The way I understand it is that you want to deprecate entry point to the library? So you want to deprecate the library itself?

What will RTK use, if createStore is deprecated? Some internal stuff? What should other "toolkit" libraries use?
Or will you just merge redux & RTK into some big blob with all of RTK's dependencies and without the possibility of (normally) using vanilla redux by itself?

What if I don't want to use RTK? I looked at it long and hard and decided I don't want to use it for multiple reasons. I don't think I'm the only one in the entire world.

If your concern is for newbies, then update documentation. Maybe add message to install log.
But please no deprecation and no annoying warnings in runtime in console with flags we will have to set to get rid of them.

[phryneas]

@zdhr have you read the suggested deprecation message above?

As configureStore is calling createStore internally, it will not be going away, and your code will continue working

Using createStore directly would get a deprecation message, since that is not the recommended approach to use Redux, by the Redux style guide and documentation, for over three years now. You can however always choose to just ignore the deprecation message. As the message states, createStore will not go away - we as library authors are just of the opinion that you should not be using it, since there are better alternatives.

If your concern is for newbies, then update documentation.

That has obviously no effect. Best example is your comment itself: We have done so for years and it seems you didn't notice, or you would not suggest this.

Maybe add message to install log.

That will not be noticed by anyone.

[mattpocock]

The fact that you're considering this approach gives me faith in the library as a whole going forward. Using @deprecated is essential because it provides VSCode users with a strikethrough on the createStore() func. It may 'feel' imprecise, but it's essential to have the visual indicator to trigger folks to look at the docs. If JSDoc/VSCode supported a @strikethrough tag, this would be preferred - but it doesn't.

I'm sure you'll do this too - but I'd recommend adding a long-form section to the docs with why this approach was taken and link it from the comment.

[markerikson]

Yep. That's exactly the idea here.

As seen in this thread and the responses to my tweet about this, there are definitely plenty of people who are still using vanilla/legacy Redux in existing apps today. We are not going to break anyone's code, even if/when we release a new redux major version. Period.

But...

We explicitly do not want any new learners adopting those practices today. And unfortunately, many learners never even think to look at our docs. Given the prevalence of all these horribly outdated courses and tutorials even today, adding a @deprecated flag is the only way we have to communicate this warning to people who otherwise will likely never hear of RTK in the first place.

[markerikson]

For the record, we did previously discuss the idea of moving the existing APIs into a @reduxjs/core package and moving what was then "Redux Starter Kit" into the redux package. But, that was all the way back in late 2018:

#3321: Discussion: Consider expanding the Redux core

I'd really still prefer to not go that direction today. We already did one big package rename from redux-starter-kit to @reduxjs/toolkit. We have a ton of docs and templates that refer to @reduxjs/toolkit. Additionally, shuffling packages would most likely require trying to merge all the separate Redux projects into a single monorepo, which in turn would lead to having to completely redo all the docs sites. (I've very briefly considered trying to have a single consolidated docs site so all the material is in one place, but the need to have a monorepo to make that work is basically a showstopper - that's just too much time and effort.)

Adding a single visible indicator to one API method is the lightest action we can take without requiring prohibitive amounts of effort on the part of either maintainers or users.

[gkatsanos]

I'm not sure if this is a useful comment, I clicked around the first tutorial presented in the docs, and the first example I landed on was using createStore. https://github.com/reduxjs/redux#basic-example . The example right after of course offers the simplicity of toolkit, but I think it'd be quite useful to make that more prominent in the docs. The same deprecation note as a highlight in the docs would go very far.