Discussion: Debate changing Redux packages to merge "Redux" and "RTK", again

[markerikson]

THIS IS STILL AN ALMOST ENTIRELY HYPOTHETICAL DISCUSSION PLEASE DO NOT PANIC

Back in late 2018, we had a thread debating the idea of "should we move this new 'Redux Starter Kit' thing into the redux core package?":

• Discussion: consider expanding the Redux core #3321

The conclusion out of that thread was "no, we shouldn't, because there's too much ecosystem inertia and we don't want to disturb things".

So, as of today, we still have a redux core package with the primitive APIs (createStore, combineReducers), and a @reduxjs/toolkit package that is our recommended set of APIs for using Redux today (configureStore wrapping createStore, createSlice generating action creators and using Immer for immutable updates, etc).

Over the last couple days we've been debating the idea of marking createStore as "deprecated", with a specific goal of driving awareness of RTK for learners who are today learning legacy Redux patterns from old tutorials, courses that were never updated, and bootcamps:

• Mark createStore as deprecated #4325
• https://twitter.com/acemarke/status/1513714595764051972

As part of those discussions, the question of "well why don't you just merge @reduxjs/toolkit into redux?" has come up again. So, I wanted to open up the floor to re-litigate that particular discussion, in 2022, with what we know today about how RTK has been adopted and received.

And for some examples of how people view RTK today, see:

• https://www.reddit.com/r/reactjs/comments/px6kxy/redux_toolkit_is_awesome/

Background

For additional background on how RTK was created in the first place, please see these posts and threads:

• Redux Toolkit 1.0: my extensive post detailing the original problems RTK was designed to solve, and its development history
• Redux issue #2295: Request for Discussion: Redux "boilerplate", learning curve, abstraction, and opinionatedness
  • Dan's wishlist for an opinionated layer on top of Redux
• Redux issue #2259: RFC: Redux Starter Kit
• RTK issue #82: My Vision for Redux Starter Kit

I'll particularly quote key sections of the "Vision" post:

Objectives

Per the README, other specific inspirations are Create-React-App and Apollo-Boost. Both are packages that offer opinionated defaults and abstractions over a more complex and configurable set of tools, with the goal of providing an easy way to get started and be meaningfully productive without needing to know all the details or make complicated decisions up front. At the same time, they don't lock you in to only using the "default" options. They're useful for new learners who don't know all the options available or what the "right" choices are, but also for experienced devs who just want a simpler tool without going through all the setup every time.

I want Redux Starter Kit to be the same kind of thing, for Redux.

Speed Up Getting Started

... I want to give people a way to get working Redux running as fast as possible.

Simplify Common Use Cases and Remove Boilerplate

I want to remove as many potential pain points from the equation as possible:

• Reduce the amount of actual physical characters that need to be typed wherever possible
• Provide functions that do some of the most obvious things you'd normally do by hand
• Look at how people are using Redux and want to use Redux, and offer "official" solutions for what they're doing already

Opinionated Defaults for Best Practices

Redux Toolkit should set things up in ways that guide the user towards the right approach, and automatically prevent or detect+warn about common mistakes wherever possible.

No Lock-In / Add It Incrementally

If someone starts an app using Redux Toolkit, I don't want to prevent them from choosing to do some parts of the code by hand, now or later down the road.

On the flip side, someone should be able to add Redux Toolkit to an existing Redux application, and begin using it incrementally, either by adding new logic or replacing existing logic incrementally.

Become the "Obvious Default" Way to Use Redux

Long-term, I'd like to see RSK become the "obvious default" way for most people to use Redux, in the same way that Create-React-App is the "obvious default" way to start a React project.

Don't Solve Every Use Case, and Stay Visibly "Typical Redux"

Redux is used in lots of different ways. Because of that, and because the core is so minimal, there's thousands of different Redux addon libraries for a wide spectrum of use cases. We can't solve all those ourselves, and we won't solve all those ourselves.

Reasonable TypeScript Support

I want to support people using TypeScript, same as I want to support anyone else using Redux in specific ways. So, RSK should be reasonably well typed. At the same time, I don't want "perfect typing" to become the enemy of "good functionality". I'm fine with trying to shape things so they work well in TS, but I'm very willing to ship a feature that has less-than-ideal typing if that's what it takes to get it out the door.

My Thoughts on Why I Don't Want to Merge Packages

