Mark's Dev Blog

Presentations: Maintaining a Library and a Community

Thu, 21 Nov 2024 21:00:00 -0500

The main thesis of this talk is that maintainers do a lot more than just write features and fix bugs, and that really most of what we do involves thinking about and interacting with the users of our library. That includes answering support questions, writing docs, thinking about how versioning and backwards compatibility will impact people, and a lot more.

Hopefully this proves useful to other maintainers, and peels back the curtain on what it's like to maintain a widely-used library.

React Summit US 2024

I first did this talk at React Summit US in November 2024:

Maintaining a Library and a Community - video

And here's the slides:

Maintaining a Library and a Community - slides

I also got to participate in a panel discussion on "The Future of React", with members of the React team and the community. This was a pretty good discussion:

The Future of React panel - video

NDC Oslo 2025

For NDC Oslo, I significantly expanded and updated the content and slides. Part of that is that I had an entire hour time slot instead of just 20 minutes, but also I thought of a lot more things to say :)

Maintaining a Library and a Community - slides

Video should be available online about a month after the conference, and I'll update this post once it's available.

https://www.youtube.com/live/42kUqbV3wIc?si=asXlCveJ_o660adX

React Advanced 2024: Designing Effective Documentation

Thu, 21 Nov 2024 20:00:00 -0500

My remote presentation for React Advanced 2024 was on "Designing Effective Documentation: Lessons Learned Writing the Redux Docs".

I've spent a lot of my time working on the Redux docs, and it is in fact how I got my start working on Redux!.

Hopefully this proves useful to other folks writing docs for tools and libraries.

Designing Effective Documentation - video

And here's the slides:

Designing Effective Documentation - slides

React Summit 2024: Why Use Redux Today?

Tue, 09 Jul 2024 23:00:00 -0500

I had the chance to speak at both React Connection Paris in April and React Summit Amsterdam in June, and at both conferences I gave a talk on "Why Use Redux Today?".

Both of those had the same core content, but I tweaked and updated the slides for React Summit.

Why Use Redux Today? - video

and the earlier livestream:

Why Use Redux Today? - livestream

And here's the slides:

Why Use Redux Today? - slides

React Summit US 2023: What's New in Redux Toolkit 2.0

Mon, 13 Nov 2023 23:00:00 -0500

I gave a lightning talk at React Summit US, and did a quick run-through of what's changing in RTK 2.0.

I've linked the livestream at the right timestamp for now, and will link the final video when it's live.

What's New in Redux Toolkit 2.0 - video

And here's the slides:

What's New in Redux Toolkit 2.0 - slides

(and totally unrelated to my talk, had the chance to lead a Carnival Parade of costumed characters as part of Kathleen McMahon's demonstration of "why you should never include a carousel in your design system!")

Kathleen McMahon: Carnival!!! - video

React Rally 2023 - A (Brief) Guide to React Rendering Behavior

Wed, 16 Aug 2023 14:00:00 -0500

My extensive post "A (Mostly) Complete Guide to React Rendering Behavior" is the most popular and widely appreciated post I've written. After the recent updates to cover React 18, it's now around 10,900 words long!

I recently had a chance to give a talk based on that post for React Advanced in 2022 and React Rally in 2023.

React Rally 2023

I'll link the video once it's available.

A (Brief) Guide to React Rendering Behavior - slides

A (Brief) Guide to React Rendering Behavior - livestream video

React Advanced 2022

A (Brief) Guide to React Rendering Behavior - video

And here's the slides:

A (Brief) Guide to React Rendering Behavior - slides

Presentations: 2022 Podcasts

Sun, 11 Dec 2022 12:00:00 -0500

I had the opportunity to talk on a number of different podcasts and interviews over the course of the year. I've gathered them here as a directory.

ThisDot / Tracy Lee: How to Contribute to Redux

Tracy Lee is a prolific podcaster, and her company ThisDot creates numerous shows related to the JS ecosystem. She had me on as part of a new "How to Contribute..." series, where I talked about ways to contribute to the Redux libraries.

https://www.youtube.com/watch?v=rPJmnxDX9lY

Kevin Ghadyani: Redux vs React Context

Kevin and I have done a couple long-form video discussions in the last couple years, and he's split those out into several separate videos.

This discussion was actually recorded in mid-2021, but just recently got published. We talked about the actual differences between Context and Redux, and why so many people get confused about the differences.

https://www.youtube.com/watch?v=1bIdaWVMFkc

PodRocket: Time-Travel Debugging with Replay (with Jason Laster)

I previously was a guest on the PodRocket podcast to discuss Redux topics. Shortly after I started working at Replay, they had me on again along with our CEO Jason Laster. We talked about the differences between Replay and "session recording" tools, the internals of how Replay works, and potential future use cases for time-travel debugging.

https://podrocket.logrocket.com/replay

Guild Community Tour: Mark Erikson

Taz Singh does a lot of interviews with folks in the JS community to help share their stories. He interviewed several folks at the Reactathon conference this year, and we had a chance to sit down and chat. We made a bunch of jokes about my Simpsons avatar, and talked about my early dev career, my time teaching in China, how I got involved in Redux, what prompted some of my blog posts, and the magic of time travel debugging with Replay.

https://beta.guild.host/presentations/episode-23-mark-erikson-bczaup

Peerlist: The Mindset of a Redux Maintainer

This was a meetup-type presentation of the "Modern Redux" talk I've done a couple times, but there were also some good questions asked afterwards.

https://www.youtube.com/watch?v=MbREkTZCcpc

20 Minute JS: Redux Toolkit and State Management in React

Fernando Doglio had me on to discuss some of the basics around "state management", why Redux became popular and then got a bad reputation, comparisons with other state libraries, and how we've modernized it with Redux Toolkit

https://podcast.20minjs.com/1952066/10665172-episode-12-redux-toolkit-and-state-management-in-react-with-mark-erikson

React Native Radio: A Redux Maintainer's Thoughts on Redux Toolkit vs Mobx-State-Tree

Earlier this year the React Native Radio podcast hosts did a show on Redux Toolkit vs Mobx-State-Tree. It was actually a very fair and balanced discussion, with a bit of a twist because host Jamon Holmgren is the maintainer of MST.

After listening to that episode, I had some thoughts on some of the topics they discussed, and reached out to Jamon. They brought me on for a follow-up episode where we dove into some of the points they'd brought up and I talked about why Redux is designed this way, including the purpose of immutability, pain points with selectors, and other tradeoffs. Really good discussion!

https://reactnativeradio.com/episodes/rnr-249-a-redux-maintainers-thoughts-on-rtk-vs-mst

Merged: Leading Tech Communities

Iddan Aaronsohn had me on the "Merged" podcast to discuss a number of topics around my involvement in the tech community. We talked about dealing with social media, sharing knowledge, working with open source, and more.

https://open.spotify.com/episode/67jTvkMB2vf7AYD5d8KSEs?si=DmNMOIuOSjaheIRI09-G_A&nd=1

Reactiflux Office Hours: Lenz Weber-Tronic and Mark Erikson

Carl Vitullo, one of the other admins in the Reactiflux Discord, held an "office hours" interview with myself and my RTK co-maintainer Lenz Weber-Tronic. We chatted about how we got involved with Redux, how users depend on implicit behavior of libraries, complexities of maintaining TypeScript libraries, the job searches we went through this year, and ways that people can get involved with open source.

https://open.spotify.com/episode/1xKYFWjPmtYwNY3DauQ2JB?si=LOhGBIrDQ5KI3034b6xvBQ

Blogged Answers: How I Estimate NPM Package Market Share (and how Redux usage compares to other libraries)

Wed, 06 Jul 2022 01:00:00 -0500

Introduction

For the last couple years, I've thrown around the statements that "Redux is used by 45-50% of React apps", and "Redux is by far the most widely used state management tool for React apps".

I've had a couple people ask how I'm coming up with those numbers. I'd written a couple prior comments about this - I tried to estimate React "state management market share" in Feb 2021, and talked some about the flaws in NPM stats as a metric in Feb 2022, but figured it was worth putting into a blog post for posterity.

I'll go through the sources I use, discuss the many caveats and limitations with those sources, and then look at Redux and other state management libraries as an example.

Primary Source: NPM Package Download Stats

The most obvious source, and the one that everyone including myself automatically turns to, is NPM's stats on how many times a package is downloaded.

That info is available through several different pages and aggregators.

NPM Package Stats Sources

NPMJS.com

The first is NPM's standard package description page. This shows a "downloads per week" graph in the right sidebar:

Until recently, there was no way to know how many times a given package version was being downloaded. Those weekly numbers count all versions of the package combined.

But, within the last year, NPM fiiiinally started publishing download stats per version. The limitation is that the data is only provided for the last 7 days worth of downloads.

Those per-version numbers are available on the "Versions" tab for a package on the NPM site:

Happily, these per-version numbers are also available as an API, with a URL of https://api.npmjs.org/versions/$PACKAGE_NAME/last-week, such as https://api.npmjs.org/versions/redux/last-week :

{
  "package": "redux",
  "downloads": {
    "4.1.0-alpha.0": 48,
    "4.1.0": 1603217,
    "4.1.2": 1869219,
    "4.1.1": 499937,
    "5.0.0-alpha.0": 220,
    "4.2.0": 2087907,
    "4.0.0": 114988
  }
}

(Note: It would be really neat if someone would create a tool that would start automatically scraping these per-version downloads stats and save them to allow comparisons over time...)

NPM Download Comparison Tools

There's several sites out there that let you type in a few different package names, and it will query NPM for download stats over time and graph them.

My go-to site is https://npm-stat.com. It lets you enter up to 5 package names (although I wish it allowed more), and shows graphs for daily/weekly/monthly/yearly download trends. Here's an example weekly graph from a query for Redux Toolkit, Mobx, and React Query since 2021:

Other available sites are https://npmtrends.com , http://npm-stats.org/, and https://npmcharts.com/ .

I also have seen https://moiva.io/ , which lets you do some similar NPM download stat trend comparisons for selected libraries, and also shows a variety of other stats: month-over-month download growth, recent releases, number of contributors, Github stars, bundle sizes, and more. A typical comparison page looks like this: https://moiva.io/?npm=@reduxjs/toolkit+mobx+react-query+redux+xstate

I haven't actually used Moiva that much thus far, but looking at it again now there's a lot of good info here and I ought to refer to it more often.

Alternate Stat Sources

There's a couple other actual stats sources I look at as well.

Github Dependency Lists

Github knows how to parse all the various package manager formats used in different language ecosystems, and uses that for many different features. One of those is the "Dependency Graph > Dependents" list, buried under the top "Insights" tab. It shows a count of how many repos and ecosystem packages depend on the package in this repo:

There's also Github stars. Frankly, I've never bothered using them as a proxy for actual usage, only vague popularity scales ("this just got posted", "a few people have looked at it", "this is actually being used", "this is widely used", "this is a major player in the ecosystem", etc).

The other vaguely statistical values I refer to are the occasional "what tools are you using?" polls that pop up on Twitter or Reddit, and particularly in relation to state management libraries. These produce some actual numbers in the poll results, as well as associated discussion. A few examples:

These are a much less objective set of numbers, but looking at both the poll numbers and discussion can help give a sense of what's being used. On the other hand, polls are also inconsistent in which tools they even list in the first place, which makes them harder to compare to each other.

Similarly, it's not actual hard stats, I do get a sense of what people may be using or finding interesting from general chatter on social media: Twitter, Reddit, HN, Reactiflux, etc.

Caveats with Package Stats and Sources

Settle in, because there's a lot.

Every single one of these metrics and sources is horribly flawed in multiple ways!

NPM Download Stats Flaws

Let's start with the biggest source.

The first issue is what's even triggering all these downloads in the first place. Per Laurie Voss, who co--founded NPM:

They are mostly CI machines. Since package lock, updates don't really cause download spikes any more. The overwhelming majority of downloads are builds, not individual developers.

This brings up a lot of questions and possible influences on these numbers:

A team with a bunch of CI jobs that keep redownloading the same packages is going to have an outsized influence on the absolute number of downloads
There's very clearly a long tail of downloads for older versions that hang around indefinitely, so older packages seem to have a sustained base of download size. So, how many of these are for old versions vs new versions?
The NPM download stats don't account for internal package hosting/caching servers like Artifactory or NexusRepository. For example, I used to work on a team that used an internal NexusRepo instance that caches packages, so none of our usage would ever get counted publicly.
What about scripts hosted on a CDN? One of Vue's selling points is that it's very <script>-tag friendly
For that matter, Vue is very popular in China, and there's a Chinese mirror of NPM (cnpm) that I've heard is typically used by Chinese devs. Downloads from that won't be reflected in NPM's stats.
It's possible to game the numbers. I saw one package that had only been published for the first time a few days before, and yet it somehow spiked to over 1M+ downloads a day within the next couple days. Clearly impossible, and it's likely this was due to a bot of some kind faking downloads.

For that matter, NPM's own stats aren't always reliable. There have been times when NPM recorded 0 downloads for a widely used package for a few days, or other times when there's a giant spike in downloads that can't possibly be real. For example, NPM claims that downloads of XState somehow tripled for a couple months before going back to normal, and downloads of Mobx went up by 75% for two weeks:

Given the consistent download levels before and after those periods, the spikes in numbers should be ignored as outliers.

Again quoting Laurie Voss:

They are meaningful relative measures -- a package with more downloads than another package is more popular -- but they have never meant anything as absolute numbers.

Laurie also covered this in a talk on the NPM registry in 2019.

As part of that talk, he described a metric called "share of registry", which points out that the absolute size of registry downloads is always growing. This means that a lib could experience an absolute increase in downloads, but its relative usage share could decrease. So, by checking "number of downloads for this package" vs "total downloads for all the registry" over time, you get a more normalized value.

I asked Laurie for some feedback on this post, and he reported that the NPM API offers the "total registry downloads" numbers for a given time range, such as https://api.npmjs.org/downloads/range/2015-01-01:2015-12-31 .

Sadly, I don't know if the "all registry downloads" numbers that Laurie used to generate that graph are available publicly, and even if they are that would take some work to pull together and calculate. So, us amateurs are stuck with just looking at the absolute values and guesstimating comparisons.

So, like I said, tons of flaws. But at the same time, NPM's download stats are basically the only hard objective numbers we as a community have to look at and infer actual usage numbers in any way. So, to some extent we end up having to look at those and make inferences, however flawed they might be.

Other Caveats and Concerns

I have no idea whether that Github "Dependents" list counts private repos. My guess is that it doesn't.

Any kind of an online poll is statistically meaningless - there's no guarantee of who saw it, who chose to answer, etc, and there's a lot of ways you could answer. What if I use Redux for my day job, and Mobx when I work on a side project at home? What answer would I choose?

What does "usage" mean anyway? :) Does 30 clones of a starter kit/boilerplate count as exactly 30 times as many "usages" as a team working on a single large project for multiple years? What about a project that pushes to CI dozens of times a day and rebuilds from scratch every time?

