Time Travel Debugging your Recoil App with Recoilize

So you’ve learned a little bit about Recoil, the new state management library from Facebook. And now you’re ready to start building some apps using Recoil. How can you better observe how your Recoil apps are working as you develop an understanding of the library? Aren’t you going to miss your beloved Redux devtools, and your favorite feature, time travel? In this article we will discuss your solution; Recoilize, a powerful dev tool for Recoil apps. We will describe how to integrate Recoilize into your app and how to use its time travel feature.

What is Recoil?

Recoil is an experimental state management library built for React applications by the React team at Facebook. Recoil provides global state to your application and makes the data flow more flexible, and re-renders more efficient than with Redux or the Context API.

In a Recoil Application data flow begins at an Atom, which is a unit of state. Atoms can be subscribed to by any number of individual React components. When an atom is updated, each component that is subscribed to it is re-rendered with the updated value.

If data needs to be further derived from the atom, a Selector is used. Selectors are similar to Atoms in that they can be subscribed to by individual components, and those components will be updated when a Selector’s parent Atom is updated. The difference being that a Selector is a pure function accepting an atom as an input. Selectors derive new data from already existing units of state.

Recoil has the advantage of more efficient re-renders. This is because only components subscribed to Atoms or Selectors who’s value was updated on a state changing event, will be re-rendered.


Recoilize is a chrome dev tool built specifically for applications managing state with Recoil. It works by recording snapshots after every state changing event and saving these snapshots. This makes it possible to inspect the state presently in your app, view state at any previous moment, or even time travel back to a previous application state without reloading the page or restarting the app.

Recoilize is available from the Google Chrome Store and must be downloaded to be used. The RecoilizeDebugger is also a React component, thus it is actually embed into your React app. In this article we’ll describe how to do just that.

If you aren’t yet up to speed on using Recoil, take a look at Bren Yamaguchi’s article on its ins and outs.

Implementing Recoilize

Recoilize is available as an npm package. Begin by installing it as a dependency in your React/Recoil application.

Next, locate the file containing your Recoil Root. The Recoil Root is a React component that marks the beginning of your Recoil application. Add an import statement to this file importing RecoilizeDebugger from the recoilize package.

Import RecoilizeDebugger from recoilize module.

RecoilizeDebugger is a React component, and should be incorporated into your code immediately within the RecoilRoot component.

RecoilIzeDebugger component wrapped by RecoilRoot component.

Under the hood Recoilize utilizes the root HTML element of your React application. This is the element that your React application is injected into. It is common practice for this element to have an ID of ‘root’, and if your are using create-react-app this element will have the ID of ‘root’ out of the box. It is important to note that Recoilize will assume this is the case and will try to find it by selecting the DOM element with an ID of ‘root’.

Passing alternatively named root HTML element into RecoilizeDebugger component

Once Recoilize is downloaded from the Google Chrome Web Store and the RecoilizeDebugger component has been imbedded you’re ready to try it out in the browser.

Using Snapshots

Recoilize makes time travel debugging easy. When you fire up the chrome extension you’ll see a snapshot list on the left side. Each snapshot shows a snapshot number, the time it took to render the application following a state changing event, and a jump button.

Snapshots representing an instance of state.

Each time a new state changing event takes place, a new snapshot is added to the list.

A new snapshot is recorded with each state change.

To the right of the snapshot list Recoilize provides many tools to describe your application at the current snapshot. Recoilize displays, among other things, the changes to state since the previous snapshot, the entire application state as a JSON tree, atom selector relationships, and the react component tree. By clicking on a previous snapshots you can view this information at any moment in time throughout your applications life.

This ability to look at the details of your application throughout time is valuable for ensuring state values are updated as you expect them too on state changing events, and also of critical importance when working through bugs that arise from complicated multi step processes.

Time Travel

“But I thought you said Time Travel? This isn’t Time Travel.”

What if instead of simply viewing the state of your application throughout time you want to actually revert your application back to a previous instance of state? Perhaps you have a complex bug arising from multiple state changing events happening in sequence. And you want to go back to the step before it began to recreate the bug. Enter the Jump button.

As you click through the snapshots and view previous instances of application state, you can click the “Jump” button on any snapshot and the app will Time Travel back to that instance of state. Atoms, selectors and corresponding components will all reverted to the state they were in at said snapshot.

The Jump buttons reverts the application to a previous state instance.

This allows the user to step through complex bugs as many times as they like, giving them a chance to view how different aspects of the application update with each state changing event.


In this article we have seen how Recoilize can be implemented into your Recoil app, and how it can be used to not only view previous instances of state, but also time travel your application back to a previous instance.

It was the goal of the Recoilize team to build powerful dev tools for users of a new and exciting state management library, Recoil, and to make them easy to implement and use. Time travel is just one feature Recoilize provides. Download the extension and give it a try on your next application to see the rest.

For more information on the Recoilize dev tool visit us at recoilize.io and if you like what we’re doing over here at Recoilize be sure to give us some stars on the Google Chrome Web Store and GitHub!

Learning, growth and code. Exciting stuff.