Stating it here at the beginning: my current opinion is that I don't want to try merging the packages. There's several reasons:

• We've now had 3 years of telling people "Use @reduxjs/toolkit". All our docs and templates do that. I don't want to whiplash through another package name change.
• RTK not only depends on Immer, it actually currently has a side effect of calling its enableES5() plugin on import of RTK to ensure compatibility with earlier versions of RTK+Immer before that behavior got split out. That means Immer is always in the bundle as soon as you import from RTK. Now, in practice we expect everyone using RTK will use Immer. But someone who just wants createStore would now have that in the bundle too. (Note that this issue is planned to be fixed in RTK 2.0, when we would stop turning on the ES5 plugin by default and thus Immer would tree-shake correctly.)
• We'd likely have to do a ton of work to merge our three repos together into a monorepo. I've briefly tossed that around as an idea to get a single combined docs site. But, it would be a huge amount of effort, and I don't have time for that.

BUT... I want to actually discuss this out loud with the community and see what people's thoughts are.

Questions

• Should we try to merge packages at all?
• If we were to do this:
  • What would the revised package structure look like?
  • What would the repo/folder structure look like?
  • What API changes would need to be made?
  • If we were to start renaming/shuffling things, how would we teach this to existing users?
  • How would we avoid breaking existing code?

[timdorr]

I don't think we should. My main reason for thinking that way is bundle size. RTK is ~10x the size of Redux:

https://bundlephobia.com/package/redux@4.1.2
https://bundlephobia.com/package/@reduxjs/toolkit@1.8.1

For those not using RTK, that puts a lot of bytes into their projects. That feels especially weird after we've done things like #3920 to really cut down on library size.

I'm totally fine with merging the repos under a monorepo, though. That might even be a good idea (less redundant tooling, more alignment on releases, better community visibility). It would no doubt be a lot of work, but I think could be beneficial.

[markerikson]

The bundle size thing is actually kind of misleading.

RTK does tree shake. The exception is the Immer enableES5() usage, which will go away in whatever next RTK major we end up with. Other than that, you only pay for what you import.

From that perspective, I have no conceptual problem with a single "kitchen sink" package, which is what RTK itself is anyway.

It's the potential whiplash of "import redux-starter-kit! no, @reduxjs/toolkit! no, now just import redux!" that I'm really concerned with.

As for the monorepo thing: the RTK repo is already a (small) monorepo, but it's really "the toolkit code, and then we added a couple RTKQ codegen packages".

IF we were to ever seriously consider merging the three repos, the real problem would be trying to maintain Git history and issue history. Git history can be doing with rewriting that changes file paths (ie, src/index.js -> packages/core/src/index.js), but you'd also lose any external links that might have pointed to those files on Github. Issues? Man, I have no idea how you'd handle merging issues together.