For the case of "React state management" specifically... React has its own built-in component state handling. There's no way to measure how much that's being used as the sole state management tool, beyond trying to somehow subtract "downloads of all state libs" from "all React downloads".

So having just listed a ton of ways that this process is flawed and hopeless, I'm now going to turn around and try to use it anyway :)

I'm going to walk through some of the steps I go through to come up with estimates of "React state management library" market share. This is largely because it's the area I'm most familiar with, but also frankly it's the area that seems to come up the most :) (although my perception here is also affected because I'm active in the React community and the maintainer of Redux, so of course this is a topic I would seem to see frequently.)

I'm going to compare Redux and RTK vs Mobx, Zustand, XState, and React Query, and also toss in a second set of comparisons with Recoil, Jotai, Valtio, and Mobx-State-Tree. (It would be interesting to add in Apollo, SWR, and Urql as additional data fetching libraries, but c'mon I can only put so much time into this blog post :) )

Now, I know that these are actually somewhat different libraries - React Query isn't "client state management", but given that it has a somewhat similar usage rate to Redux Toolkit (and folks sometimes migrate from Redux to React Query to manage server state), it often gets thrown around by people as a competitor.

Comparing NPM Stats

Generally, my first step is to go to https://npm-stat.com, type in the name of several libraries, and view stats for the last couple years. This starts to give us a sense of scale and relative comparisons.

For example, here's Redux Toolkit, Mobx, XState, React Query, and Zustand since the start of 2020:

But what happens when you do RTK, Redux core, React, and React-Redux?

So, both relative growth rates and sense of scale and magnitude are useful pieces of info here.

For additional comparison, here's RTK vs several other libraries:

Pulling out some of those numbers:

React: 16.0M
Redux: 7.7M
Redux Toolkit: 1.64M
React Query: 1.46M
XState: 1.11M
Mobx: 891K
Zustand: 550K
Recoil: 267K
Jotai: 117K
Mobx-State-Tree: 76K

For point of reference, when I did a similar comparison in Feb 2021, the numbers were:

React: 9.5M
Redux: 5M
Apollo: 1.3M (combined across @apollo/client and react-apollo)
XState: 750K
MobX: 600K
Redux Toolkit: 450K
React Query: 250K
SWR: 250K
Recoil: 60K
Zustand: 40K

(Yes, I realize there's some differences in which libs are in each list.)

What can we learn from these graphs?

Clearly the Redux core package has vastly more downloads than any of the other state libs
RTK has passed Mobx and XState
Remember that RTK has a hard dependency on the redux core, so all RTK downloads are also Redux downloads
React Query has really taken off in the last year, and is gaining downloads at a slightly faster pace than RTK
React-Redux has almost as many downloads as the Redux core, which means that most Redux users are using React
React-Redux has historically been in the vicinity of 45-50% of React downloads, but React's growth rate has accelerated in the last two years.
Redux and React-Redux are seeing growth in absolute terms, but not as much as React.
I'm actually a bit surprised that the download rates for React-Redux and Redux core have started to diverge a bit - perhaps we're getting more non-React users?
Zustand has seen quite a bit of growth

I have to say some of the results here kind of surprise me. Given the hype around Recoil early on, you'd think that it would have more usage. RTK seems to be actively growing, while the other libs are seeing very slow growth. (Also remember that we're at the "smaller state libs" scale, and the "React and Redux" scale dwarfs any of these.)

Comparing Github Dependents

I just now went through the repos for all these libraries, and manually looked up the stats on the "Dependents" page for each repo, and have them sorted by the "number of repos using this package" count:

Library	Repos	Packages
React	10,614,469	231,415
Redux	2,279,295	23,163
React-Redux	2,117,795	18,916
Redux Toolkit	275,624	1,635
XState	133,285	633
Mobx	106,102	4,585
React Query	75,383	919
Zustand	30,465	481
Recoil	26,159	369
Mobx-State-Tree	6,829	360
Jotai	4,065	170
Valtio	1,612	106

Some thoughts here:

It's amazing to see the scale of React itself. It just dwarfs everything else
There's a very interesting difference in ratios between the NPM download stats and the Github repo dependents stats. Redux is just about 50% of React in terms of downloads, but just barely over 20% in terms of repos.
Redux and React-Redux are much closer in terms of repos than downloads, although perhaps Github doesn't count RTK-using repos as depending on redux, in which case their relative ratio widens a bit

Poll Results

Similarly, I'm going to go through some of those polls I linked earlier and pull out the numbers for libraries over time:

Library	Twitter 2019-10	Reddit 2020-11	Reddit 2022-02
Redux	48%	42%	67%
Mobx	9%	4.5%	5.8%
Context	32%	25%
React state		22%
Recoil		4%	6.3%
Unstated		2%
Zustand			12.5%
Jotai			4.4%
XState			3.4%
"Other"	11%

Clearly there's a lot of inconsistency here in terms of which libs are even being voted on, much less which ones are being used, plus there's a split between "using React state" and "using a library". So, we definitely can't use these for real meaningful statistical comparisons, but you can still get a vague sense of usage here. The main takeaway I would get out of this is that, yes, Redux is still pretty strong here, and there's a lot of split beyond that.

Conclusions

Looking at these numbers now, with fresh eyes, here's my takeaways:

React's Growth Continues

I didn't do comparisons vs Vue, Angular, Ember, and Svelte here, but you can see by just looking at "React vs any other React ecosystem lib" that React is getting downloaded and used lot, and shows no signs of stopping.

Ironically, I did just pull up some links to framework-level usage comparisons based on similar statistics to answer a comment earlier, and they definitely do show React's lead. I'll link those here:

Redux is Still Number One In State Management

Clearly, Redux is still by far the most widely used state management library with React apps. No other library comes close in terms of NPM downloads and dependent repos, and even Redux Toolkit by itself is beating the other libraries handily. Additionally, the anecdata of the polls and discussions shows a lot of people saying "use RTK", which is a noticeable change from 2018-2019 when a lot of folks were chattering about "Redux boilerplate" and "Redux is dead".

I said at the start of this post that I've been repeating "Redux is 45-50% of React apps" for a while now.

Honestly, after seeing these numbers, I think I need to revise that at least partially.

If we look at just React, Redux, React-Redux, and RTK:

Library	DLs/wk	Dependents
React	15.97M	10.61M
Redux	7.45M	2.28M
React-Redux	5.62M	2.11M
Redux Toolkit	1.57M	0.27M

Based on NPM downloads, Redux itself is still around 45% of React, but React-Redux is only 35%.

Where it gets really different is in terms of dependent repos. There, Redux is only 20% of React.

To be honest, I'm really not sure what to make of the split between numbers here. If we go back to Laurie Voss's point that "NPM downloads are primarily driven by CI", I suppose some interpretations here might be:

There's a ton of repos that depend on React, but not Redux. It's possible that a noticeable percentage of those are "starting to learn React" repos from beginners, and thus might be less likely to depend on Redux
It's also very likely that a larger number of new apps today are indeed less likely to add Redux, because they don't feel it's necessary
It's possible that larger professional apps may be relatively more likely to be using Redux, and thus installing it when building in CI
Libraries that depend on React may also contribute to the number of React downloads

To be clear, I don't know if any of these guesses are correct! I'm just brainstorming right now as I look at these numbers, trying to come up with possible explanations.

If I were to revise my previous "45-50% of React" estimate... the obvious potential bounds here are 20-35%, depending on how you balance "downloads" vs "dependent repos".

On the other hand, as I asked earlier: how should we weigh "usage" between "thousands of starter app clones" and "real apps"? Raw numbers? Does 1 real app === 10/100/1000 starter clones? How would we even figure that out how many repos fit in those categories without completely scraping Github? :)

I'm going to try to be intellectually honest with myself here:

I'm going to revise my prior "45-50% of React apps use Redux" estimate, and lower it to "roughly 33% of React apps use Redux".

I think that's a fair-ish estimate based on the combination of downloads + dependents, tweaked by the anecdata.

Wishlist

It would be really nice if someone could put together a new NPM package comparison site that automates the "share of registry" metric for a given set of packages. Given that you can query for "all registry downloads" and "per-package downloads" for a given time range, this seems pretty feasible.

