Recoil: A New State Management Library Moving Beyond Redux and the Context API

A full introduction to Recoil, an experimental state management library for React applications

Recoil data-flow graph for state management — Photo by the author.

Available since May 2015, Redux is a predictable state container for JavaScript applications. It is a single source of truth, its state is read-only, and changes are made with pure functions. Redux has a nice browser debugging extension for easy debugging. The drawback is the complex boilerplate to start with. It may not be compatible with React’s upcoming concurrent mode.

Context API was introduced by React 16.3 in May 2018. Along with React Hooks (useContext), it provides a way to pass data through the React component tree without having to pass props down manually at every level. It is designed to share global data, such as the current authenticated user, theme, or preferred language. Context API and React Hooks provide a new approach to state management. Debugging is hard and there are performance issues when rendering multiple dynamic items.

So should you go with Redux or Context API?

After a couple of years of battle, with many articles announcing Redux is dead, not dead yet, etc., both are alive and adopted by many applications. There is no clear winner yet.

The following is an NPM trend comparison. Both of them are still in heavy use:

Now we have a newcomer.

Recoil is a brand new experimental JavaScript state management library developed by Facebook. It has been available since May 2020.

Problem Addressed

Recoil addresses many of the problems larger applications encounter when using the existing Context API:

The component state can only be shared by pushing it up to the common ancestor, but this might include a huge tree that then needs to re-render.
Context can only store a single value — not an indefinite set of values, each with its own consumers.
Both of these make it challenging to code-split the top of the tree (where the state has to live) from the leaves of the tree (where the state is used).

Recoil defines a directed graph orthogonal, but it is also intrinsic and attached to the React component tree (see the Recoil data-flow graph at the top). In this data-flow graph, state changes flow from the roots of the graph (atoms) through pure functions for derived states (selectors) and into components.

With this architecture design, Recoil uses a React-style solution to resolve Context API issues. This solution is easy to use, with the possibility of compatibility with concurrent mode and other new React features as they become available. In addition, more advanced debugger options are on the way, such as time-traveling, undo capability, persistent data, etc.

Recoil Setup

Let’s see how Recoil works in Create React App (npx create-react-app my-app). First, install Recoil with the command npm i recoil. Then the package becomes part of dependencies in package.json:

"dependencies": {
  "recoil": "0.1.2"
}

Change src/App.css to this for minimal styling:

Components that use Recoil hooks must be wrapped with <RecoilRoot>. In the following src/index.js, add RecoilRoot on lines 10 and 12:

Now we are ready to see Recoil examples.

Atoms

We want to create the following user interface. It shows the initial state 0. Each click of the Increase button will increase the count by one, and each click of the Decrease button will decrease count by one.

We can use useState to achieve this in src/App.js:

Now we use Recoil’s atom to do the same user interface. The atom, countState, is defined on lines 5-8. It is used by line 11. That’s it.

What is an atom?

It is a shared, writable, Recoil state that includes a piece of data that it manages. Components can subscribe to atoms and will then be re-rendered when related atoms change.

An atom has two props:

key: A string used to identify the atom internally. This string should be unique with respect to other atoms and selectors in the entire application.
default: The initial value of an atom.

The following are hooks that interact with atoms:

useRecoilState(): This hook is used to read and write to an atom. It subscribes the calling components to the atom.
useRecoilValue(): This hook is used to read an atom. It subscribes the calling components to the atom.
useSetRecoilState(): This hook is used to write to an atom.
useResetRecoilState(): This hook is used to reset an atom to its default value.
useRecoilCallback(): This hook is used to construct a callback that can read an atom and asynchronously update it.

Selectors

Atoms work well to store states. Selectors are pure functions used to calculate derived states. Selectors avoid redundant states, usually obviating the need for reducers to keep states in sync and valid.

The proper design is to use atoms to store a minimal set of states, while everything else is efficiently computed as a function of atoms. Components can subscribe to selectors just like atoms and will then be re-rendered when selector-derived states change.

What is a selector? According to the official documentation:

“A selector is a pure function that accepts atoms or other selectors as input. When these upstream atoms or selectors are updated, the selector function will be re-evaluated.”

A selector has these props:

key: A string used to identify the atom internally. This string should be unique with respect to other atoms and selectors in the entire application.
get: A function that is passed as an object, { get }, where get is a function to retrieve values from other atoms or selectors. All atoms or selectors passed to this function will be implicitly added to a list of dependencies for the selector.
set?: An optional function that returns a new writeable state. It is passed as an object, { get, set }, and a new value. get is a function to retrieve values from other atoms or selectors. set is a function to set an atom value, where the first parameter is the atom name and the second parameter is the new value.

We add a selector to generate derived state in src/App.js:

The selector on lines 10-13 defines the derived doubleCountState, which is used by line 17. This value is displayed as double count value on line 23.

Optionally, selectors can set atom values. We add an input field in the user interface. It reflects the doubleCountState selector state. When it gets a user input, this new value is set to the countState atom state.

Here is an example in src/App.js:

The selector on lines 15-19 defines the derived inputState, which is used by line 24. Its value is the same as the selector’s: doubleCountState (defined on line 17).

When a user changes the input value, onChange (line 29) will invoke setInput (line 24) and then set the countState atom (line 18). The atom change will cause the re-rendering of every related value.

Asynchronous Selectors

Recoil provides a way to map states (atoms) and derived states (selectors) to React components via a data-flow graph. What if the get functions in selectors are asynchronous? It works the same way as the synchronous data flow. Simply make the get function return a promise to a value.

Here is the revised src/App.js:

On lines 12-18, we rewrite the get function to return a promise. Everything else remains the same.

In fact, if you replace lines 12-18 with the following snippet to wait for the promise, it works too:

Wait a minute. Run npm start, and we encounter this error:

RecoilRoot requires a fallback user interface for asynchronous selectors. We add it to src/index.js on lines 12 and 14:

Now, it works!

It is always a good idea to have an ErrorBoundary (lines 11 and 15) when things go dynamic. How to create an error boundary is detailed in a previous article.

Recoil ESLint

Are you using eslint-plugin-react-hooks in your project? If yes, it is recommended to add useRecoilCallback to the list of additionalHooks (line 9).

Conclusion

Recoil is the latest state management library provided by Facebook. Although it is still experimental, it shows a lot of promising features to replace Context API for state management.

We have been using Recoil for a while. It is easy to use, and allows us to share states across multiple components/files, using syntax as simple as useState. This storybook includes a few examples using Recoil.

The states of atoms and selectors can be defined or undefined, primitives values, or object values. The values of selectors are automatically derived from atoms or other selectors.

There are also various ways to structure atoms and selectors. They can be grouped into one file, or classified into a few files, depending on the programming logic. Recoil provides freedom from existing technical constraints.

Happy coding!

Thanks for reading. I hope this was helpful. You can see my other Medium publications here.

Note: Jonathan Ma contributed to part of this article.