(and that's before we even get into the logistics of trying to merge the three docs sites together...)

[geekact]

Why not emit warning message when developers are calling createStore?

function createStore(args, shouldWarning = true) {
  if (process.env.NODE_ENV !== 'production' && shouldWarning) {
    console.warning('...prefer to use @reduxjs/tooltik [url link]...');
  }
}

The developers will always open the Chrome DevTools and see this message.

[markerikson]

For one thing, configureStore currently uses createStore entirely as-is.

For another, using createStore is still a valid thing to do, and there's a lot of legacy codebases out there. (The one I'm working on now at https://github.com/RecordReplay/devtools was still on vanilla Redux until I upgraded the store setup right after I joined a month ago.)

I just want to provide a nudge, without getting to the point of being an annoying jerk about it.

[gkatsanos]

Merging feels natural and would be a step towards simplification - and simplification is a good thing in a generally complex ecosystem such as the one of JS frameworks/React/Redux.
To my understanding Redux had issues which RTK successfully tackled - but at the same time created a bit of confusion and added to the mental load of learning one more API. (configureStore, createStore, createSlice etc). For a beginner - who has to anyway grasp the advanced concepts of state management / Redux, having two entry points (Redux / RTK) adds to the confusion.
The merge could be backwards compatible (kind of), the old APIs can still be exported and available, but they could be all moved to a separate documentation section. New developers would not need to master returning new copies of arrays or objects without mutating them as the library will be doing it for them in the background. (one example)

I hope it happens.

[idevat]

Personally, I would like to be able use redux without RTK.

I appreciate redux simplicity - few concepts and code written near plain (java|type)script. I prefer it over complex opaque machinery. (Similar reasons once led me to prefer react over angular).

Bigger codebase can tend to change more frequently. Also dependencies like Immer sometimes means to deal with issues.

Redux makes perfect sense standalone. RTK is advertised enough. I'm for the freedom not to use it.

[lukescott]

I just want to offer some feedback as a long time Redux user who saw the deprecation method. It caught me by surprise, and was very confusing because:

1. We did not opt-in to upgrade to a major version, and I found it surprising a method we had been using for a long time was "deprecated" even though we did not upgrade.
2. It was not clear to me whether Redux toolkit was replacing Redux or if it was a superset. If it was a superset, "deprecated" seems wrong as you would expect an alternative within the library itself.
3. When looking at Redux toolkit examples, as a long time user, it wasn't clear if it was still immutable, which is something that has been ingrained in us for years.

I do not think that marking createStore as "deprecated" and providing a legacy alias is appropriate here because:

• Redux Toolkit uses createStore itself.
• Redux (Core) is supposed to be the core package.
• Long-standing users of Redux core are going to continue using it.
• Redux Toolkit are for those who feel that Redux is "too much boilerplate", but for those already using it, we already have existing patterns that eliminate that boilerplate (used internally) that make up hundreds of thousands of lines of code. If we transition to what is now considered "standard", that will take many years, if it happens at all.

What I feel should have happened is:

• redux package is renamed to @reduxjs/core.
• Issue a final version of redux with an npm install deprecation message. Point to a document that talks about using @reduxjs/toolkit for new projects and the benefits. But if you are in a position where you are already well established, you can just use @reduxjs/core as a drop-in upgrade.

This would have been a much more familiar and friendlier approach. I've already gone thru a dozen packages that have transitioned to a @namespace like this. It's not a big deal. What kind of is a big deal is finding existing code has a method with a slash thru it and spending a chunk of time trying to figure out why. It makes code look broken. Verses looking at a deprecation message in npm install and scheduling a time to upgrade on our usual package maintenance cycle.

[phryneas]

The deprecation message is there about a year now (please update your dependencies more frequently!), and it contains a link that you can click and read. I don't know how we can make it any "less chunk of time" than that, honestly.
Also, deprecation messages are usually not added in a new major, but in a minor or patch, often to warn about the removal in an upcoming major, and to show off better alternatives. Apart from us not removing createStore, we are completely in line with that - yes, it is perfectly normal that a normal package update will give you a message like this.
Honestly, it is very disheartening that we still have to have this discussion in the fourth year after we started recommending Redux Toolkit as the default way of writing any new Redux logic all over our documentation. If you haven't followed the project in all that time, it feels just weird that the first instinct you have is to come here and complain.

[markerikson]

@lukescott Hey, thanks for taking the time to write this up (and I mean that sincerely - reasoned discussion is a rare thing these days :) )

That said, I think I would have to disagree with most of the points and suggestions that you're making.

Let me try to respond to the points in rough order:

Purpose and Meaning of "Deprecation"

It is standard practice throughout the programming system to mark methods as deprecated as a way to discourage their use, even if there is zero intent to remove them any time soon.

In the release notes at https://github.com/reduxjs/redux/releases/tag/v4.2.0 , I quoted the Wikipedia definition of "deprecation":

"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"

Similarly, per https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/deprecation/deprecation.html :

When you design an API, carefully consider whether it supersedes an old API. If it does, and you wish to encourage developers (users of the API) to migrate to the new API, then deprecate the old API. Valid reasons to deprecate an API include:

• It is insecure, buggy, or highly inefficient
• It is going away in a future release
• It encourages bad coding practices

Deprecation is a reasonable choice in all these cases because it preserves "backward compatibility" while encouraging developers to change to the new API. Also, the deprecation comments help developers decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.

That precisely matches what we're trying to do here.

We're not removing createStore. But we want to actively discourage people from using it directly.

Marking it as @deprecated provides a visual strikethrough, which is meant to get users to hover over the variable name, see the doc hover tooltip that says "Please use configureStore from Redux Toolkit" instead", and read the linked docs page that explains that in more detail. The @deprecated attribute also literally carries the intent to the user.

When Should Deprecation Be Applied, Version-Wise?

Deprecations are generally meant to be applied in a minor version.