It would be nice if there was also a way to query Github's API for the "Dependents" info, but it doesn't look like that's available. I did find a Stack Overflow answer showing how to scrape that info from repo pages, so I guess that could be a fallback option.

Moiva.io seems like it does a good portion of that already, and there is an open issue to add dependents as a metric. I also just filed an issue asking for adding "share of registry" as a comparison metric as well.

Final Thoughts

Hopefully the info I've provided here is informative and useful for folks trying to make comparisons between different packages.

And yes, I did intentionally write this post to show some stats behind my repeated statements that "Redux is still most widely used" and "45-50% of React apps". Looking at these numbers, they definitely back up the "most widely used", but I did have to revise the "45-50%" down to about "33%" - I hadn't realized just how much the gap in downloads between React and React-Redux has grown in the last year.

Presentations: Modern Redux with Redux Toolkit

Mon, 27 Jun 2022 20:00:00 -0500

I've frequently talked about why we created Redux Toolkit and what APIs it includes as part of my "State of Redux" talks and other similar presentations. I recently had the chance to talk at a couple of online meetups, and put together an updated and consolidated version of that material as a complete "Modern Redux with Redux Toolkit" presentation:

Modern Redux with Redux Toolkit - video

Modern Redux with Redux Toolkit - slides

Reactathon 2022: The Evolution of Redux Async Logic

Wed, 04 May 2022 12:00:00 -0500

I've spoken at Reactathon in past years, and this year I had the chance to give a pre-recorded talk. I also ended up giving the same talk live as well after filling in as a backup speaker.

My talk looked at why we use middleware for side effects in Redux, the major libraries (thunks, sagas, observables), why we've recommended thunks, introduces RTK Query and the "listener" middleware, and gives our current recommendations for what tools to use in different scenarios today.

The Evolution of Redux Async Logic - slides

The video should be online in the next few weeks, but for now you can see me give the talk as part of the Day 3 livestream:

The Evolution of Redux Async Logic - livestream video

Idiomatic Redux: Designing the Redux Toolkit Listener Middleware

Fri, 18 Mar 2022 10:00:00 -0500

Intro

In Redux Toolkit 1.8, we released a new "listener" side effects middleware that is intended to be a lightweight alternative to more widely used Redux async middleware like sagas and observables.

The final API and usage of the middleware looks like this:

import { configureStore, createListenerMiddleware } from '@reduxjs/toolkit';

import todosReducer, {
  todoAdded,
  todoToggled,
  todoDeleted,
} from '../features/todos/todosSlice';

// Create the middleware instance and methods
const listenerMiddleware = createListenerMiddleware();

// Add one or more listener entries that look for specific actions.
// They may contain any sync or async logic, similar to thunks.
listenerMiddleware.startListening({
  actionCreator: todoAdded,
  effect: async (action, listenerApi) => {
    // Run whatever additional side-effect-y logic you want here
    console.log('Todo added: ', action.payload.text);

    // Can cancel other running instances
    listenerApi.cancelActiveListeners();

    // Run async logic
    const data = await fetchData();

    // Pause until action dispatched or state changed
    if (await listenerApi.condition(matchSomeAction)) {
      // Use the listener API methods to dispatch, get state,
      // unsubscribe the listener, start child tasks, and more
      listenerApi.dispatch(todoAdded('Buy pet food'));

      // Spawn "child tasks" that can do more work and return results
      const task = listenerApi.fork(async (forkApi) => {
        // Can pause execution
        await forkApi.delay(5);
        // Complete the child by returning a value
        return 42;
      });

      const result = await task.result;
      // Unwrap the child result in the listener
      if (result.status === 'ok') {
        // Logs the `42` result value that was returned
        console.log('Child succeeded: ', result.value);
      }
    }
  },
});

const store = configureStore({
  reducer: {
    todos: todosReducer,
  },
  // Add the listener middleware to the store.
  // NOTE: Since this can receive actions with functions inside,
  // it should go before the serializability check middleware
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().prepend(listenerMiddleware.middleware),
});

But how did we end up with that API design?

Trust me, it didn't appear out of thin air :)

The development of this new API was a long and winding process that dates back 2.5 years, and involved significant amounts of iteration to determine what use cases it should cover, what the public API should look like, and how to implement the functionality.

I'd like to recap that process, as I think it's a good example of how to work through designing library APIs and there may be useful lessons for other developers.

Why Create a New Middleware?

Background: Redux Side Effects Approaches

Redux was originally designed to use middleware for customizing side effects behavior with your choice of syntax. Dan and Andrew specifically didn't want to lock users into having to use a single built-in API for async logic, or require users to learn a complex library like RxJS.

The Redux community jumped on this idea, and began cranking out dozens of addon libraries for managing side effects (to the point that less than a year after Redux's release, there was a post complaining there were too many side effects libraries).

But, by late 2017, the ecosystem had mostly coalesced to a few major options:

Thunks: dispatch a function, get (dispatch, getState) as arguments, run whatever logic you want in that function
Sagas: write generator functions that respond to dispatched actions and return descriptions of side effects ("call this function with these args"), and let the saga middleware do the actual work
Observables: write RxJS observable pipelines that respond to dispatched actions and execute side effects

In practice, thunks have always been considered the default. Sagas have been fairly popular. Observables have been somewhat less common - they solve the same use case as sagas, but are mostly used by people who prefer RxJS as an API for declarative behavior rather than the more imperative generator function syntax of sagas.

Redux Toolkit and Thunks

When we designed Redux Toolkit, we specifically wanted to have a good store setup out of the box. We decided early on to automatically set up the thunk middleware by default, because thunks have always been the most common approach for writing async logic. Additionally, we've specifically recommended thunks as the default side effects approach for years, and RTK includes a createAsyncThunk API that abstracts the standard pattern for dispatching actions based on a promise's lifecycle.

RTK's configureStore API allows full customization of the middleware, including replacing the defaults entirely. So, you've always been able to add sagas, observables, or custom middleware to the store, or turn off thunks entirely.

Concerns with Sagas and Observables

Over the years, we've become more opinionated in our advice about how to use Redux. As part of that, we've progressed from "use whatever side effects library you want", to actively discouraging people from using sagas unless absolutely necessary.

We've been asked if we would ever add direct support for sagas to RTK itself, either by including them as a default or having some saga-specific API included. I answered this in my post Why Redux Toolkit Uses Thunks For Async Logic, which points out that:

Sagas require understanding both generator functions and the specific redux-saga "effects" APIs
Some saga patterns like "watcher" vs "worker" sagas lead to extra boilerplate as well as making logic hard to follow
Sagas don't work well with TypeScript
Sagas are good for very complex async workflows, but overkill for basic data fetching scenarios

The same concerns apply to observables as well, just with "RxJS operators" instead of "generator functions and saga effects".

These factors all played a role in the eventual development of the listener middleware.

Original Inspiration

In October 2019, I filed an issue for "Add an action listener callback middleware". In that issue, I wrote:

Thunks are easy to use and a good default, but the biggest weakness is that they don't let you respond to dispatched actions. Sagas and observables are very powerful (too powerful for most apps), but they do let you kick off additional logic in response to actions.

I've been considering adding some kind of middleware that would be in between - something that lets you run callback functions in response to specific actions, but without the complex overhead of sagas and observables.

In that issue, I specifically linked a "handler" middleware written by Justin Falcone during his time at Glitch. Justin commented with some details on why it was being used:

There are essentially two schools of thought for working with side effects with redux.

The first approach is to put the side effects in the actions -- e.g. instead of dispatching a simple value, dispatch a promise, or a function that calls side effects. Middleware like redux-promise and redux-thunk intercept these non-value actions and run them.

The second approach is to put the side effects directly into the middleware -- the actions are always simple values, but the middleware listens to these actions, and can run side effects in response to them. This is the approach used by redux-saga and redux-loop; it's also how logging and metrics-reporting middleware work.

I prefer the second approach because it encourages you to keep the "how" with the state, and the "what" with the UI. However, the tools associated with this approach, particularly redux-saga, tend to have a pretty steep learning curve. The approach I'm using here is less expressive, but much closer to the complexity of redux-thunk.

I replied with:

Yep, that's the idea I'm going for here. One possible improvement I'd like to consider is adding and removing subscriptions at runtime. The likely approach would be dispatch(addActionListener(type, callback)).

This formed the basis for the initial design of the middleware: the ability to run callbacks in response to dispatched actions, with a simpler API than sagas or observables, and to add and remove "listener" callbacks at runtime via dispatching.

Initial Design and Implementation Ideas

The same thread then went off into some early design discussions. I tried to lay out some initial constraints and API usage ideas:

There should be multiple possible handlers for a single action type. The Glitch middleware linked in the original post does that.

It should be possible to add more handlers at runtime by dispatching a "listeners/addListener" action that contains a callback function as the payload, and is explicitly stopped by the middleware from proceeding to the reducers. There should also be some way to remove a listener using the same approach, whether it be based on a returned ID or a function reference equality check.

Other than the "add/remove listener" actions, the middleware should probably pass the action through to the reducers first before executing the listeners, same as how sagas work. (I could hypothetically imagine including a way for the callbacks to say "stop this action from proceeding", but it'd be a lot simpler if we don't worry about that.)

We're definitely going to pass the "store API" {dispatch, getState} object into the callbacks. Perhaps we should also pass in {addListener, removeListener} as part of that param as well.

At the same time, Lenz Weber tried to put together an initial proof of concept PR just to get something going. Lenz's POC relied on providing a lookup table of action types as another field inside of createSlice, and generated a separate listener middleware instance per slice.

As the discussion continued over the next few days, we debated whether it was better to define listeners inside or outside of slices, whether dynamically adding listeners at runtime via dispatching was a good idea, and the possibility of users tying listeners to components. In the process, I also tossed out an initial suggestion for a "predicate API" that would look like (action, currentState, prevState) => boolean, as a way to check for state changes in addition to specific actions. I also pointed out that a dispatch-based approach for dynamically adding listeners made it the most flexible and easily accessible. If we tried adding a new method to the store itself, the UI wouldn't have access to it, whereas dispatch is universally available. Similarly, dispatch is UI-agnostic and thus would work with any view layer.

Second PR and Use Case Bikeshedding

Initial PR Contents

The original discussion thread continued intermittently for several months. In May 2020, Lenz put together a second implementation attempt in PR #547.

This attempt started with a few interesting ideas:

Adding listeners either via middleware.addListener or dispatch(addListener())
Matching actions either via type string or by providing an RTK action creator
One-shot listeners by providing a once option
The ability to actually stop an action from being processed by any other listeners or the reducers, by providing a preventPropagation option
A condition callback that could be used to further determine if a listener should run or not

Having a concrete code implementation to look at was great... and it promptly sparked a major wave of bikeshedding :)

One quirk of the initial PR was that the "add listener" action object was actually being passed onwards to the reducers. Since the action originally contained the listener callback function, and those aren't serializable, the middleware was deleting the callback before forwarding the action onwards. The idea was that seeing the "some listener got added" action in the DevTools might be useful for visibility purposes.

PR Iteration and Brainstorming

We debated the value of this for a few days, and at one point Lenz started thinking about dispatching some kind of a "started listening" action. However, he quickly realized this led to too much complexity, and we decided to just drop forwarding the "add" action entirely.