In RTK 1.9, we specifically marked some of the createSlice/createReducer options as deprecated. In that situation, we explicitly did intend to remove them in 2.0. As a preparation for that, we marked them as deprecated, and added a runtime warning, so that users who don't read our release notes would still be notified of the upcoming change.

In this case, there is no further change to the Redux core. Nothing is being removed. There's not even a runtime warning. It is appropriate for that to be in a minor version. That's us, telling you, that we don't think it's a good idea to use that method. And it worked! YOU NOTICED. That deprecation marker did its job. Note that the version was published a year ago, and despite that, it sounds like you hadn't looked at the release notes and seen it. This is literally why marking it as deprecated is important - it's the only avenue we have to proactively reach out to our users.

Status and Relationship of Redux Core and RTK

This is covered extensively in our docs, including the article linked directly in the hover tooltip and the release notes:

• https://redux.js.org/introduction/why-rtk-is-redux-today
• https://redux.js.org/tutorials/essentials/part-1-overview-concepts#redux-toolkit
• https://redux.js.org/tutorials/essentials/part-2-app-structure
• https://redux.js.org/usage/migrating-to-modern-redux
• https://redux.js.org/tutorials/fundamentals/part-8-modern-redux

Architecturally, RTK is a wrapper around the core redux library (createStore specifically, as well as compose and applyMiddleware).

Conceptually, RTK is a replacement for the core redux library, and all the extra code you used to write "by hand".

We want every single Redux-writing developer to be writing that code using Redux Toolkit if at all possible.

I'll also note that the Redux core and RTK docs pages are pretty clear that Immer is the key part of letting you write "mutating" state update syntax in reducers, and it does produce a truly immutable update:

• https://redux.js.org/tutorials/essentials/part-2-app-structure#reducers-and-immutable-updates
• https://redux.js.org/tutorials/fundamentals/part-3-state-actions-reducers#reducers-and-immutable-updates
• https://redux.js.org/tutorials/fundamentals/part-8-modern-redux#immutable-updates-with-immer
• https://redux.js.org/usage/structuring-reducers/immutable-update-patterns
• https://redux-toolkit.js.org/usage/immer-reducers

User Choices and Outcomes

You're correct that not all users will migrate to RTK.

Our job is to create the library that we think provides the best usage experience for all of our users, teach people how to use it, and let people know what we think are the best patterns for using the library that we have created and the solutions that we have provided based on answering thousands of questions and seeing the problems our users have run into over time.

If users hear our advice, and opt to not follow it, that's their choice to make. But we want them to be know that there is a choice in the first place, and be aware of RTK and our recommendations.

Redux Toolkit are for those who feel that Redux is "too much boilerplate", but for those already using it, we already have existing patterns that eliminate that boilerplate (used internally) that make up hundreds of thousands of lines of code. If we transition to what is now considered "standard", that will take many years, if it happens at all.

I know. One of the reasons we created RTK is to standardize those patterns. @phryneas will happily point out the drastic inconsistencies in Redux app development across the ecosystem prior to the creation of RTK. Literally hundreds of duplicate libraries published on NPM, and who knows how many hundreds more internal to companies, all trying to solve the same use cases in similar ways.

We designed RTK to solve the majority of use cases that Redux-using developers face in real world apps, and to be that standard set of tools that all Redux apps can make use of.

No one is saying that you have to rewrite your entire app right away. We're not even forcing you to rewrite your app. We're saying we think it's a really really good idea for you to migrate. But if you choose to do so, you can do it on your own timeline, and you can do that migration incrementally, because old-style and modern RTK code can co-exist permanently.

Proposed Packaging Changes

This is where I particularly disagree.

• redux package is renamed to @reduxjs/core.
• Issue a final version of redux with an npm install deprecation message. ... But if you are in a position where you are already well established, you can just use @reduxjs/core as a drop-in upgrade.

We've already had plenty of churn with naming and versioning. As it is, RTK started off as redux-starter-kit, and we had to rename it after publishing 1.0 due to confusion over its usage and purpose.

One of my primary goals as a maintainer is to maximize backwards compatibility and minimize churn in the ecosystem. There are times when it's necessary to have truly breaking changes, but I do my best to minimize those to be rare and only when absolutely necessary.

The redux package is firmly embedded in the ecosystem. And, as you yourself pointed out, there are a lot of people who are happy using it by itself and don't want to change.