At the same time, a user tried out the PR prototype build, and interestingly jumped straight to trying to add a listener by dispatching from within a component. They ran into a types issue where TS thought that the value returned from dispatch was the plain "add" action object, rather than the unsubscribe callback that should be getting returned. I realized that this was actually a repeat of a types problem Lenz and I had run into a year earlier - trying to get TS to acknowledge that a middleware may alter the return value of dispatch when a specific action is dispatched. (Lenz noted that TS specifically had issues when other fields were attached to the middleware, and said he had "fixed it by brute force". Spoiler: this would come back to bite us later!)

The same user noted that the initial implementation actually ran the listeners before the reducers processed the action, and that meant they couldn't ever see the updated state. Lenz suggested adding a when: 'before' | 'after' option, and added that to the PR. However, I pointed out that both the saga and observable middleware handle effects after the reducers run, and so that should probably be the default.

There was a flurry of discussion activity over the next few days, which led to several PR updates: dropping the once and condition options, defaulting when to 'after', adding listenerApi.unsubscribe, and a consolidation of internal handling for the "before/after" logic. We also did some review and comparison of how other Redux-based libraries and similar custom middleware, to see what their APIs looked like and what capabilities were included.

In the process, I started having some ideas about what methods should be exposed as part of the "listener API", like adding a getPreviousState method:

By passing in getState to the listener, we enable them to read the "current" state at any point in the future, ie, in the middle of some async/await stuff. So yeah, we definitely want getState.

What doesn't give you is the ability to know what the state was before the listener even got triggered at all, which is why I was thinking about getPreviousState.

As a side note: these listeners are definitely way weaker than sagas and observables, in that I don't see how you'd listen for multiple distinct actions in sequence. I'm okay with that, as this is deliberately intended to be a much more scoped API anyway.

(Narrator: This Changed)

At the same time, @mpeyper suggested adding subscribe/unsubscribe methods, and we both came up with the idea of adding an extraArgument similar to the thunk middleware, with the typical use case of injecting a service layer into the middleware. Lenz suggested adding a type guard to enable better typed matching against certain actions, and another user mentioned the idea of waiting for a condition to evaluate to true based on an (action, state) combination. Although we didn't know it at the time, these would all end up becoming parts of the final listener middleware API, albeit after some of these were forgotten and independently reinvented later :)

Stalemate

By late 2020, the conversation on the PR had died off due to a lack of clarity about what the runtime semantics of the middleware should be. The Redux team moved on to working on other new features, including RTK Query. PR #547 was still open, but fell off into the background. Lenz did suggest possibly publishing it as a standalone package under our @rtk-incubator package scope, just to give people a chance to try it out separately.

A couple other users did comment expressing interest. One comment in Dec 2020 said "we're using sagas, but looking for alternatives because those are too complicated". In June 2021, another user dropped by Reactiflux asking some questions, and I pointed them to the PR as a possible solution. They tried it out and left some suggestions on both internal implementation and APIs for adding listeners.

A few days later, a user named Faber Vitale commented and offered suggestions on adding error handling, pointing out that currently any thrown error would kill the entire processing chain. Faber had actually just written the new RTK Query monitor for the Redux DevTools. Faber would end up adding huge contributions to the final version of the middleware.

In late September, another user listed some reasons for wanting to drop sagas:

Poor TypeScript support and will never get official TypeScript support according to maintainers.

Generator syntax isn't as straightforward as normal JavaScript

Thunk actions (action creators that return promises) are sweet and Saga doesn't support

No longer actively maintained

Redux maintainers generally advise against using it whenever possible unless dealing with really complex asynchronous flows where handling timing overlap of actions is needed.

In general, having some sort of takeLatest/takeLeading esque option on a per function basis would be a game changer. If that were the case there would be practically no reason to use Saga for almost any use case (except maybe a complex auth flow, for example).

It was clear that there was some interest in this middleware - it just needed some actual attention and effort to push it forward.

Restarting the Development Effort

Extracting a Standalone Implementation

In September 2021, I was working on adding some analytics tracking to my day job's app. I specifically wanted to be able to save some analytics events based on dispatched actions. I knew that other analytics-related middleware existed, but I remembered the WIP "action listener" middleware PR and figured it might be a good fit.

The original PR had long grown stale compared to the current RTK release, so I ended up copy-pasting the entire middleware source from the PR directly into our own app. In the process, I also hacked in the ability to pass in a "matcher" function as well to allow matching against multiple possible action types, not even remembering that Lenz had suggested something similar earlier. (I ended up doing this by adding a separate code path for "matchers" vs "type"-based comparisons, which required a chunk of duplicated code at the time.)

Since I'd done the work to make the middleware run as a standalone implementation, I went ahead and pasted the source into a comment in the original PR in case anyone else wanted to try it.

Creating a New Incubator Package

Another couple months went by. In early November, I remembered the middleware again, and finally decided to do something about pushing the effort forward.

By this time we'd turned the RTK repo into a monorepo, containing the original RTK package plus a couple of auxiliary packages related to RTK Query code generation. I copy-pasted the build setup from one of those, and published the standalone middleware source as @rtk-incubator/action-listener-middleware v0.1.0. I then put up RTK discussion #1648: New experimental "action listener" middleware as a thread to house discussion and further iteration on the middleware.

Updating the Design Goals

I took the time to go back through all the prior existing discussions in the issues and PRs, and assembled a list of relevant comments and suggestions on use cases and possible API features. I then wrote an extended comment where I summarized the existing API, listed remaining open questions, and offered my suggestions for design behavior.

I got a couple other comments with some excellent suggestions, like removing the stopPropagation method on the grounds that it was confusing semantically.

Shaping the API

v0.2: Finding the Right Primitives

I spent the next couple nights hacking on several of those ideas, and published v0.2.0 containing the updates.

v0.2 had several important changes: it dropped the stopPropagation method, added an extra argument to middleware creation, added getOriginalState to the listener API, and added some basic try/catch error handling.

However, as I was working on these changes, I already had bigger ideas in mind for further down the road. We'd said from the beginning that "listeners" weren't supposed to replace sagas. After all, sagas were meant for really complex async workflows, and you couldn't do most of the really powerful saga operations like cancellation, throttling, debouncing, forked child jobs, long-running async workflows, or takeLatest without using generator functions.

Or... could you? What if we could replicate most of the functionality of sagas, by adding some key primitives to the listener API design?

This thought started running through my head, and I began having some admittedly grandiose ideas for what this "action listener" middleware could someday become.

At the same time, I happened to be chatting with Shawn Swyx Wang. Shawn was working at a company called Temporal.io, which lets devs write very long-running async workflows as code (like a monthly billing cycle implemented as while(true) { sleep("30days"); billUser(); })). I figured he might have some useful input, given the conceptual similarity of "async workflows".

Shawn specifically pointed me to one of Temporal's workflow APIs as a possible enhancement: condition. Temporal's condition method lets workflows pause themselves until the provided callback function returns true. It also accepts an optional timeout, and returns a Promise<boolean>. That means it can be used as if (await condition(someCheck, timeout)), allowing for both async behavior and easy use with conditional checks.

After looking at that, it was pretty easy to add an equivalent function to the listener API. I wrote it in about 30 lines, and implemented it as a one-shot listener that resolved a "succeeded" promise, raced against a "timeout" promise.

I published the condition method as part of v0.2, and specifically pointed to that in the announcement as an example of enabling "long-running async workflows".

v0.3: Fixing Listener Syntax and Types

At this time, the API for adding a listener still looked like:

middleware.addListener(typeOrActionCreatorOrMatcher, listenerCallback, options);

I wanted to get the action correctly typed inside of listeners, but this wasn't providing type inference because of the overload behavior.

I decided it was best to switch addListener to take a single options object containing several different possible fields for matching against an action. The question was how to get the type inference working correctly. I also wanted to be able to use the same options object typedefs for both middleware.addListener and the "add" action creator. Additionally, at this time the listenerApi.getState method was still hard-typed to return unknown, because there was no way of knowing the actual RootState type before the middleware was created. I figured our best bet was to provide support for declaring "pre-typed" versions of both those functions, similar to how React-Redux exports a TypedUseSelectorHook type.

I was able to get the actual code rearranged to take an options object pretty easily. However, the type inference was refusing to cooperate. I spent a couple days banging my head against it before I acknowledged that my TS-fu simply wasn't strong enough to solve this one myself.

I posted a comment with my WIP code, described the issue, and begged for help. Happily, within the next couple days, I got the assistance I needed. Josh DeGraw gave me an example of extracting the common options as a separate type, and Lenz figured out how to get the overload type inference working correctly.

With that hurdle gone, I published v0.3 with the switch to an options object for adding listeners, as well as the ability to pre-type the "add" methods.

v0.3 also included a couple other key new capabilities. The listenerApi object already had an unsubscribe method. A user suggested adding subscribe as well. This would allow listener callbacks to mimic the takeLeading effect from sagas, by calling unsubscribe at the start to prevent any other instances of that listener from running, and re-subscribing at the end of the callback.

v0.4: "Child Job" Support

From the beginning, we'd said that this "action listener" middleware wasn't supposed to be a full replacement for sagas or observables. However, the addition of the condition and subscribe/unsubscribe methods had gotten me wondering if it might be possible to match the capabilities of sagas after all. I figured it was worth at least doing some research and exploration to see what was feasible, and to do so at this point while the middleware was still in alpha, rather than release something "final" and realize we'd missed some key use cases.

I spent several days doing some significant research on the APIs and capabilities of multiple libraries across the JS ecosystem: redux-saga, redux-observable, redux-logic, xstate, ember-concurrency, and several others, then wrote up my research notes as an extended comment. My conclusions were:

The current "action listener" middleware API let us do the equivalent of takeEvery and takeLeading
takeLatest would require cancellation support
Every library that realistically supported cancellation required use of generator functions, because promises are not inherently cancellable
sagas and ember-concurrency both supported "child tasks", and those also required cancellation support

I really didn't want to turn the listener middleware into another generator-based implementation. At that point it would just be a cheap knockoff of sagas, and there'd be no point in it. But, promise cancellation is a quagmire topic - hundreds of people much smarter than me have fought over that in API designs for years, with no good resolution.

A search of NPM for "async cancellation"-related libs did turn up a couple of interesting possibilities. One was https://github.com/ethossoftworks/job-ts , a library that provided a "job" abstraction with promise-based cancellation support. I also found a gist at https://gist.github.com/andrewcourtice/ef1b8f14935b409cfe94901558ba5594 with a "task" API that used AbortController internally.

After playing around with the job-ts library, I decided its "job" abstraction seemed like a good match for how saga child tasks worked. I ended up copying the source over into the middleware package, and wrapped each listener invocation in a Job instance. That enabled me to add a form of cancellation for each running listener instance, and also let listeners kick off child jobs as well.]

Meanwhile, Faber Vitale pointed out that we didn't have an equivalent of the saga take API. The condition method we'd added was very similar, but it returned a boolean and not the matched action. I agreed that would be useful, and Faber filed a PR to add take.

I released v0.4 with take, listener cancellation, and "job" support in early December 2021. With those APIs now available, I was then able to write a test file demonstrating equivalent behavior to the takeLatest, takeLeading, throttle, debounce, fork + join, and fork + cancel saga effects, showing that the WIP "action listener" middleware could now do most of the same things as sagas.

v0.5: "Tasks" and `AbortController`

The "jobs" API worked, but it added a bit more bundle size than I wanted. The implementation was based on a class, and I'd had success shaving some bytes in React-Redux by converting a class to a closure for better minification results. I gave that a shot here, but didn't see any real improvement.

At the same time, Faber decided to try replacing the "jobs" API entirely. Instead, he reimplemented cancellation behavior and the take/condition methods using a "task" abstraction that was built around AbortController instead. Because fork/delay/pause had been part of the jobs-ts API, we ended up adding those as methods inside of listenerApi instead.

This shaved off about 2K min, leaving the middleware around 4k min in total. I had liked the "jobs" API and concept, but smaller code is a big win, so I shipped that as v0.5.

At this point it felt like we'd settled on the right capabilities, use case support, and general design for the API. The "action listener" middleware could now do most of the same things as sagas, but with a much smaller API and bundle size.

I tried asking for user feedback on Twitter, but wasn't really getting much of a response. So, it was up to us to figure out what else needed tweaking.

v0.6: Simplifying Behavior

Faber pointed out that the original when option was basically useless now that there was no longer an option to cancel action processing. Lenz and I agreed, so I went ahead and ripped that out.

In the process, I noted that listenerApi.cancelPrevious() was misleading, because it actually cancelled all other running instances of that listener regardless of ordering. I ended up renaming it listenerApi.cancelActiveListeners() for clarity.

Those changes went out in v0.6.

I summarized the open questions at that point:

We need to review the types for extra and figure out how to get that to carry through properly

Not happy with how removeListener is solely based on action type right now

Should passing in an entry with the same listener reference still skip adding a new entry and return the existing one, or should we actually have two distinct entries added?

Should we add some kind of a "bulk add listeners" API somehow? Is that worth it?

Are we happy with the likely usage pattern of having a listenerMiddleware.ts file that creates the middleware and exports it, and then slices would have to import that and call middleware.addListener()? Is there a better setup pattern more akin to createSlice + configureStore(), where a slice file can define an entry that can be imported into listenerMiddleware.ts and added?

The middleware return types still aren't working right - const unsubscribe = store.dispatch(addListenerAction()) results in a {type: string, payload: ListenerEntry| type, when it should be an Unsubscribe type. Not sure if this is due to the listener middleware types, configureStore types, or thunk types.

v0.7: Cleanup Improvements

A user asked if there was a way to clear all listeners entirely, particularly for use with cleaning up a shared store instance during tests.

Faber filed a PR to add middleware.clear(). We'd also noted that the "remove" functions only allowed matching based on exact action type, and Faber was able to rewrite them to accept the same options object as the "add" functions for consistency.

We also noted that the existing behavior for the getOriginalState method could potentially lead to memory leaks. getOriginalState captures the value of state before the reducer has a chance to process the action. Since that was always being passed in to each callback as part of listenerApi, that meant that the state reference was being kept around as long as any listener callback was still running.

We fixed that issue by reworking the internals of the middleware so that getOriginalState can only be called synchronously during the original dispatch call stack. If a listener really wants to have access to that value later, it needs to call getOriginalState() right away and save the reference explicitly.

Those fixes went out as v0.7 at the end of January 2022.

TypeScript Issues

I had noted much earlier that there were a couple remaining TS-related issues:

createActionListenerMiddleware() accepted an extra argument, but listenerApi.extra was always typed as unknown - the provided value's type wasn't being carried through the rest of the middleware types
const unsubscribe = dispatch(addListener()) was typed as returning the {type: 'alm/addListener'} action object, when the code actually returned an Unsubscribe callback

Fixing the extra type behavior was easy. However, as I dug into the unsubscribe type behavior, I just couldn't understand why TS was failing to recognize that the middleware's types changed the return of dispatch when that particular action was passed through.

Lenz took a look, and after some discussion we concluded that there were really two parts of the problem:

The types for getDefaultMiddleware() were not doing a sufficient job of inferring any available overrides of dispatch. There was some hardcoded handling internally for the thunk middleware's types specifically, but if any other middleware tried to augment dispatch, those types weren't getting included
createActionListenerMiddleware() created and returned the actual middleware instance, but also attached the {addListener, removeListener} methods directly onto the middleware instance itself. Lenz had said earlier that he'd "solved the problem with brute force", but we determined that this somehow changed the type of the middleware enough that TS could no longer infer any dispatch augmentation.

I ended up rewriting the types for RTK's getDefaultMiddleware completely. We already had an internal MiddlewareArray type that provided custom concat/prepend methods for improved typing, since [...getDefaultMiddleware()] seemed to lose types. I was able to borrow some advanced TS type inference techniques I'd learned while working on Reselect 4.1, and upgrade its ability to extract the exact type of each middleware. I then rewrote the concat/prepend methods to return concatenated TS tuple types with the exact types of the added middleware, rather than a much looser Middleware[] array type. This preserved any potential dispatch augmentation type info.

Those changes went up as a PR for RTK itself, and I put them on an integration branch that would later become RTK 1.8.

For the middleware methods, we decided that our best option was to change the return structure of the "create middleware" function. Instead of returning the middleware directly and attaching the methods, we decided we'd have to return an object containing the instance and the methods, like {middleware, addListener, removeListener}. It was a bit annoying to have to do that just to placate TS, but we felt it was necessary to get the right typing behavior and developer usage.

v0.8: Bikeshedding Naming!

Faber had suggested earlier that "action listener middleware" and createActionListenerMiddleware were too long, and I agreed.

Alongside the return value changes, I proposed that we change the creation function name to createListenerMiddleware.

The other naming concern I had was that the naming clash between middleware.addListener() and the separate addListener action creator. I wanted there to be some kind of difference in the naming scheme to avoid confusion.

Lenz and I started bikeshedding some naming ideas, and I laid out a list of some possibilities:

The main questions are:

What should we call the object returned from the create() function?

Related to this, Lenz isn't keen on having the examples destructure {middleware, addListener}, and would prefer something like obj.middleware instead

Lenz suggested renaming the main API to createListener(), so that you have listener.middleware, etc

Problem is that we've been referring to the actual callback functions as "listeners', so that would require coming up with a different name for those

We do want to differentiate between the "instance methods" for adding and removing entries, vs the action creators

If we were to go with createListener, then some options are:

methods:

add/remove

addX/removeX

attach/detach

subscribe/unsubscribe

actions:

addX/removeX

xAdded/yRemoved

subscribeListener/unsubscribeListener

field/functions:

listener

callback

effect

I put out a request for feedback on Twitter, but got no response. A week later I followed up with my own preferences:

Keep createListenerMiddleware. It makes it clear what we're doing, and it matches the createSagaMiddleware / createEpicMiddleware naming pattern from those libraries.

Keep the existing listener name for the function field

That means we just need to come up with a consistent name for the object returned from createListenerMiddleware that contains {middleware, addListener, removeListener}, and settle on a name for the action creators.

One option would be to give the action creators all "past tense" names: listenerAdded, listenerRemoved, listenersCleared. That sort of aligns with the "actions as events" mindset.... except that these aren't even actions that are meant to update state, they really are direct commands to the middleware itself. So, that slightly bothers me too. But it would at least give us a naming convention to distinguish the action creators from the instance methods.

I linked the comment over in Reactiflux and mentioned it on Twitter. This time, we actually got a good discussion going in the Reactiflux #redux channel.

A couple hours of intense debate followed, with numerous naming options thrown around. We finally settled on a naming scheme that had several changes:

API: createListenerMiddleware
return object: {middleware, startListening, stopListening, clearListeners}
Docs examples show the object as listenerMiddleware
One entry: "listener"
Field in that listener entry: effect
Action creators: addListener, removeListener, removeAllListeners

const listenerMiddleware = createListenerMiddleware();

listenerMiddleware.startListening({ type, effect });
listenerMiddleware.stopListening({ type, effect });

configureStore({
  middleware: (gDM) => gDM().prepend(listenerMiddleware.middleware),
});

const unsubscribe = store.dispatch(addListener({ type, effect }));

With all those names finalized, I went ahead and made the naming and return value changes and released it as v0.8.

Finalizing the Release

Moving the Source

The listener middleware had been published as a standalone @rtk-incubator/action-listener-middleware package this whole time, but the plan was always to move it over into the actual RTK package for a final release. I had originally planned to do that in RTK 1.8, and figured that 1.8 would also include several other changes (like new RTK Query options). But, after Lenz said he was busy and wouldn't have time to work on RTKQ for a while, I decided it was best to just release 1.8 with only the new listener middleware.

I threw together a PR that moved the middleware source over into the actual RTK package folder. At the same time, Faber filed a couple more PRs to tweak remaining edge cases, like the resolved promise value of child tasks.

Last-Minute Bugs

I wanted to make sure that the middleware was actually getting published correctly as part of the main RTK package. I use a tool called yalc that lets me do local "publishes" of WIP packages. This gives much more consistent and realistic behavior for testing packages than trying to do npm link.

All of our unit tests were passing, but to be realistic I figured it was worth installing the local RTK build into a real project. I set up a new Vite project and copy-pasted in the source for the "counter" example that Faber had added to the RTK repo.

This turned out to be a very smart decision, because the middleware was completely broken in the example app! I could add it to the store and call listenerMiddleware.startListening(), but none of the listener effects were running when I clicked buttons.

I tried debugging with the browser devtools. Somehow it looked like the debugger was hitting the line that looped over the available listener entries... but never actually checking to see if any of them should run.

At this point I was seriously confused. Fortunately, I had another trick up my sleeve. I had recently announced that I was joining Replay.io. Replay is a true "time-traveling debugger" - it lets you record app usage, and then investigate the app's behavior and execution at any point in that recording.

I recorded a replay of the counter app behavior and opened it up. I saw the same bizarre behavior where the loop body wasn't actually getting executed. I even pulled in Jason Laster, CEO of Replay to look at it, and he saw the same thing.

I finally happened to switch from looking at the sourcemapped view of the original code over to the transpiled view of what was actually being run by the browser.... and there I saw what was going on. The middleware used a JS Map internally to keep track of listener entries, and tried to use a for..of loop to loop over those entries for conditional checks. Somehow that loop's comparison was failing, and it truly wasn't stepping into the loop body.

Fortunately, I remembered that we'd seen the same bug a year earlier, and it turned out to be an ESBuild+TS transpilation issue . The workaround was easy, albeit annoying: copy the entries into an array first, then loop over that. (You can see the replay of the actual recorded bug here.)

Final Name and Behavior Changes

As I was getting ready to actually publish 1.8, I noted that middleware.clearListeners() cancelled any running instances, but middleware.stopListening() and dispatch(removeListener()) did not. I updated those to accept an optional {cancelActive?: true} parameter to enable cancellation upon removal.

Finally, Faber pointed out that the removeAllListeners action creator should be more distinct and consistent with the instance methods, so we renamed it to clearAllListeners instead.

And with that, I finally released the listener middleware live in RTK v1.8.0!.

Conclusions

When I filed the original issue in 2019, I had no idea that the process would take over two years, or that we'd end up effectively replacing sagas :) But, all the time, effort, iteration, and bikeshedding paid off, and I'm very happy with the final result.

Reception

I announced the release of RTK 1.8 on February 27 and also linked the release notes on Reddit. To be honest I actually didn't expect it to be that big a deal - I figured this was more of a niche API to begin with, so I wasn't expecting a big response.

To my very pleasant surprise, we've already gotten a bunch of very positive feedback. Some examples:

"I just cobbled up something that will replace a complete set of sagas and all their associated r-r boilerplate with a single small listener middleware. Ridiculously easy!"

"This is great 🙌. Listening to state changes is something I've been missing from thunks / sagas. If your actions are event-based and business logic is in the reducer, listening to actions is not enough."

"I literally am working on an app with where I need this feature (since I'm using RTK), I check my phone and I see this update. Mind blown. I will give this a shot."