We could rename the package to @reduxjs/core. But, what real benefit would that accomplish? That doesn't really nudge people over to using RTK. If we deprecate the entire redux core package, that's just going to add to the spew of warnings when you run npm or yarn, and frankly no one pays attention to those anyway.

Point to a document that talks about using @reduxjs/toolkit for new projects and the benefits.

is this not literally what we have done with the deprecation notice? :)

This would have been a much more familiar and friendlier approach.

All I did was add a single @deprecated tag, with a visual strikethrough. No runtime warnings. No errors.

The release notes have clear instructions saying you have 3 options for responding to this:

• Ignore it
• Edit the import to be legacy_createStore
• Use RTK instead

By the rules of semantic versioning, we'd totally be within our rights to delete the createStore API in the upcoming Redux 5.0 major release. We're not. We're keeping createStore, because we are not going to BREAK user code.

What could we possibly have done that would be "friendlier" than a single strikethrough with extensive notes explaining our reasoning?

What kind of is a big deal is finding existing code has a method with a slash thru it and spending a chunk of time trying to figure out why. It makes code look broken.

THAT IS EXACTLY THE POINT :)

You looked. You noticed. Mission accomplished. (Except that hovering over that variable literally links to the docs page explaining this, so I'm honestly not sure how it could take "a chunk of time to figure out why").

Final Thoughts

And, I do honestly appreciate you writing this up, in a calm manner. (I'm genuinely frustrated with other folks responding by yelling at us online, repeatedly and loudly, and accusing us of making this change in bad faith.)

But I am truly confused as to how the message that we have tried to so clearly document and explain is somehow not being received or understood, by you and a (thankfully small, but loud) group of folks.

Ultimately, it's our job as maintainers to make the decisions around the code, docs, and care of these libraries, that we think are best for the vast majority of our user base, to give them more maintainable code and tools that are easier to understand and use.

[lukescott]

I appreciate your taking the time. I think the reason why it took so long to notice is because the createStore call is wrapped in a root level helper that is seldom looked at or changed. I recently visited that section of the code because we're in the process of implementing i18n, and I had to update that section.

I guess the reasons I would have preferred a npm install message is because:

1. We would have noticed this sooner as we have a process in place to review npm deprecations and warnings, and audit logs. Editor level deprecations aren't going to be noticed as easily unless someone is actually looking at the code in question.
2. With an npm log entry, we can "upgrade" and then choose the path best suited for us without having a method have a permanent strike-thru or having to use an alias with the word "legacy" in it. For a large team and with bringing on new engineers, having to explain why we are using a "deprecated" or "legacy" method is not great.
3. OCD :)

The reason we haven't upgraded Redux in a while is because we consider it a simple lightweight library. It's not something that needs to change because of browser updates. So simple in fact we built our own purpose built tools around it.

While I understand the desire to create an easier path for newcomers, I see the old api as low level, and perfectly acceptable to use if you have established patterns in place.

At least this is how I feel about it right now. I haven't had a chance to fully evaluate this new pattern and how it would fit into our ecosystem. What we have now is very much purpose built.

Our system is very similar to React in how you have a component tree that mirrors the dom, and has a render cycle and flushes all the changes. We have a state component tree that performs specific operations (or "steps") in response to a Redux action, and when all the operations are complete, it "merges" the changes out, minimizing parent object recreation (being that object are immutable). Each component is very specific, and put together like legos (user-built).

It could be the new pattern might work well, I just haven't had a chance to dive in and see where the overlap is, and how we would utilize it.

[markerikson]

Huh. Totally separate from the "deprecation" question, I'd be interested in seeing some examples of this "state component tree" idea - always neat to see what people are doing with Redux, especially if it's out of the ordinary!

FWIW, odds are you could probably implement those extra patterns using the methods provided by RTK, and still shrink the amount of code involved. In other words, if your current approach involves "write a reducer, with some actions", then that same reducer would probably be writable using createSlice instead. (and of course createStore -> configureStore is a straight swap that normally involves deleting 30-40 lines of setup code for things like the devtools and middleware.)

[morzel85]

I don't know if its feasible, but I would prefer having:

• redux meaning the RTK (opinionated, batteries included, ...)
• redux/core meaning the fundamental parts (lightweight, mostly for consumption by main package or libs/frameworks authors who really need it)

[markerikson]

Not gonna happen at this point :) Too much churn for no actual benefit.