"Quick shout out to you and your fellow RTK devs! I've just implemented the new listener middleware for a feature that persists specific slices of redux to indexedDB via Dexie, and it was practically painless. Listen for changes to the slice in a prev/next predicate, ignore it if it's the rehydrate action, fire a side effect that updates the changed property in indexedDB, and... it just works. The docs are clear and concise as usual, the syntax is easy to grasp, and it's easily as powerful as sagas or rxjs epics (at least how I've seen them used) without hardly any of the cognitive overhead. With this on top of RTK Query, I can finally get rid of all the clunky hard-to-test observables in this app and the weird actions firing actions firing actions spaghetti that's been built up over the last few years. Seriously, thank you so much. You've all made my job a lot easier."

This is extremely exciting as a maintainer - it tells me that the new API is solving the right use cases, and that the time and effort we put into it was worth it.

Key API Design Moments

Looking back, there were several key ideas and sources of inspiration that led to the final design:

The original vision of "provide callbacks that run in response to specific actions" was solid
"Add listeners at runtime with dispatch(addListener())" was also there at the beginning and was a key part of the design the entire way through
I had the idea for the (action, currState, prevState) => boolean "predicate" option right away, which turned out to enable running logic in response to state changes and not just actions
Lenz's second PR ultimately formed the basis of the rest of the implementation
The "run listeners before or after?" discussion led to adding getOriginalState, as well as the subscribe/unsubscribe methods
My interest in using the listener middleware in my work app prompted me to add matcher as an option, as well as extracting the existing PR code to work standalone and restarting the development work
Faber argued for dropping stopPropagation and when, which simplified the design, and also came up with all the error handling concepts
Shawn Swyx Wang suggested adding condition based on Temporal's API (and amusingly my implementation of condition(predicate, timeout?) prompted Temporal to rearrange their function's arguments order to match ours)
That led to me thinking about expanding the scope of the middleware to try to match saga capabilities, and investigating topics like promise cancellation and child task support
I had the idea for changing from positional parameters in addListener to an options object, but Lenz Weber and Josh DeGraw came up with the TS solutions that unblocked my attempt to rewrite the types
Faber suggested take and middleware.clearListeners, and rewrote the initial "jobs" API to provide similar cancellation behavior based on AbortController
Lenz and I investigated the const unsubscribe = dispatch(addListener()) TS issues. I was able to leverage my experience from Reselect 4.1 to rewrite the MiddlewareArray and getDefaultMiddleware types.
Multiple people participated in the final name bikeshedding discussion
I noted the lack of cancel-on-remove right at the end

Clearly, this was a very iterative process! The end result definitely fulfilled my original vision, but it was much more comprehensive than I could ever have imagined at the start.

Lessons and Takeaways

Hopefully this gives some insight into some of the process for designing a new library API.

I think there's several lessons that library maintainers can take away from this process:

Have a clear vision and purpose for the API: From the very beginning, I had a specific goal that I wanted this new API to accomplish. I saw a gap in RTK's functionality, and I specifically wanted to fill that gap. Additionally, while user feedback was absolutely critical (as discussed below), it was also important to keep the goals and implementation scoped and on track.
Design and discuss in public: Lenz and I did the bulk of the implementation work. However, many of the key design decisions only happened because of specific discussions with interested community members, as they described potential use cases and offered suggestions for API design and behavior. There's no way Lenz and I could have worked out the final design on our own - that back-and-forth discussion was critical, and that was only possible because we did the entire process in public from day 1. (That's not to say that internal discussions or design work are bad / should be avoided, but the more you can get the community involved, the better.)
Running code encourages discussion: Having a couple prototype PRs was critical. They gave us running examples to try out, and concrete code implementations to review and critique.
Get code in user hands ASAP, and iterate: Early on, having CodeSandbox CI set up to publish installable RTK packages from the PR branches made it possible for people to try out the initial builds. Later on, the use of a separate "incubator" package plus an ongoing Github Discussions thread helped us iterate on development and nail down the final behavior.
Tests and example use cases are valuable: The unit tests for the middleware served multiple purposes. Besides actual code coverage, they acted as "type tests" to verify the TS compilation behavior. We also added tests that demonstrated specific use cases, like implementing various Redux-Saga effects and some other example usage scenarios. This helped us verify that the API could do what we wanted, and gave us ideas for how to tweak things. (And in the case of the final pre-release checks, checking behavior in a real app helped me find a critical transpilation/publish bug.)

Of course other tools and communities will have different experiences. I can actually point to two other fairly contrasting experiences with React-Redux:

Before we started dev work on React-Redux v8, I wanted the codebase converted to TS. I created an issue asking for community participation and put out a call for help on Twitter, and over the next few weeks random community members helped convert the codebase a couple files at a time
On the other hand, when I moved on to reworked React-Redux v8 to support React 18, I did all the dev work for the useSyncExternalStore conversion myself, because I was the only one with the background knowledge and I knew what needed to be done.

As always, YMMV, but I think these principles can be useful for library maintainers that are looking to design new APIs.

Blogged Answers: The Evolution of Redux Testing Approaches

Tue, 22 Jun 2021 22:00:00 -0500

Introduction

I was just asked a question about how testing works for Redux applications:

For a beginner front-end developer, what would you expect them to know about Redux testing? (techniques and patterns specifically)

What - if any - tools are industry-standard for Redux testing? I've seen some tutorials using redux-mock-store, fetchMock, redux-testkit, redux-action-assertions, etc.

I ended up writing an extended response about the history of testing Redux apps, the two major styles of testing that I've seen, and how those approaches have evolved over time - clearly worthy of being reposted publicly.

Testing Redux

What should a beginning dev know about testing Redux?

For #1, I wouldn't necessarily expect a beginner to know much testing at all, really :) I actually just spent the last couple weeks helping guide a pair of interns through writing their first React component tests with React Testing Library, and it was a bit eye-opening when I had to explain so many different moving pieces: Jest, RTL, describe, it, jest.fn(), render(), expect(), and even just "write multiple tests that feed in different inputs, and check to see what the output is". It's not an easy or natural thing, and I'd kinda forgotten that.

All that said: the bare basic bit of testing I'd expect a beginner to be able to at least try or hopefully understand is testing reducers, because those are the simplest possible things to test: pure functions, whose entire logic depends on (state, action), and it's just expect(actual).toEqual(expected) in some way

What's standard for Redux testing?

For #2: this has varied a lot, and I think it's changed some over the last couple years.

The real question here is about how you test your Redux code. Do you test pieces in isolation? reducers, selectors, thunks, sagas, etc. Or do you test your Redux logic integrated into the rest of the app?

Our docs have always taught the "isolation" approach, and that does especially make sense for reducers and selectors. The "integration" approach was in a minority.

But, RTL and Kent C Dodds have drastically changed the mindset and approach for testing in the React ecosystem. The patterns I see now are about "integration"-style tests - large chunks of code, working together, as they'd be used in a real app.

These two approaches lead to very different styles of writing tests.

"Isolation"-style tests

With the "isolation" approach, again, writing tests for reducers and selectors is trivial - pure functions.

Testing thunks and components, on the other hand, got a lot more complicated.

redux-mock-store's primary purpose, as I understand it, is to collect a list of dispatched actions for later assertions: "yes, we did in fact dispatch todoAdded with this text", etc. That makes sense when you're testing things in isolation.

Testing thunks has always been really tricky for that approach, though. You have to configure the mock store with the thunk middleware. And what about any async calls? Thunks tend to directly import AJAX libs or client API layers - Angular-style DI has never been a big practice in the React ecosystem. So, that makes it harder to test thunks that make async calls. For that matter, thunks can dispatch other thunks too. So, testing dispatched actions is understandable here given those limitations.

The thunk middleware does have an "extra argument" that can be defined at middleware setup time, and that has been used for injecting some service layer for API calls that can be swapped with a mock version in tests.

This also gets very tricky when looking at components, especially when using the connect API with Enzyme. One of the reasons for the popularity of the "container/presentational" pattern is that it made it very easy to test presentational components. They're props-only, no logic other than formatting, no dependencies on any external APIs or behavior.

That concept is still a valid thing to do, but the React ecosystem has strongly moved away from "containers" thanks to hooks. I talked about this in my post Thoughts on React Hooks, Redux, and Separation of Concerns, and my talk ReactBoston 2019: Hooks, HOCs, and Tradeoffs.

connect does have an option to pass a Redux store instance directly as a prop named store. That works okay if you've only got one level of connected component being tested, but if you're doing an Enzyme mount(), which is a full render of the component tree, and there are other connected components in that subtree, they don't get access to the store correctly. So, you occasionally saw people creating real Redux stores and using a <Provider> in their component tests, but it was definitely a rarer thing

"Integration"-style tests

Well, that has flipped around over the last couple years with the arrival of RTL and hooks. Granted, I don't spend a lot of time reading other people's tests, and a lot of what I'm about to describe is my own experience working on some apps and working with other members of the Redux team. But, what I'm seeing is that "integration" style tests:

always create a real Redux store in a test and wrap the component under test in a <Provider>. Typically there's a customized render() function that wraps the RTL render method, accepts a store as an option or creates one internally if none was passed in, and automatically does the provider wrapping.
either fill the store in with fake data on creation, or dispatch some actions to load it up
don't care about what actions were dispatched - what matters is "I click the 'Add Todo' button, and another item shows up in the list"
mock async requests at the fetch/xhr level using tools like msw, miragejs, jest-mock-fetch, or similar. that way, none of the thunk logic has to change in a test - the thunk still tries to make a "real" async request, it just gets intercepted

Testing Sagas

I know that a number of people have chosen to use sagas specifically because they don't actually make real async requests in the saga function - it's just a stream of descriptions that the saga middleware is supposed to execute. in theory, that makes them much more testable.

having said that, I've seen discussions showing some annoyance with testing sagas, because you can effectively end up testing internal implementation details: "first it yields X, then it yields Y", etc.

I believe https://github.com/jfairbank/redux-saga-test-plan picked up some traction as a potentially better way to test sagas, but I haven't tried to do any of that myself

Recommendations

I can say that we did update the Redux docs "Testing" page to show more of an "integration"-type approach for testing connected components recently, although I think we ought to make that a bit more clear.

The couple projects I've been on in the last couple years haven't had tons of tests, but the integration-style approach seems to work out very well for us.

The new RTK Query APIs in Redux Toolkit are entirely "integration"-style tests, using MSW for all the API calls, and that's worked out fantastically well.

So. if you're going to teach anything, I'd say:

teach how to do basic tests for pure functions (reducers, selectors)
teach integration tests for everything working together (<Provider> + store wrapped around component, clicking a button does whatever real Redux logic, API calls are mocked out so app code doesn't have to change, assert UI is updated appropriately)

Presentations: Learn Modern Redux Livestream

Sat, 29 May 2021 16:00:00 -0500

This week I had the chance to appear on Jason Lengstorf's "Learn with Jason" livestream show.

The topic was "Learn Modern Redux". We started by recapping some of the usual topics ("what is Redux?", "why do some people dislike Redux?", "how has Redux changed?"), and then dove into live-coding a real Redux app. We showed how to create a new React+TS project using the Vite build tool (similar to Create-React-App), add the Redux packages, and set up Redux Toolkit and React-Redux from scratch (including our recommended TS hooks configuration).

We then showed how to use the upcoming RTK Query data fetching API to request a list of dog breeds from a public API, and display that data in our UI.

I had a blast being on this show, and I think it was a great chance to show folks how we recommend writing Redux code today.

The episode page on the "Learn with Jason" site has the embedded video, transcript, and show notes links:

Learn Modern Redux - episode page, video embed, and transcript

The example app is available as a live demo and the source is in a Github repo:

Running app: https://lets-learn-redux-toolkit.netlify.app/
Source code: https://github.com/learnwithjason/lets-learn-redux-toolkit

Presentations: The State of Redux, May 2021

Sat, 29 May 2021 16:00:00 -0500

I've done several prior iterations of my "State of Redux" talk, including:

I recently had a chance to record an updated version of the talk for an internal conference, and have posted the video for this one myself.

This iteration of the talk featured updates to the section on Redux Toolkit, an introduction to RTK Query, and info on how we recommend using Redux and TypeScript together.

The State of Redux, May 2021 - video

The State of Redux, May 2021 - slides

Presentations: Podcast Appearances in 2021

Sat, 29 May 2021 15:00:00 -0500

Intro

As with last year, I've continued to get a number of invites to appear as a guest on various podcasts.

I'll link them chronologically.

March: React Roundup

First off for this year was the React Roundup podcast. We covered most of the usual topics like "Redux isn't dead" and "RTK is useful", as well as how I got into open source and my goal of creating a "React community tools and practices" site to help provide ecosystem guidance:

React Roundup 135: Redux, Redux Toolkit, OSS and More with Mark Erikson

March: FullStack Jam

This discussion covered many of the usual topics: Redux's usage and current status, how Redux Toolkit makes using Redux easier, and how RTK Query simplifies data fetching:

FSJam 40: Redux Toolkit with Mark Erikson

March: State of the React Ecosystem

A panel vidcast where several React ecosystem library maintainers were able to talk about what's new and upcoming with their tools:

State of the React Ecosystem (March 2021)

May: PodRocket

I appeared on LogRocket's podcast, and we had some great discussions about the value of Redux, what's in RTK, tradeoffs of using Immer, when it makes sense to use Redux, why people keep claiming Redux is dead, and how people should approach writing new tutorials for tools that already have docs and an ecosystem:

PodRocket: Redux is alive and well, with Mark Erikson

December: Scrimba Podcast

A nice discussion about career-related topics, including thoughts on searching for info online and dealing with programming errors.

Career advice from the maintainer of Redux, Mark Erikson

Blogged Answers: Why React Context is Not a "State Management" Tool (and Why It Doesn't Replace Redux)

Mon, 18 Jan 2021 10:00:00 -0500

Introduction

"Context vs Redux" has been one of the most widely debated topics within the React community ever since the current React Context API was released. Sadly, most of this "debate" stems from confusion over the purpose and use cases for these two tools. I've answered various questions about Context and Redux hundreds of times across the internet (including my posts Redux - Not Dead Yet!, React, Redux, and Context Behavior, A (Mostly) Complete Guide to React Rendering Behavior, and When (and when not) to Reach for Redux), yet the confusion continues to get worse.

Given the prevalence of questions on this topic, I'm putting together this post as a definitive answer to those questions. I'll try to clarify what Context and Redux actually are, how they're meant to be used, how they're different, and when you should use them.

TL;DR

Are Context and Redux the same thing?

No. They are different tools that do different things, and you use them for different purposes.

Is Context a "state management" tool?

No. Context is a form of Dependency Injection. It is a transport mechanism - it doesn't "manage" anything. Any "state management" is done by you and your own code, typically via useState/useReducer.

Are Context and `useReducer` a replacement for Redux?

No. They have some similarities and overlap, but there are major differences in their capabilities.

When should I use Context?

Any time you have some value that you want to make accessible to a portion of your React component tree, without passing that value down as props through each level of components.

When should I use Context and `useReducer`?

When you have moderately complex React component state management needs within a specific section of your application.

When should I use Redux instead?

Redux is most useful in cases when:

You have larger amounts of application state that are needed in many places in the app
The app state is updated frequently over time
The logic to update that state may be complex
The app has a medium or large-sized codebase, and might be worked on by many people
You want to be able to understand when, why, and how the state in your application has updated, and visualize the changes to your state over time
You need more powerful capabilities for managing side effects, persistence, and data serialization

Understanding Context and Redux

In order to use any tool correctly, it's critical to understand:

What its purpose is
What problems it's trying to solve
When and why it was originally created

It's also critical to understand what problems you are trying to solve in your own application right now, and pick the tools that solve your problem the best - not because someone else said you should use them, not because they’re popular, but because this is what works best for you in this particular situation.

Most of the confusion over "Context vs Redux" stems from a lack of understanding about what these tools actually do, and what problems they solve. So, in order to actually know when to use them, we need to first clearly define what they do and what problems they solve.

What is React Context?

Let's start by looking at the actual description of Context from the React docs:

Context provides a way to pass data through the component tree without having to pass props down manually at every level.

In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like these between components without having to explicitly pass a prop through every level of the tree.

Notice that it does not say anything about "managing" values - it only refers to "passing" and "sharing" values.

The current React Context API (React.createContext()) was first released in React 16.3. It replaced the legacy context API, which had been available since early versions of React, but had major design flaws. The primary problem with legacy context was that updates to values passed down via context could be "blocked" if a component skipped rendering via shouldComponentUpdate. Since many components relied on shouldComponentUpdate for performance optimizations, that made legacy context useless for passing down plain data. createContext() was designed to solve that problem, so that any update to a value will be seen in child components even if a component in the middle skips rendering.

Using Context

Using React Context in an app requires a few steps:

First, call const MyContext = React.createContext() to create a context object instance
In a parent component, render <MyContext.Provider value={someValue}>. This puts some single piece of data into the context. That value could be anything - a string, a number, an object, an array, a class instance, an event emitter, and so on.
Then, in any component nested inside that provider, call const theContextValue = useContext(MyContext).

Whenever the parent component re-renders and passes in a new reference to the context provider as the value, any component that reads from that context will be forced to re-render.

Most commonly, the value for a context is something that comes from React component state, along these lines:

function ParentComponent() {
  const [counter, setCounter] = useState(0);

  // Create an object containing both the value and the setter
  const contextValue = {counter, setCounter};

  return (
    <MyContext.Provider value={contextValue}>
      <SomeChildComponent />
    </MyContext.Provider>
  )
}

A child component then can call useContext and read the value:

function NestedChildComponent() {
  const { counter, setCounter } = useContext(MyContext);

  // do something with the counter value and setter
}

Purpose and Use Cases for Context

Based on that, we can see that Context doesn't actually "manage" anything at all. Instead, it's like a pipe or a wormhole. You put something in the top end of the pipe using the <MyContext.Provider>, and that one thing (whatever it is) goes down through the pipe until it pops out the other end where another component asks for it with useContext(MyProvider).

So, the primary purpose for using Context is to avoid "prop-drilling". Rather than pass this value down as a prop, explicitly, through every level of the component tree that needs it, any component that's nested inside the <MyContext.Provider> can just say useContext(MyContext) to grab the value as needed. This does simplify the code, because we don't have to write all the extra prop-passing logic.

Conceptually, this is a form of "Dependency Injection". We know that the child component needs a value of a certain type, but it doesn't try to create or set up that value itself. Instead, it assumes that some parent component will pass down that value, at runtime.

What is Redux?

For comparison, let's look at the description from the "Redux Essentials" tutorial in the Redux docs:

Redux is a pattern and library for managing and updating application state, using events called "actions". It serves as a centralized store for state that needs to be used across your entire application, with rules ensuring that the state can only be updated in a predictable fashion.

Redux helps you manage "global" state - state that is needed across many parts of your application.

The patterns and tools provided by Redux make it easier to understand when, where, why, and how the state in your application is being updated, and how your application logic will behave when those changes occur.

Note that this description:

specifically refers to "managing state"
says that the purpose of Redux is to help you understand how state changes over time

Historically, Redux was originally created as an implementation of the "Flux Architecture", which was a pattern first suggested by Facebook in 2014, a year after React came out. Following that announcement, the community created dozens of Flux-inspired libraries with varying approaches to the Flux concepts. Redux came out in 2015, and quickly won the "Flux Wars" because it had the best design, matched the problems people were trying to solve, and worked great with React.

Architecturally, Redux emphasizes using functional programming principles to help you write as much of your code as possible as predictable "reducer" functions, and separating the idea of "what event happened" from the logic that determines "how the state updates when that event happens". Redux also uses middleware as a way to extend the capabilities of the Redux store, including handling side effects.

Redux also has the Redux Devtools, which allow you to see the history of actions and state changes in your app over time.

Redux and React

Redux itself is UI-agnostic - you can use it with any UI layer (React, Vue, Angular, vanilla JS, etc), or without any UI at all.

That said, Redux is most commonly used with React. The React-Redux library is the official UI binding layer that lets React components interact with a Redux store by reading values from Redux state and dispatching actions. So, when most people refer to "Redux", they actually mean "using a Redux store and the React-Redux library together".

React-Redux allows any React component in the application to talk to the Redux store. This is only possible because React-Redux uses Context internally. However, it's critical to note that React-Redux only passes down the Redux store instance via context, not the current state value!. This is actually an example of using Context for dependency injection, as mentioned above. We know that our Redux-connected React components need to talk to a Redux store, but we don't know or care which Redux store that is when we define the component. The actual Redux store is injected into the tree at runtime using the React-Redux <Provider> component.

Because of this, React-Redux can also be used to avoid prop-drilling, specifically because React-Redux uses Context internally. Instead of explicitly putting a new value into a <MyContext.Provider> yourself, you can put that data into the Redux store and then access it anywhere.

Purposes and Use Cases for (React-)Redux

The primary reason to use Redux is captured in the description from the Redux docs:

The patterns and tools provided by Redux make it easier to understand when, where, why, and how the state in your application is being updated, and how your application logic will behave when those changes occur.

There are additional reasons why you might want to use Redux. "Avoiding prop-drilling" is one of those other reasons. Many people chose Redux early on specifically to let them avoid prop-drilling, because React's legacy context was broken and React-Redux worked correctly.

Other valid reasons to use Redux include:

Wanting to write your state management logic completely separate from the UI layer
Sharing state management logic between different UI layers (such as an application that is being migrated from AngularJS to React)
Using the power of Redux middleware to add additional logic when actions are dispatched
Being able to persist portions of the Redux state
Enabling bug reports that can be replayed by developers
Faster debugging of logic and UI while in development

Dan Abramov listed a number of these use cases when he wrote his post You Might Not Need Redux, all the way back in 2016.

Why Context is Not "State Management"

"State" is any data that describes the behavior of an application. We could divide that into categories like "server state", "communications state", and "location state" if we want to, but the key point is that there is data being stored, read, updated, and used.

David Khourshid, author of the XState library and an expert on state machines, said:

"State management is how state changes over time."

Based on that, we can say that "state management" means having ways to:

store an initial value
read the current value
update a value

There's also typically a way to be notified when the current value has changed.

React's useState and useReducer hooks are good example of state management. With both of those hooks, you can:

store an initial value by calling the hook
read the current value, also by calling the hook
update the value by calling the supplied setState or dispatch function
Know that the value has been updated because the component re-rendered

Similarly, Redux and MobX are clearly state management as well:

Redux stores an initial value by calling the root reducer, lets you read the current value with store.getState(), updates the value with store.dispatch(action), and notifies listeners that the store updated via store.subscribe(listener)
MobX stores an initial value by assigning field values in a store class, lets you read the current value by accessing the store's fields, updates values by assigning to those fields, and notifies that changes happened via autorun() and computed()

We can even say that server caching tools like React-Query, SWR, Apollo, and Urql fit the definition of "state management" - they store initial values based on the fetched data, return the current value via their hooks, allow updates via "server mutations", and notify of changes via re-rendering the component.

React Context does not meet those criteria. Therefore, Context is not a "state management" tool!

As we established earlier, Context does not "store" anything itself. The parent component that renders a <MyContext.Provider> is responsible for deciding what value is passed into the context, and that value typically is based on React component state. The actual "state management" is happening with the useState/useReducer hook.

As David Khourshid also said:

Context is how state (that exists somewhere already) is shared with other components.

Context has little to do with state management.

Or, as a recent tweet put it:

I guess Context is more like hidden props than abstracted state.

Think of it this way. We could have written the exact same useState/useReducer code, but prop-drilled the data and the update function down through the component tree. The actual behavior of the app would have been the same overall. All Context does for us is let us skip the prop-drilling.

Comparing Context and Redux

Let's review what capabilities Context and React+Redux actually have:

Context
- Does not store or "manage" anything
- Only works in React components
- Passes down a single value, which could be anything (primitive, objects, classes, etc)
- Allows reading that single value
- Can be used to avoid prop-drilling
- Does show the current context value for both Provider and Consumer components in the React DevTools, but does not show any history of how that value changed over time
- Updates consuming components when the context value changes, but with no way to skip updates
- Does not include any mechanism for side effects - it's purely for rendering components
React+Redux
- Stores and manages a single value (which is typically an object)
- Works with any UI, including outside of React components
- Allows reading that single value
- Can be used to avoid prop-drilling
- Can update the value via dispatching an action and running reducers
- Has DevTools that show the history of all dispatched actions and state changes over time
- Uses middleware to allow app code to trigger side effects
- Allows components to subscribe to store updates, extract specific pieces of the store state, and only re-render when those values change

So, clearly these are very different tools with different capabilities. The only overlap between them, really, is "can be used to avoid prop-drilling".

Context and `useReducer`

One problem with the "Context vs Redux" discussions is that people often actually mean "I'm using useReducer to manage my state, and Context to pass down that value". But, they never state that explicitly - they just say "I'm using Context". That's a common cause of the confusion I see, and it's really unfortunate because it helps perpetuate the idea that Context "manages state".

So, let's talk about the Context + useReducer combination specifically. Yes, Context + useReducer does look an awful lot like Redux + React-Redux. They both have:

A stored value
A reducer function
dispatching of actions
a way to pass down that value and read it in nested components

However, there's still a number of very significant differences in the capabilities and behaviors of Context + useReducer vs those of Redux + React-Redux. I covered the key points in my posts React, Redux, and Context Behavior and A (Mostly) Complete Guide to React Rendering Behavior. Summarizing here:

Context + useReducer relies on passing the current state value via Context. React-Redux passes the current Redux store instance via Context.
That means that when useReducer produces a new state value, all components that are subscribed to that context will be forced to re-render, even if they only care about part of the data. This may lead to performances issues, depending on the size of the state value, how many components are subscribed to that data, and how often they re-render. With React-Redux, components can subscribe to specific pieces of the store state, and only re-render when those values change.

In addition, there's some other important differences as well:

Context + useReducer are React features, and therefore cannot be used outside of React. A Redux store is independent of any UI, and so it can be used separate from React.
The React DevTools allow viewing the current context value, but not any of the historical values or changes over time. The Redux DevTools allow seeing all actions that were dispatched, the contents of each action, the state as it existed after each action was processed, and the diffs between each state over time.
useReducer does not have middleware. You can do some side-effect-y things with useEffect in combination with useReducer, and I've even seen some attempts to wrap useReducer with something that resembles a middleware, but both of those are severely limited in comparison to the functionality and capabilities of Redux middleware.

It's worth repeating what Sebastian Markbage (React core team architect) said about the uses for Context:

My personal summary is that new context is ready to be used for low frequency unlikely updates (like locale/theme). It's also good to use it in the same way as old context was used. I.e. for static values and then propagate updates through subscriptions. It's not ready to be used as a replacement for all Flux-like state propagation.

There's a lot of posts out there that recommend setting up multiple separate contexts for different chunks of state, both to cut down on unnecessary re-renders and to scope concerns. Some of those also suggest adding your own "context selector components", which require a mixture of React.memo(), useMemo(), and carefully splitting things up so there's two separate contexts for each segment of state (one for the data, and one for the updater functions). Sure, it's possible to write code that way, but at that point you're just reinventing React-Redux, poorly.

So, even though Context + useReducer sorta-resemble Redux + React-Redux at a quick glance... they are not fully equivalent and cannot truly replace Redux!

Choosing the Right Tool

As I said earlier, it's critical to understand what problems a tool solves, and know what problems you have, in order to correctly choose the right tool to solve your problems.

Use Case Summary

Let's recap the use cases for each of these:

Context:
- Passing down a value to nested components without prop-drilling
useReducer
- Moderately complex React component state management using a reducer function
Context + useReducer:
- Moderately complex React component state management using a reducer function, and passing that state value down to nested components without prop-drilling
Redux
- Moderate to highly complex state management using reducer functions
- Traceability for when, why, and how state changed over time
- Wanting to write your state management logic completely separate from the UI layer
- Sharing state management logic between different UI layers
- Using the power of Redux middleware to add additional logic when actions are dispatched
- Being able to persist portions of the Redux state
- Enabling bug reports that can be replayed by developers
- Faster debugging of logic and UI while in development
Redux + React-Redux
- All of the use cases for Redux, plus interacting with the Redux store in your React components

Again, these are different tools that solve different problems!

Recommendations

So, how do you decide whether to use Context, Context + useReducer, or Redux + React-Redux?

You need to determine which of these tools best matches the set of problems that you're trying to solve!

If the only thing you need to do is avoid prop-drilling, then use Context
If you've got some moderately complex React component state, or just really don't want to use an external library, go with Context + useReducer
If you want better traceability of the changes to your state over time, need to ensure that only specific components re-render when the state changes, need more powerful capabilities for managing side effects, or have other similar problems, use Redux + React-Redux

My personal opinion is that if you get past 2-3 state-related contexts in an application, you're re-inventing a weaker version of React-Redux and should just switch to using Redux.

Another common concern is that "using Redux means too much 'boilerplate'". Those complaints are very outdated, as "modern Redux" is significantly easier to learn and use than what you may have seen before. Our official Redux Toolkit package eliminates those "boilerplate" concerns, and the React-Redux hooks API simplifies using Redux in your React components. As one user recently told me:

We just switched from context and hooks over to RTK on one of our production application's frontends. That thing processes a little over $1B/year. Fantastic stuff in the toolkit. The RTK is the polish that helped me convince the rest of the teams to buy into the refactor. I also did a boilerplate analysis for that refactor and it's actually LESS boilerplate to use the RTK than it is to use the recommended dispatch pattern in contexts. Not to mention how much easier it is to process data.

Yes, adding RTK and React-Redux as dependencies does add additional byte size to your application bundle over just Context + useReducer, because those are built in to React. But, the tradeoffs are worth it - better state traceability, simpler and more predictable logic, and improved component rendering performance.

It's also important to point out that these are not mutually exclusive options - you can use Redux, Context, and useReducer together at the same time! We specifically encourage putting "global state" in Redux and "local state" in React components, and carefully deciding whether each piece of state should live in Redux or component state. So, you can use Redux for some state that's global, and useReducer + Context for some state that's more local, and Context by itself for some semi-static values, all at the same time in the same application.

To be clear, I'm not saying that all apps should use Redux, or that Redux is always a better choice! There's many nuances to this discussion. I am saying that Redux is a valid choice, there are many reasons to choose Redux, and the tradeoffs for choosing Redux are a net win more often than many people think.

And finally, Context and Redux are not the only tools to think about. There's many other tools out there that solve other aspects of state management in different ways. MobX is another widely used option that uses OOP and observables to automatically update data dependencies. Jotai, Recoil, and Zustand offer lighter-weight state update approaches. Data fetching libraries like React Query, SWR, Apollo, and Urql all provide abstractions that simplify common patterns for working with cached server state (and the upcoming "RTK Query" library will do the same for Redux Toolkit). Again, these are different tools, with different purposes and use cases, and are worth evaluating based on your use case.

Final Thoughts

I realize that this post won't stop the seemingly never-ending debate over "Context vs Redux?!?!?!?!?". There's too many people out there, too many conflicting ideas, and too much miscommunication and misinformation.

Having said that, I hope that this post has clarified what these tools actually do, how they're different, and when you should actually consider using them. (And maybe, just maybe, some folks will read this article and not feel the need to post the same question that's been asked a million times already...)

Further Information

Context Purpose and Design
Redux Purpose and Design
Differences between Redux and Context
- React, Redux, and Context Behavior
- A (Mostly) Complete Guide to React Rendering Behavior
When should I use Redux?
Other Redux and Context Comparison Discussions

Mark's Dev Blog

Presentations: Maintaining a Library and a Community

React Summit US 2024

NDC Oslo 2025

React Advanced 2024: Designing Effective Documentation

React Summit 2024: Why Use Redux Today?

React Summit US 2023: What's New in Redux Toolkit 2.0

React Rally 2023 - A (Brief) Guide to React Rendering Behavior

React Rally 2023

React Advanced 2022

Presentations: 2022 Podcasts

ThisDot / Tracy Lee: How to Contribute to Redux

Kevin Ghadyani: Redux vs React Context

PodRocket: Time-Travel Debugging with Replay (with Jason Laster)

Guild Community Tour: Mark Erikson

Peerlist: The Mindset of a Redux Maintainer

20 Minute JS: Redux Toolkit and State Management in React

React Native Radio: A Redux Maintainer's Thoughts on Redux Toolkit vs Mobx-State-Tree

Merged: Leading Tech Communities

Reactiflux Office Hours: Lenz Weber-Tronic and Mark Erikson

Blogged Answers: How I Estimate NPM Package Market Share (and how Redux usage compares to other libraries)

Introduction

Primary Source: NPM Package Download Stats

NPM Package Stats Sources

NPMJS.com

NPM Download Comparison Tools

Alternate Stat Sources

Github Dependency Lists

Online Polls and Social Media Discussions

Caveats with Package Stats and Sources

NPM Download Stats Flaws

Other Caveats and Concerns

Estimating React State Management Market Share

Comparing NPM Stats

Comparing Github Dependents

Poll Results

Conclusions

React's Growth Continues

Redux is Still Number One In State Management

Redux's Total Market Share has Dropped vs React

Wishlist

Final Thoughts

Presentations: Modern Redux with Redux Toolkit

Reactathon 2022: The Evolution of Redux Async Logic

Idiomatic Redux: Designing the Redux Toolkit Listener Middleware

Intro

Why Create a New Middleware?

Background: Redux Side Effects Approaches

Redux Toolkit and Thunks

Concerns with Sagas and Observables

Original Inspiration

Initial Design and Implementation Ideas

Second PR and Use Case Bikeshedding

Initial PR Contents

PR Iteration and Brainstorming

Stalemate

Restarting the Development Effort

Extracting a Standalone Implementation

Creating a New Incubator Package

Updating the Design Goals

Shaping the API

v0.2: Finding the Right Primitives

v0.3: Fixing Listener Syntax and Types

v0.4: "Child Job" Support

v0.5: "Tasks" and AbortController

Polish and Refinement

v0.6: Simplifying Behavior

v0.7: Cleanup Improvements

TypeScript Issues

v0.8: Bikeshedding Naming!

Finalizing the Release

Moving the Source

Last-Minute Bugs

Final Name and Behavior Changes

Conclusions

Reception

Key API Design Moments

Lessons and Takeaways

Blogged Answers: The Evolution of Redux Testing Approaches

Introduction

v0.5: "Tasks" and `AbortController`

Are Context and `useReducer` a replacement for Redux?

When should I use Context and `useReducer`?

Context and `useReducer`