ReactInDepth is moving away from Medium. This article, its updates and more recent articles are hosted on the new platform inDepth.dev

I don’t want to dig too deep into the technical details of React Suspense and how it works under the hood, there are already plenty great blog posts, videos and conference talks out there that do that. Instead I want to focus more on the impact Suspense will have on us application developers in the way we think about loading states and architecture our apps.

Still, a brief technical introduction

To get everyone who hasn’t heard about Suspense or doesn’t really know what it is on board, I still want to give at least a summary of what all this fuzz is about.

Introduced at JSConf Iceland by Dan Abramov last year, Suspense was pitched as an improvement to the developer experience when dealing with asynchronous data fetching within React apps. This is a huge deal, because everyone who is building dynamic web applications knows that this is still one of the major pain points and one of the things that brings huge boilerplates with it.

Suspense is also supposed to transform the way we think about loading states, which shouldn’t be coupled to the fetching component or data source, but rather a UI concern. Our apps should show spinners where it makes most sense in context of the user experience. Suspense helps doing so by decoupling these concerns for us.

Dan Abramov on Twitter

@AdamRackis Suspense doesn't care why (or how many times) you suspend, so a single spinner can work for a combination of code splitting, data fetching, image loading, etc. Whatever the tree below needs. And if it's fast enough, then no spinner at all!

This goes beyond API data fetching and can be applied to any async data flow, e.g. code splitting or assets loading. React.lazy in combination with the Suspense component already made it into the latest React stable release, allowing easy code splitting for dynamic imports without having to manually handle the loading state. The fully featured Suspense functionality that includes data fetching will have to wait until later this year, but you can already experiment with it through current alpha releases.

The general idea is to allow components to “suspend” their render, e.g. if they need extra data loaded from external sources. Once all the information is there, React will re-try to render the component.

To achieve this, React uses Promises. A component can throw a Promise in its render method (or anything that is called during the component’s render, e.g. the new static getDerivedStateFromProps). React catches the thrown Promise and looks for the closest Suspense component up the tree, which acts as a sort of boundary. The Suspense component takes an element as its fallback prop, which will be rendered while any children in its subtree are suspended, no matter where or why.

React also keeps track of the thrown Promise. Once it resolves, another attempt of rendering the component is made. This assumes that since the Promise is resolved, the suspended component now has all the information it needs to properly render. For that, we use some form of cache where the data is stored. This cache essentially determines on every render whether the data is already available (then it just reads it like from a variable) or not, in which case it triggers the fetch and throws the resulting Promise for React to catch. As mentioned this is not exclusive to data fetching, any async action that can be described using Promises can make use of it, code splitting being a very obvious and popular example.

The core concept is very similar to error boundaries, which were introduced in React 16 to allow catching uncaught exceptions anywhere within the app by, again, placing components (in this case any component with a componentDidCatch lifecycle method) in your tree to handle everything that gets thrown up from below them. In the same way, the Suspense component catches any thrown Promises from its children, with the difference that for Suspense we don’t have to make a custom component to act as a boundary, the Suspense component is that boundary, letting us defined the fallback that should be rendered (as well as some additional things, that we’ll touch on later).

This whole approach dramatically simplifies the way we will think about application loading states and aligns our mental model as developers more with the one of UX and UI designers.

Designers usually don’t think about data sources, but more of logical groups and information hierarchy within an interface or application. And you know who else doesn’t care about the source of your data? Users. No one likes an app with thousands of independent loading spinners, some of them only flashing for milliseconds, with the content of the page jumping up and down while the data requests resolve.

So why is this so ground breaking?

The problem

To understand what the game changer is, let’s take a look at how we currently deal with data fetching in our apps.

The most primitive approach is by storing all required information in local state, which could look something like this:

Pretty verbose, huh?

We fetch the data on mount and store it in local state. Additionally we keep track of errors and loading state through local state as well. Does that look familiar? Even if you are not using state but instead maybe even some kind of abstraction, very likely you still have a lot of those loading ternaries scattered across your app.

I wouldn’t say this approach is bad per se (it will serve the need for simple use cases, plus we can obviously easily optimise it, e.g. pulling the actual fetch into a separate method for a start), but it doesn’t scale well and the developer experience could definitely be better. To be more specific, I see the following issues with it:

1. 👎 Ugly ternaries → bad DX
   Loading and error states are defined via ternaries in the render, making the code unnecessarily convoluted. We’re not describing one render function, we’re describing three.
2. 👎 Boilerplate → bad DX
   Handling all of this state comes with a lot of boilerplate: triggering the fetch on mount, updating loading state and storing data in state on success or storing the error on failure. We would need to repeat this for every other component that uses external data.
3. 👎 Confined data and loading state → bad DX & UX
   The state is handled and stored within the component, which means we will end up with a million spinners in our app, as well as making multiple unnecessary API calls to the same endpoints if we have different components relying on the same data. This comes back to the point I made earlier, that the mental model of making loading states depend on the data source doesn’t seem right. Through this approach, the loading state is coupled to the data fetching and its component, which limits us to deal with it within this component (or finding cheats to hack around it) instead of being able to handle it in a broader context of the application.
4. 👎 Re-fetching data → bad DX
   Changing ids that i.e. would need to trigger a re-fetch of the data are verbose to implement. We’ll have to do the initial fetch in componentDidMount and additionally to check if the id changes in componentDidUpdate.
5. 👎 Flashing spinners → bad UX
   If the users internet connection is fast enough, showing the loading spinner for just a few milliseconds is even worse than showing nothing at all, making your app feel janky and slower. Perceived performance is key.

Can you see the pattern? To many it may not come as a surprise, but to me it was never really that clear how hand-in-hand developer and user experience actually go.

So, having identified the problems, how do we solve them?

Introducing Context

For a long time Redux has been the go to solution for a lot of these problems. With the “new” Context API in React 16 we got another great tool to help us define and expose data on a global level while making it easily accessible in a deeply nested component tree. So for the sake of simplicity we’ll go with the latter here.

First off, we can easily pull out all the information we previously stored in local state into a context provider, which will allow us to share it with other components. We can also expose a method to fetch data through this provider, so that our components only need trigger this method and read the loaded information via a context consumer. The recently in React 16.6 released contextType makes this even more elegant and less verbose.

The provider also functions as a form of cache, preventing us from hitting the same endpoint multiple times if the data is already there or loading, e.g. triggered by another component.

We could even try to remove the ternary within the component. Let’s say we’d want the loading spinner higher up in the tree, covering more than just this component. Now that we have the loading state in the context, we can simply access it where we want and show a loading spinner there instead, right?

This is still problematic, since the AsyncData component needs to be rendered in order to trigger the data fetch in the first place. Sure, we could hoist up the fetch as well, somewhere higher up the tree, instead of triggering it in the component, but that doesn’t really solve the problem, it just moves it somewhere else. It’s also bad for code readability and maintainability, suddenly AsyncData relies on some other component doing the data loading for it. This dependency is neither clear nor good. Ideally your components can work as much as possible in isolation, so you can place them anywhere without relying on other components being in specific spots in the component tree around them.

But at least now we have all the data and loading states in one central place, which is an improvement. And since we’re able to place the provider anywhere, we can consume this information and functionality from wherever we want, meaning that other components can utilise it (no redundant code anymore) and can reuse already loaded data, eliminating unnecessary API calls.

To put this into perspective, let’s have a look at our initial issues again:

1. 👎 Ugly ternaries
   Nothing changed here, all we can do now is move the ternaries somewhere else, which doesn’t really solve the DX problem.
2. 👍 Boilerplate
   We removed all the boilerplate that was required before. We only have to trigger the fetch and read the data and loading state from the context, leading to way less repetitive code, which in turn leads to better readability and maintainability of what‘s left.
3. 👍 Confined data and loading state
   We now have a global state that can be accessed anywhere in the application. So we improved the situation significantly, but weren’t able to solve all the issues: loading states are still coupled to the data source, also (even if we find a cheat around these dependencies) if we want to show a loading state depending on multiple components loading their respective information, we still have to explicitly know which sources that are and manually check for all the individual loading states.
4. 👎 Re-fetching data
   Nothing changed here…
5. 👎 Flashing spinners
   Here neither…

I think we can all agree that this is still a solid improvement, but it leaves some of the problems unsolved.

Suspense to the rescue

How can we do better by using Suspense?

For one, we can get rid of the context, the data handling and caching will be done by a cache provider, which really could be anything. Context, local storage, a window object (even Redux if you really wanted to), you name it. All this provider does is basically storing the information we request. On every request, it checks first whether the information is already stored. If so, return it. If not, fetch the data, and throw the Promise. Before resolving the Promise, it stores the loaded information in whatever it uses for the cache, so that when React triggers the re-render, everything is available. That’s it. Obviously it gets more complex with more complex use cases, considering things like cache invalidation and SSR, but this is the general gist of it.

This caching functionality is also one of the reasons why Suspense for data fetching still hasn’t made it into stable React yet. If you want to have a sneak peak, the experimental package called react-cache is available to play around with. But be aware that in its early stage the API will definitely change and a lot of common use cases are not yet covered.

Dan Abramov on Twitter

Note: Suspense in 16.6 is meant to be used for code splitting. The data fetching part isn't ready yet! Don't use any "cache" package until we document and release it as stable. 🙂 Unless you're just experimenting.

All that aside, we can also get rid of all the loading state ternaries. Even more, instead of fetching on component mount and update, suspense works by conditionally fetching in the render, suspending it if the data is not already available through the cache. This might seem like an anti-pattern at first (after all we’ve always been told not to do this), but it makes a lot of sense considering that if the data is in the cache, the provider will simply return it and the render gets executed as normal.

Finally we can place the boundaries and define the fallback component we want to render while the data is fetching. Where? Anywhere we want. As explained before, these boundaries will catch any thrown Promises bubbling up from below them in the tree.

I think this undeniably makes the code a lot cleaner, the logical data flow is now easily readable from top to bottom. But what did it do to our problems?

1. ❤️ Ugly ternaries
   Gone. The fallback rendering is now handled by the boundary, which makes the code easier to follow and feels more intuitive. Loading state has become a UI concern, decoupled from the actual data fetching.
2. ❤️ Boilerplate
   We improved this one even further, by completely removing the need for life cycle methods to trigger the fetch. Also foreseeing future libraries acting as cache providers, it will only be a matter of switching between those whenever you want to change your storage solution.
3. ❤️ Confined data and loading state
   Solved. Now we have clear boundaries for loading states, which don’t care about where the loading triggers came from or the reasons for them. Whenever any component within the boundary is suspended, the loading state will be rendered, period.
4. ❤️ Re-fetching data
   Since we (can) pass the source straight in the render method, changes to props that should trigger re-fetching of data will do so automatically, without us needing to do anything. The cache provider takes care of that.
5. 👎 Flashing spinners
   Well, this is still a problem 🤔

Those are massive improvements, but we still have one problem left … however, now that we’re using Suspense, React has another trick up its sleeve to help us with that one as well.

Concurrent mode to finish them off

Concurrent mode, or formerly known as Async React, is another upcoming feature that lets React work on more than one task at a time, switching between them depending on defined priorities, effectively allowing it to multi-task. Andrew Clark did a fantastic talk on it at the last ReactConf, including a great demo of the impact it has for the user. I don’t want to go into all the details here, since this really deserves a whole post on its own.

However, by adding concurrent mode to our app, Suspense receives a new capability that we can control via a prop on the Suspense component. If we now pass in a maxDuration, the boundary will delay showing the loading spinner for that amount of time, preventing spinners from flashing up unnecessarily. It also makes sure the spinner will stay for a minimum amount of time, solving the same issue essentially making sure the user experience is as smooth as possible.

To be clear, this will not make the data load any faster, but the user will perceive it as such and the user experience will be dramatically improved.

Also, concurrent mode is by no means a requirement for Suspense. As we saw before, the general functionality works perfectly fine without it and already solves many problems. Concurrent mode is more the icing on the cake, not absolutely necessary but awesome if there.

The takeaway — or a TL;DR if you will

Seeing Suspense, it feels like (until now) we had the whole concept of dealing with loading states backwards. They were always tightly coupled to the data source, which usually is tightly coupled to a specific data set or even component.

Instead, Suspense now allows us to think of loading states as a UI concern. It becomes simple to define areas in your app that will deal with loading states, while at the same time cleaning up the code from verbosity and repetition, a historical baggage we were carrying around for years.

I also want to give a huge shout out at this stage to the React team, not only for their work on the functionality itself, but even more for letting us developers explore it in its early stages, allowing healthy conversations about API design and most importantly the ecosystem already to pick up, so everything will be in place once Suspense hits the stable release later this year. Thanks! 🎉

PS: I gave a talk about all of this at the ReactBris meetup. You can find the slides and a small demo application seeing Suspense and Concurrent Mode in action here: https://github.com/julianburr/talk-suspense-game-changer

Why React Suspense Will Be a Game Changer was originally published in React In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

ReactInDepth is moving away from Medium. This article, its updates and more recent articles are hosted on the new platform inDepth.dev

In the article Level Up Your Reverse Engineering Skills I explained the benefits of reverse-engineering and outlined some guidelines and principles of successful reverse-engineering. If you haven’t read it, I recommend you start from there. This article will demonstrate the application of those guidelines and principles and introduce debugging techniques that I commonly use.

I was writing this article as I was exploring and debugging the React sources. To get the most value from it, I encourage you to go through a similar discovery process as I did using this article as a guide. If you ever wanted to reverse-engineer something, use this guide as a starting point and join me in this journey of discovery!

I’m really excited to find out how React works under the hood, like a kid on a Christmas morning 😄. Are you? Let’s get started then!

Start with acquiring the sources and setting up a sample application

For reverse-engineering I need both the React sources and a sample React application for debugging. Let’s start with the sources. I go to github.com/facebook/react and check the “releases” tab:

The latest version is 16.4.2:

Then I clone the project:

git clone https://github.com/facebook/react.git

search for the version in git tags:

$ git tag

…
v16.4.0
v16.4.0-alpha.16.4.0-alpha.7926752
v16.4.0-alpha.5a25959
v16.4.0-alpha.94a255d
v16.4.1
v16.4.2

and checkout the version I need (v16.4.2):

$ git checkout tags/v16.4.2

Checking out files: 100% (728/728), done.
Previous HEAD position was 7d9b4ba35 Update bundle sizes for 16.1.0 release
HEAD is now at 54adb2674 16.4.2

Now I need to set up a project with the same version of React. I recommend using the simplest setup possible — HTML page with the library. And it’s awesome that React is bundled to make this setup possible.

Once I download the project, I need to update the version of React to 16.4.2. I can specify the version I need in the unpckg bundle inside the index.html:

<script src="https://unpkg.com/react@16.4.2/umd/react.development.js" crossorigin></script>
<script src="https://unpkg.com/react-dom@16.4.2/umd/react-dom.development.js" crossorigin></script>

Okay, just to test that it works, I run the HTTP server inside the folder with index.html:

$ http-server .

Starting up http-server, serving .
Available on:
  http://192.168.0.4:8080
  http://127.0.0.1:8080
Hit CTRL-C to stop the server

Everything’s fine, the server is started on port 8080. Nice.

Identify the part of the technology to focus on

Okay, now I need to figure out the place where to start the process of reverse-engineering. Right now I’m wondering how change detection works in React. So that is my goal to start with.

However, it still doesn’t tell me where to put the debugger statement or what files to look for in the sources. To find out that I’m going to use my knowledge of the modern change detection process

Know common design patterns and general architectural concepts

I know that change detection is about synchronizing changes from a component instance to DOM nodes. In React we initiate the change detection process by calling setState. So I can start from there. However, since I learned from the docs that it’s an asynchronous call, I don’t think it’ll lead me directly to the relevant parts. So, instead, I’ll focus on identifying where React stores references to the created DOM nodes. Once I know that, I think I can track down where these DOM nodes are accessed and work forward from there. It seems that this path might get me closer to the end goal of understanding change detection: so I’ll focus on DOM nodes.

DOM nodes to look for

Before I can figure out where DOM nodes are stored, I need to know what DOM nodes will be created for the component. Here is how a React component looks like in my simple application:

class LikeButton extends React.Component {
  constructor(props) {
    super(props);
    this.state = { liked: false };
  }

  render() {
    if (this.state.liked) {
      return 'You liked this.';
    }

    return e(
      'button',
      { onClick: () => this.setState({ liked: true }) },
      'Like'
    );
  }
}

I’m looking at the render function responsible for returning a template for a component. Here the e is an alias for React.createElement:

const e = React.createElement;

In Angular, a template for a component is defined using HTML. In React however, the template is defined by composing calls to the createElement function. So, I need to figure out what HTML will be produced by the following statement:

return e(
    'button',
    {onClick: () => this.setState({liked: true})},
    'Like'
);

Well, since it’s a call to the createElement function I can explore the function’s implementation. But first, I need to find that function in the sources. To do that I open sources in WebStorm and use the IDE’s Search Everywhere functionality:

The first two results seem promising. I’m going to use signatures to figure out which function I need. Here is the signature for the function in the react-dom package:

export function createElement(
  type: string,
  props: Object,
  rootContainerElement: Element | Document,
  parentNamespace: string,
): Element { ... }

And the signature for the function in the react package:

export function createElement(type, config, children) { ... }

So, which one do I need?

Think like a scientist

In the first article I defined the basic steps for the scientific approach:

1. Make an observation and form a hypothesis.
2. Make a prediction based on the hypothesis.
3. Test the prediction.

So let’s now use this approach. Observing the parameters list, I assume the first function is used in the render method of the component. It’s also inside the react-dom package which adds credibility to my assumption. So that is my hypothesis — the function createElement from the react-dom package is used inside the render method. Hence, I predict that this function will be executed when React calls the render method on the component. I now need to test the prediction. To do that, I put a debugger statement before the call to createElement, run my example and when the execution is paused I step into the e function call to see where I’ll end up:

Interestingly, I end up inside the createElementWithValidation function.

Not the function I expected. Based on the function name, I guess it’s just a wrapper around createElement. I assume that this function has the call to the createElement function inside. So I look up this function in the sources:

and explore its implementation. Indeed, I see the call to the createElement inside:

export function createElementWithValidation(type, props, children) {
  const validType = isValidElementType(type);
  ...

  const element = createElement.apply(this, arguments);

At this point I can either continue exploring the sources relying on WebStorm’s ability to figure out the location of the referenced createElement function or go back to debugging. React is written in JavaScript and for projects written in JS I normally prefer debugging over exploring sources using an IDE’s reference resolution mechanism. It’s a different story with TypeScript because it’s mostly strongly typed. But in this particular case React uses ES modules for importing references:

import {isValidElement, createElement, ...} from './ReactElement';

which provides a reliable way for an IDE to resolve the location of the references. So I’ll stick to the sources for now. I control-click on the createElement and WebStorm navigates me to the function in the react/src/ReactElement.js:

export function createElement(type, config, children) { ... }

And it’s not the function I assumed would be called! My assumption was wrong. That happens all the time, don’t get discouraged by getting your hypothesis wrong.

Actually, I’m still a bit suspicious about my wrong assumption. So I’m going to test it again using the debugger. Switching between debugging and exploring implementations in the sources is very common during reverse-engineering.

Remember, we’ve ended up in the createElementWithValidation function:

So scroll a bit lower and put a breakpoint at the line of thecreateElement function call and use the Continue to here functionality of the debugger:

I then step into the function call and end up inside the createElement:

Okay, it’s the same function I arrived at using IDE’s resolution process. Now that I know which function is used in the render function, I can figure out the HTML. I just need to match the parameters in the function’s signature and the function’s call:

// signature
function createElement(type, config, children) { ... }

// actual call
return e(
    'button',
    {onClick: () => this.setState({liked: true})},
    'Like'
);

Now I’m using my knowledge of how a browser DOM works to come up with a template. There will be a bunch of hypotheses here. I assume that the type parameter refers to the tag name of a DOM node. The config specifies a bunch of event handlers and thechildren parameter defines child nodes. So I predict that based on the information supplied to the function, React will create DOM nodes corresponding to the following template:

<button (click)="() => this.setState({ liked: true })">
    Like
</button>

These nodes will be: a button element with one click event binding and a child text node with the value Like. So that is my prediction that I need to validate. To do that I need to see what DOM nodes will be created by React and compare them to the template I came up with.

Notice how the knowledge about underlying platform is required to come up with the template. You have to know about different types of DOM nodes.

If I’m lucky, these DOM nodes will be created inside the function createElement. Since I have an application paused inside the createElement function, I’ll continue with debugging to explore the function’s body. I could do that from the sources, but I usually prefer debugging over the sources, mostly because I don’t need to rely on IDE’s ability to resolve references and can immediately observe the values that variables hold.

So I quickly skim through the function body and stumble upon the call to ReactElement as a return statement:

Now it’s time to switch to the sources and explore the function ReactElement there:

I want to see if it creates DOM nodes. Well, it doesn’t. As I can see, this function just creates a data structure called ReactElement. I’m instantly curios how this data structure is used in React. Interestingly, it has the type property:

const element = {
  // This tag allows us to uniquely identify this as a React Element
  $$typeof: REACT_ELEMENT_TYPE,

  // Built-in properties that belong on the element
  type: type,
  key: key,
  ...

};

So I’m wondering if the value for this property will be the string button. Since my application is paused at the call to the ReactElement function:

I can step into the function call to find out:

Well, the first call is not the string button, but a class reference to the LikeButton component. I’m going to remember that and get back to it later. I assume that the button string should come in one of the next calls. I don’t know how many more calls there’s going to be, but I know that I can expect the button string to come only after the render function has started executing. So here is a neat trick I can use. I disable the breakpoint in the createElement function until I hit the debugger statement in the render function:

Once the breakpoint is disabled I resume execution:

Until I hit the debugger statement in the render function:

I then navigate to the disabled breakpoint

and enable it

Okay, so now I resume execution and inspect the value of the type parameter:

Great! As I guessed the element we’re creating is the button.

The comment that describes the function states that it used to create a React Element. So I guess the data structure that acts as a proxy for a DOM node in React is called ReactElement. Interesting. There’s also a link to the documentation on React Elements so I’ll need to get back to it and get familiar with the docs. But, I’ll do that a bit later when I get to the investigation of the role React Elements play in the framework. For now I need to stick to my task of validating the prediction about the DOM nodes that React will create for the component.

I continue debugging and when I exit the render function I see the following code:

{
    ReactDebugCurrentFiber.setCurrentPhase('render');
    nextChildren = instance.render();
    if (debugRenderPhaseSideEffects || ...) {
        instance.render();
    }
    ReactDebugCurrentFiber.setCurrentPhase(null);
}

I observe the surrounding code and see the word Fiber everywhere. I have no idea what it is, so I’ll google it. The search turns up numerous results. I’ve quickly scanned some of them and it seems that Fiber is the new engine. I’ll definitely need to read more about it.

Allow yourself some time to think about what you’ve found

So I’m going to pause now and think about what I’ve discovered so far. For each createElement function call, React creates a data structure called ReactElement. So, I want to add this to my notes:

createElement(type) -> ReactElement.type

I’ve seen two calls to the createElement function — the first one with the type of the LikeButton class reference and the second one with the string button. So, I assume that we can have two types of React Elements: component class references and DOM nodes types.

I still haven’t found where the DOM node is created. It’s important to find that place to validate the hypothesis about types of DOM nodes created.

Use the Call Stack to construct the application flow

At this point I want to take a look at the Call Stack:

By clicking through the functions in the Call Stack I infer that React is going through some work loop and executes pieces of work bit by bit. I suppose that one such piece of work could be creating a DOM node, but I’ll need to work through the multiple iterations of the loop to find out that. Debugging loops is always time consuming, and if a loop is asynchronous, which I imagine is the case here, the complexity of debugging rises drastically.

Have a good grasp on the underlying platform

So, instead, I’ll use my knowledge of the native DOM API and try to find the createElement native DOM API call in the sources. This method is called on the document to create a DOM node. I don’t expect React to use document directly, but rather a platform independent wrapper. So I’ll be searching for .createElement with the dot before the name omitting the document.

I’ll first do a search inside packages/react/src. There seems to be nothing there besides tests. Okay, maybe there’s something in a different package. So I’ll do a search through all packages excluding test files:

I know that createElement should be called on document, and I see something promising:

Great. Similar to how I did with the createElement function, I’ll use debugging to verify if the function I’ve found is used to create DOM nodes. I expect it to be called to create the button HTML element. To check it, I need to find this code in the sources loaded to the browser and add a breakpoint there.

Have a good command of debugging tools

So, I do a search in the sources tab of Chrome’s Dev Tools using Ctrl+Shift+F and look for the parent.ownerDocument.createElement(parent.tagName) line. This is what I get:

I double click it and end up in the corresponding file. So, I then add a breakpoint and reload my application. Nothing. The breakpoint is not hit so I guess it’s not the method I’m looking for. Again, I got it wrong.

Approach the task from different angles

But I’ll try something else here. Here is a technique I use quite often. I replace methods on objects with methods that wrap around original functionality and add the debugger statement: inside. This is a variation of the decorator pattern. When someone calls the decorated method on an object anywhere in the application, the debugger statement is hit and I can see in the Call Stack where the call is made from.

I’ll use this technique on the document object and decorate the createElement method. Usually, it’s important to decorate the method as early as possible in the application. In my case I know that the button DOM node won’t be created until after the render method is called on the component instance, so I can decorate the document at this point.

So, as soon as the application is paused in the render method, I decorate the createElement method by executing a few statements in the console:

When I resume the execution it is then paused exactly at my debugger statement:

Now all I need to do is inspect the Call Stack. I first check the previous function call:

There are a couple of things to notice here. One thing is that the function that creates DOM nodes is called createElement$1 in the code. The other thing is that React references document as ownerDocument. This is useful information and I’ll use it when I’ll be searching for other method calls on the document.

I’ll now take a look at the createInstance function call:

Cool, here the function name is createElement. And it creates the button DOM node. I don’t know why the previous call adds $1 to the function name, but it’s not important at this point. Perfect, I’ve found the function that creates DOM nodes!

Now I need to find it in the sources. I do a full search in WebStorm:

And see the familiar list again. That’s the list we started from. The first time I saw it I assumed that the function from the react-dom package will be executed inside the render function:

return createElement(
    'button',
    {onClick: () => this.setState({liked: true})},
    'Like'
);

But it was the second function that was called which created a React Element.

So I can conclude now that the function from the react-dom package creates DOM nodes, while the function from the react package creates React Elements.

That’s important information! I can use it to infer that for functions related to DOM, I should be looking inside the react-dom package. On the other hand the react package probably contains platform independent logic. I can make such an inference because I know that React is a multi platform framework. I also know how Angular packages are structured, that they have @angular/core and @angular/platform-browser which seem to be similar to React.

Now I want to spend some time exploring the file where the function createElement is placed so I can start learning the code base. The filename with the createElement function is called ReactDomFiberComponent.js. There are many functions in the file that perform DOM operations, for example: createElement, createTextNode and updateDOMProperties. I’m so happy I’ve found it! Now I have a place to look for functions to put the debugger in when I need to intercept a DOM operation.

Now I’m finally ready to validate my predication that the following call

return createElement(
    'button',
    {onClick: () => this.setState({liked: true})},
    'Like'
);

will create one button element node, one text node with the value Like and add one event listener to the button element.

I know which functions create element and text nodes, but I don’t know which function adds an event listener. I’ll do a search in the react-dom package and find the following functions:

It must be either the first or the second one.

So, to validate the prediction, I add the debugger statements to functions createElement, createTextNode and addEventBubbleListener and addEventCaptureListener. When I reload the application I hit breakpoints in the createElement and addEventBubbleListener functions. The click event is bubbling, so it makes sense that the bubble variant of the addEventListener was executed. However, the function createText node wasn’t executed. I wonder now how the text node Like was created. Maybe it was created inside the createElement function?

To find that out, I’m going to continue stepping over the calls and check the childNodes property. This is where my knowledge of the underlying platform comes in handy. This technique will allow me to quickly move through the calls and identify the function that added the child node.

So, the first function I exit is createElement. I check the property:

Nope, it’s 0. It means that child node wasn’t created by the createElement function. I then step over precacheFiberNode$1 and updateFiberProps$1 checking the property after each function. The child text node is not added. I continue debugging and end up in the completeWork function:

The variable _instance holds the reference to the created DOM node. I also check the workInProgress variable which references FiberNode:

Based on the variable name and a little info I read on Fiber, I assume the FiberNode represents a chunk of work to do in the new Fiber architecture.

Now I step over the appendAllChildren function call and check the childNodes again:

Nope, still 0. That means that the child was not added in the appendAllChildren and at this point I don’t need to dive into it. Now I repeat the same with the call to finalizeInitialChildren. Step over and check:

Great, now we have it. I’ve pinpointed the function finalizeInitialChildren that created the child node. By continuing debugging and using the approach of checking the chidlNodes value, I’ve found the code that adds the text node inside the setInitialDOMProperties function:

When I step into the setTextContent function I see how the node was added:

Finally, I’ve verified my prediction on what types of DOM nodes will be created! Take a moment to appreciate how much we’ve learnt along the way: functions that create React Elements and DOM nodes, their locations, difference between packages, new Fiber architecture. Amazing, isn’t it?

A word about luck

I talked about luck and the role it plays in the process of reverse-engineering in my previous article. Well, here is a great demonstration. I started debugging with the goal to find out where React stores DOM nodes. Incidentally, if I just lower my gaze under the finalizeInitialChildren function call I see the following:

The button DOM element created above is attached to the workInProgress fiber node. So DOM nodes are attached to Fiber Nodes. That’s where React stores references to DOM nodes.

Of course, that’s just a start. There’s a very long of road of discovery ahead.

At this point I simply know that the created DOM node and its children are attached to the FiberNode’s stateNode property. Based on my knowledge of how Angular stores DOM elements, I assume that there should be some kind of data structure corresponding to components that will hold the references to the DOM. Could the Fiber Node, which is a piece of work, be that kind of data structure? It’s possible, but I haven’t seen anything like that. Now I need to imagine how I would design that kind of system if that were the case? For that to work, I’d need to store Fiber Nodes somewhere and then iterate over them when the DOM needs an update.

I’ll need to take a look at the Fiber Node class and its type. I’ll need to figure out where Fiber nodes are stored and how they are processed. So many questions to find answers to. But I’m excited!

Thanks for reading! If you liked this article, hit that clap button below 👏. It means a lot to me and it helps other people see the story.

For more insights follow me on Twitter and on Medium.

Practical application of reverse-engineering guidelines and principles was originally published in React In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

The main algorithm of the work loop in React’s reconciler

ReactInDepth is moving away from Medium. This article, its updates and more recent articles are hosted on the new platform inDepth.dev

To educate myself and the community, I spend a lot of time reverse-engineering web technologies and writing about my findings. In the last year, I’ve focused mostly on Angular sources which resulted in the biggest Angular publication on the web — Angular-In-Depth. Now the time has come to dive deep into React. Change detection has become the main area of my expertise in Angular, and with some patience and a lot of debugging, I hope to soon achieve that level in React.

In React, the mechanism of change detection is often referred to as reconciliation or rendering, and Fiber is its newest implementation. Due to the underlying architecture, it provides capabilities to implement many interesting features like performing non-blocking rendering, applying updates based on the priority and pre-rendering content in the background. These features are referred to as time-slicing in the Concurrent React philosophy.

Besides solving real problems of application developers, the internal implementation of these mechanisms has a wide appeal from the engineering perspective. There’s such a wealth of knowledge in the sources that will help us grow as developers.

If you Google “React Fiber” today you’re going to see quite a lot articles in the search results. All of them, though, except for the notes by Andrew Clark are pretty high-level explanations. In this article, I’ll refer to this resource and provide an elaborate explanation for some particularly important concepts in Fiber. Once we’ve finished, you’ll have enough knowledge to understand the work loop representation from a very good talk by Lin Clark at ReactConf 2017. That’s the one talk you need to see. But it’ll make a lot more sense to you after you’ve spent a little time in the sources.

This post opens a series on React’s Fiber internals. I’m about 70% through understanding the internal details of the implementation and have three more articles on reconciliation and rendering mechanism in the works.

I work as a developer advocate at ag-Grid. If you’re curious to learn about data grids or looking for the ultimate react data grid solution, give it a try with the guide “Get started with React grid in 5 minutes”. I’m happy to answer any questions you may have. And follow me to stay tuned!

Let’s get started!

Setting the background

Fiber’s architecture has two major phases: reconciliation/render and commit. In the source code the reconciliation phase is mostly referred to as the “render phase”. This is the phase when React walks the tree of components and:

• updates state and props,
• calls lifecycle hooks,
• retrieves the children from the component,
• compares them to the previous children,
• and figures out the DOM updates that need to be performed.

All these activities are referred to as work inside Fiber. The type of work that needs to be done depends on the type of the React Element. For example, for a Class Component React needs to instantiate a class, while it doesn't do it for a Functional Component. If interested, here you can see all types of work targets in Fiber. These activities are exactly what Andrew talks about here:

When dealing with UIs, the problem is that if too much work is executed all at once, it can cause animations to drop frames…

Now what about that ‘all at once’ part? Well, basically, if React is going to walk the entire tree of components synchronously and perform work for each component, it may run over 16 ms available for an application code to execute its logic. And this will cause frames to drop causing stuttering visual effects.

So this can be helped?

Newer browsers (and React Native) implement APIs that help address this exact problem…

The new API he talks about is the requestIdleCallback global function that can be used to queue a function to be called during a browser’s idle periods. Here’s how you would use it by itself:

If I now open the console and execute the code above, Chrome logs 49.9 false. It basically tells me that I have 49.9 ms to do whatever work I need to do and I haven’t yet used up all allotted time, otherwise the deadline.didTimeout would be true. Keep in mind that timeRemaining can change as soon as a browser gets some work to do, so it should be constantly checked.

requestIdleCallback is actually a bit too restrictive and is not executed often enough to implement smooth UI rendering, so React team had to implement their own version.

Now if we put all the activities Reacts performs on a component into the function performWork, and use requestIdleCallback to schedule the work, our code could look like this:

We perform the work on one component and then return the reference to the next component to process. This would work, if not for one thing. You can’t process the entire tree of components synchronously, as in the previous implementation of the reconciliation algorithm. And that’s the problem Andrew talks about here:

in order to use those APIs, you need a way to break rendering work into incremental units

So to solve this problem, React had to re-implement the algorithm for walking the tree from the synchronous recursive model that relied on the built-in stack to an asynchronous model with linked list and pointers. And that’s what Andrew writes about here:

If you rely only on the [built-in] call stack, it will keep doing work until the stack is empty…Wouldn’t it be great if we could interrupt the call stack at will and manipulate stack frames manually? That’s the purpose of React Fiber. Fiber is re-implementation of the stack, specialized for React components. You can think of a single fiber as a virtual stack frame.

And that’s what I’m going to explain now.

A word about the stack

I assume you’re all familiar with the notion of a call stack. This is what you see in your browser’s debugging tools if you pause code at a breakpoint. Here are a few relevant quotes and diagrams from Wikipedia:

In computer science, a call stack is a stack data structure that stores information about the active subroutines of a computer program… the main reason for having call stack is to keep track of the point to which each active subroutine should return control when it finishes executing… A call stack is composed of stack frames… Each stack frame corresponds to a call to a subroutine which has not yet terminated with a return. For example, if a subroutine named DrawLine is currently running, having been called by a subroutine DrawSquare, the top part of the call stack might be laid out like in the adjacent picture.

Why is the stack relevant to React?

As we defined in the first part of the article, Reacts walks the components tree during the reconciliation/render phase and performs some work for components. The previous implementation of the reconciler used the synchronous recursive model that relied on the built-in stack to walk the tree. The official doc on reconciliation describe this process and talk a lot about recursion:

By default, when recursing on the children of a DOM node, React just iterates over both lists of children at the same time and generates a mutation whenever there’s a difference.

If you think about it, each recursive call adds a frame to the stack. And it does so synchronously. Suppose we have the following tree of components:

Represented as objects with the render function. You can think of them as instances of components:

React needs to iterate the tree and perform work for each component. To simplify, the work to do is to log the name of the current component and retrieve its children. Here’s how we do it with recursion.

Recursive traversal

The main function that iterates over the tree is called walk in the implementation below:

Here’s the output we’re getting:

a1, b1, b2, c1, d1, d2, b3, c2

If you don’t feel confident with recursions, check out my in-depth article on recursion.

A recursive approach is intuitive and well-suited for walking the trees. But as we discovered, it has limitations. The biggest one is that we can’t break the work into incremental units. We can’t pause the work at a particular component and resume it later. With this approach React just keeps iterating until it processed all components and the stack is empty.

So how does React implement the algorithm to walk the tree without recursion? It uses a singly linked list tree traversal algorithm. It makes it possible to pause the traversal and stop the stack from growing.

Linked list traversal

I was lucky to find the gist of the algorithm outlined by Sebastian Markbåge here. To implement the algorithm, we need to have a data structure with 3 fields:

• child — reference to the first child
• sibling — reference to the first sibling
• return — reference to the parent

In the context of the new reconciliation algorithm in React, the data structure with these fields is called Fiber. Under the hood it’s the representation of a React Element that keeps a queue of work to do. More on that in my next articles.

The following diagram demonstrates the hierarchy of objects linked through the linked list and the types of connections between them:

So let’s first define our custom node constructor:

And the function that takes an array of nodes and links them together. We’re going to use it to link children returned by the render method:

The function iterates over the array of nodes starting from the last one and links them together in a singly linked list. It returns the reference to the first sibling in the list. Here is a simple demo of how it works:

We’ll also implement a helper function that performs some work for a node. In our case, it’s going to log the name of a component. But besides that it also retrieves the children of a component and links them together:

Okay, now we’re ready to implement the main traversal algorithm. It’s a parent first, depth-first implementation. Here is the code with useful comments:

Although the implementation is not particularly difficult to understand, you may need to play with it a little to grok it. Do it here. The idea is that we keep the reference to the current node and re-assign it while descending the tree until we hit the end of the branch. Then we use the return pointer to return to the common parent.

If we now check the call stack with this implementation, here’s what we’re going to see:

As you can see, the stack doesn’t grow as we walk down the tree. But if now put the debugger into the doWork function and log node names, we’re going to see the following:

It looks like a callstack in a browser. So with this algorithm, we’re effectively replacing the browser’s implementation of the call stack with our own implementation. That’s what Andrew describes here:

Fiber is re-implementation of the stack, specialized for React components. You can think of a single fiber as a virtual stack frame.

Since we’re now controlling the stack by keeping the reference to the node that acts as a top frame:

we can stop the traversal at any time and resume to it later. That’s exactly the condition we wanted to achieve to be able to use the new requestIdleCallback API.

Work loop in React

Here’s the code that implements work loop in React:

As you can see, it maps nicely to the algorithm I presented above. It keeps the reference to the current fiber node in the nextUnitOfWork variable that acts as a top frame.

The algorithm can walk the components tree synchronously and perform the work for each fiber node in the tree (nextUnitOfWork). This is usually the case for so-called interactive updates caused by UI events (click, input etc). Or it can walk the components tree asynchronously checking if there’s time left after performing work for a Fiber node. The function shouldYield returns the result based on deadlineDidExpire and deadline variables that are constantly updated as React performs work for a fiber node.

The peformUnitOfWork function is described in depth here.

I’m working on the series of in-depth articles that explore the implementation details of Fiber change detection algorithm in React. Stay tuned and follow me on Twitter and on Medium, I’ll tweet as soon as it’s ready.

Thanks for reading! If you liked this article, hit that clap button below 👏. It means a lot to me and it helps other people see the story.

The how and why on React’s usage of linked list in Fiber was originally published in React In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

ReactInDepth is moving away from Medium. This article, its updates and more recent articles are hosted on the new platform inDepth.dev

In my previous article Inside Fiber: in-depth overview of the new reconciliation algorithm in React I laid the foundation required to understand the technical details of the update process that I’ll describe in this article.

I’ve outlined main data structure and concepts that I’ll be using in this article, particularly Fiber nodes, current and work-in-progress trees, side-effects and the effects list. I’ve also provided a high-level overview of the main algorithm and explained the difference between the render and commit phases. If you haven’t read it, I recommend that you start there.

I’ve also introduced you to the sample application with a button that simply increments a number rendered on the screen:

You can play with it here. It’s implemented as a simple component that returns two child elements button and span from the render method. As you click on the button, the state of the component is updated inside the handler. This results in the text update for the span element:

Here I’ve also added the componentDidUpdate lifecycle method to the component. This is needed to demonstrate how React adds effects to call this method during the commit phase.

In this article I want to show you how React processes state updates and builds the effects list. We’ll take a tour into what’s going on in the high-level functions for the render and commit phases.

Particularly, we’ll see how that in completeWork React:

• updates the count property in the state of ClickCounter
• calls the render method to get a list of children and performs comparison
• updates the props for the span element

And, in commitRoot React:

• updates the textContent property of the span element
• calls the componentDidUpdate lifecycle method

But before that, let’s quickly take a look at how the work is scheduled when we call setState in a click handler.

Note that you don’t need to know any of it to use React. This article is about how React works internally.

I work as a Developer Advocate at ag-Grid. If you’re curious to learn about data grids or looking for the ultimate React data grid solution, get in touch or give it a try with the guide “Get started with React grid in 5 minutes”. I’m happy to answer any questions you may have. Follow me to stay tuned!

Scheduling updates

When we click on the button, the click event is triggered and React executes the callback that we pass in the button props. In our application it simply increments the counter and updates the state:

Every React component has an associated updater which acts as a bridge between the components and the React core. This allows setState to be implemented differently by ReactDOM, React Native, server side rendering, and testing utilities.

In this article we’ll be looking at the implementation of the updater object in ReactDOM, which uses the Fiber reconciler. For the ClickCounter component it’s a classComponentUpdater. It’s responsible for retrieving an instance of Fiber, queuing updates, and scheduling the work.

When updates are queued, they are basically just added to the queue of updates to process on a Fiber node. In our case, the Fiber node corresponding to the ClickCounter component will have the following structure:

As you can see, the function in the updateQueue.firstUpdate.next.payload is the callback we passed to setState in the ClickCounter component. It represents the first update that needs to be processed during the render phase.

Processing updates for the ClickCounter Fiber node

The chapter on the work loop in my previous article explains the role of the nextUnitOfWork global variable. Particularly, it states that this variable holds a reference to the Fiber node from the workInProgress tree that has some work to do. As React traverses the tree of Fibers, it uses this variable to know if there’s any other Fiber node with unfinished work.

Let’s start with the assumption that the setState method has been called. React adds the callback from setState to the updateQueue on the ClickCounter fiber node and and schedules work. React enters the render phase. It starts traversing from the topmost HostRoot Fiber node using the renderRoot function. However, it bails out of (skips) the already processed Fiber nodes until it finds a node with unfinished work. At this point there’s only one Fiber node with some work to do. It’s the ClickCounter Fiber node.

All work is performed on the cloned copy of this Fiber node is stored in the alternate field. If the alternate node is not yet created, React creates the copy in the function createWorkInProgress before processing updates. Let’s assume that the variable nextUnitOfWork holds a reference to the alternate ClickCounter Fiber node.

beginWork

First, our Fiber gets into the beginWork function.

Since this function is executed for every Fiber node in a tree it’s a good place to put a breakpoint if you want to debug the render phase. I do that often and check the type of a Fiber node to pin down the one I need.

The beginWork function is basically a big switch statement that determines the type of work that needs to be done for a Fiber node by the tag and then executes the respective function to perform the work. In the case of CountClicks it’s a class component, so this branch will be taken:

and we get into the updateClassComponent function. Depending on whether it’s the first rendering of a component, work being resumed, or a React update, React either creates an instance and mounts the component or just updates it:

Processing updates for the ClickCounter Fiber

We already have an instance of the ClickCounter component, so we get into the updateClassInstance. That’s where React performs most of the work for class components. Here are the most important operations performed in the function in the order of execution:

• call UNSAFE_componentWillReceiveProps() hook (deprecated)
• process updates in the updateQueue and generate new state
• call getDerivedStateFromProps with this new state and get the result
• call the shouldComponentUpdate to ensure a component wants to update;
  if false, skip the whole rendering process, including calling render on this component and its children; otherwise proceed with the update
• call UNSAFE_componentWillUpdate(deprecated)
• add an effect to trigger componentDidUpdate lifecycle hook

Although the effect to call componentDidUpdate is added in the render phase, the method will be executed in the following commit phase.

• update state and props on the component instance

state and props should be updated on the component instance before the render method is called, since the render method output usually depends on the state and props. If we don’t do that, it will be returning the same output every time.

Here’s the simplified version of the function:

I’ve removed some auxiliary code in the snippet above. For instance, before calling lifecycle methods or adding effects to trigger them, React checks if a component implements the method using thetypeof operator. Here is, for example, how React checks for the componentDidUpdate method before adding the effect:

Okay, so now we know what operations are performed for the ClickCounter Fiber node during the render phase. Let’s now see how these operations change values on the Fiber nodes. When React begins work, the Fiber node for the ClickCounter component looks like this:

After the work is completed, we end up with a Fiber node that looks like this:

Take a moment to observe the differences in properties values.

After the update is applied, the value of the property count is changed to 1 in the memoizedState and the baseState in updateQueue. React has also updated the state in the ClickCounter component instance.

At this point, we no longer have updates in the queue, so firstUpdate is null. And importantly, we have changes in the effectTag property. It’s no longer 0, it’s value is 4. In binary this is 100, which means that the third bit is set, which is exactly the bit for the Update side-effect tag:

export const Update = 0b00000000100;

So to conclude, when working on the parent ClickCounter Fiber node, React calls the pre-mutation lifecycle methods, updates the state and defines relevant side-effects.

Reconciling children for the ClickCounter Fiber

Once that’s done, React gets into the finishClassComponent. This is where React calls the render method on a component instance and applies its diffing algorithm to the children returned by the component. The high-level overview is described in the docs. Here’s the relevant part:

When comparing two React DOM elements of the same type, React looks at the attributes of both, keeps the same underlying DOM node, and only updates the changed attributes.

If we dig deeper, however, we can learn that it actually compares Fiber nodes with React elements. But I won’t go into much details now as the process is quite elaborate. I’ll write a separate piece that focuses particular on the process of child reconciliation.

If you’re anxious to learn details on your own, check out the reconcileChildrenArray function since in our application the render method returns an array of React Elements.

At this point there are two things that are important to understand. First, as React goes through the child reconciliation process, it creates or updates Fiber nodes for the child React elements returned from the render method. The finishClassComponent function returns the reference to the first child of the current Fiber node. It will be assigned to the nextUnitOfWork and processed later in the work loop. Second, React updates the props on the children as part of work performed for the parent. To do that it uses data from the React elements returned from render method.

For example, here’s what the Fiber node corresponding to the span element looks like before React reconciles the children for the ClickCounter fiber:

As you can see, the children property in both memoizedProps and pendingProps is 0. Here’s the structure of the React element returned from the render for the span element:

As you can see, there’s a difference between the props in the Fiber node and the returned React element. Inside the createWorkInProgress function that is used to create alternate Fiber nodes, React will copy the updated properties from the React element to the Fiber node.

So, after React has finished reconciling the children for the ClickCounter component, the span Fiber node will have the pendingProps updated. They will match the value in the span React element:

Later, when React will be performing work for the span Fiber node, it will copy them to the memoizedProps and add effects to update DOM.

Well, that’s all the work that React performs for the ClickCounter fiber node during the render phase. Since the button is the first child of the ClickCounter component, it will be assigned to the nextUnitOfWork variable. There’s nothing to be done with it, so React will move to its sibling, which is span Fiber node. According to the algorithm described here, it happens in the completeUnitOfWork function.

Processing updates for the Span fiber

So, the variable nextUnitOfWork now points to the alternate of the span fiber and React starts working on it. Similar to the steps performed for the ClickCounter, we start with the beginWork function.

Since our span node is of HostComponent type, this time in the switch statement React takes this branch:

and ends up in the updateHostComponent function. You can see a parallel with the updateClassComponent function called for class components. For a functional component it’ll be updateFunctionComponent and so on. You can find all these functions in the ReactFiberBeginWork.js file.

Reconciling children for the span fiber

In our case there nothing important happening for the span node in the updateHostComponent.

Completing work for the Span Fiber node

Once beginWork is finished, the node gets into the completeWork function. But before that, React needs to update the memoizedProps on the span fiber. You may remember that when reconciling children for the ClickCounter component, React updated the pendingProps on the span Fiber node:

So once beginWork is finished for the span fiber, React updates pendingProps to match memoizedProps:

It then calls the completeWork function which is basically a big switch statement similar to the one we saw in beginWork:

Since our span Fiber node is HostComponent, it runs the updateHostComponent function. In this function React basically does the following:

• prepares the DOM updates
• adds them to updateQueue of the span fiber
• adds the effect to update the DOM

Before these operations are performed, the span Fiber node looks like this:

and when the work is completed it looks like this:

Notice the difference in the effectTag and updateQueue fields. It’s no longer 0, it’s value is 4. In binary this is 100, which means that the third bit is set, which is exactly the bit for the Update side-effect tag. That’s the only job React needs to do for this node during the following commit phase. The updateQueue field holds the payload that will be used for the update.

Once React has processed ClickCounter and its children, it’s done with the render phase. It can now assign the completed alternate tree to the finishedWork property on FiberRoot. This is the new tree that needs to be flushed to the screen. It can be processed immediately after the render phase or picked up later when React is given time by the browser.

Effects list

In our case, since the span node and the ClickCounter component have side effects, React will add a link to the span Fiber node to the firstEffect property of HostFiber.

React builds the effects list in the compliteUnitOfWork function. Here’s what a Fiber tree with effects to update text of the span node and calls hooks on ClickCounter looks like:

And here’s the linear list of nodes with effects:

Commit phase

This phase begins with the function completeRoot. Before it gets to do any work, it sets the finishedWork property on the FiberRoot to null:

root.finishedWork = null;

Unlike the first render phase, the commit phase is always synchronous so it can safely update HostRoot to indicate that the commit work has started.

The commit phase is where React updates the DOM and calls the post mutation lifecycle method componentDidUpdate. To do that, it goes over the list of effects it constructed during the previous render phase and applies them.

We have the following effects defined in the render phase for our span and ClickCounter nodes:

The value of the effect tag for ClickCounter is 5 or 101 in binary and defines the Update work which basically translates into the componentDidUpdate lifecycle method for class components. The least significant bit is also set to signal that all work has been completed for this Fiber node in the render phase.

The value of the effect tag for span is 4 or 100 in binary and defines the update work for the host component DOM update. In the case of the span element, React will need to update textContent for the element.

Applying effects

Let’s see how React applies those effects. The function commitRoot, which is used to apply the effects, consists of 3 sub-functions:

Each of those sub-functions implements a loop that iterates over the list of effects and checks the types of the effects. When it finds the effect pertaining to the function’s purpose, it applies it. In our case, it will call the componentDidUpdate lifecycle method on the ClickCounter component and update the text of the span element.

The first function commitBeforeMutationLifeCycles looks for the Snapshot effect and calls the getSnapshotBeforeUpdate method. But, since we didn’t implement the method on the ClickCounter component, React didn’t add the effect during the render stage. So in our case, this function does nothing.

DOM updates

Next React moves to the commitAllHostEffects function. This is where React will change the text on the span element from 0 to 1. There’s nothing to do for the ClickCounter fiber because nodes corresponding to class components don’t have any DOM updates.

The gist of the function is that it selects the correct type of effect and applies the corresponding operations. In our case we need to update the text on the span element, so we take the Update branch here:

By going down to commitWork, we will eventually get into the updateDOMProperties function. It takes the updateQueue payload that was added during the render stage to the Fiber node, and updates the textContent property on the span element:

After the DOM updates have been applied, React assigns the finishedWork tree to the HostRoot. It sets an alternate tree as current:

root.current = finishedWork;

Calling post mutation lifecycle hooks

The last remaining function is commitAllLifecycles. This where React calls the post mutational lifecycle methods. During the render phase, React added the Update effect to the ClickCounter component. This is one of the effects that the function commitAllLifecycles looks for and calls componentDidUpdate method:

The function also updates refs, but since we don’t have any this functionality won’t be used. The method is called in the commitLifeCycles function:

You can also see that this is the function where React calls the componentDidMount method for components that have been rendered for the first time.

And that’s it!

We’re finally done. Let me know what you think about the article or ask questions in the comments. I have many more articles in the works providing in-depth explanation for scheduler, children reconciliation process and how effects list is built. I also have plans to create a video where I’ll show how to debug the application using this article as a basis.

For more insights follow me on Twitter and on Medium. Thanks for reading! If you liked this article, hit that clap button below 👏. It means a lot to me and it helps other people see the story.

In-depth explanation of state and props update in React was originally published in React In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.

ReactInDepth is moving away from Medium. This article, its updates and more recent articles are hosted on the new platform inDepth.dev

React is a JavaScript library for building user interfaces. At its core lies the mechanism that tracks changes in a component state and projects the updated state to the screen. In React we know this process as reconciliation. We call the setState method and the framework checks if the state or props have changed and re-renders a component on UI.

React’s docs provide a good high-level overview of the mechanism: the role of React elements, lifecycle methods and the render method, and the diffing algorithm applied to a component’s children. The tree of immutable React elements returned from the render method is commonly known as the “virtual DOM”. That term helped explain React to people early on, but it also caused confusion and isn’t used in the React documentation anymore. In this article I’ll stick to calling it a tree of React elements.

Besides the tree of React elements, the framework has always had a tree of internal instances (components, DOM nodes etc.) used to keep the state. Starting from version 16, React rolled out a new implementation of that internal instances tree and the algorithm that manages it code-named Fiber. To learn about the advantages which the Fiber architecture brings check out The how and why on React’s usage of linked list in Fiber.

This article would take me a lot longer to write and would be less comprehensive without the help of Dan Abramov! 👍

This is the first article in the series aimed at teaching you internal architecture of React. In this article I want to provide an in-depth overview of important concepts and data structures relevant to the algorithm. Once we have enough background, we’ll explore the algorithm and main functions used to traverse and process the fiber tree. Next articles in the series will demonstrate how React uses the algorithm to perform initial render and process state and props updates. From there we’ll move on to the details of the scheduler, the child reconciliation process, and the mechanism of building an effects list.

Follow me to stay tuned!

I’m going to give you some pretty advanced knowledge here 🧙‍. I encourage you to read it to understand the magic behind the inner workings of Concurrent React. This series of articles will also serve you as a great guide if you plan to start contributing to React. I’m a strong believer in reverse-engineering, so there will be a lot of links to the sources from the recent version 16.6.0.

It’s definitely quite a lot to take in, so don’t feel stressed if you don’t understand something right away. It takes time as everything worthwhile. Note that you don’t need to know any of it to use React. This article is about how React works internally.

I work as a Developer Advocate at ag-Grid. If you’re curious to learn about data grids or looking for the ultimate React data grid solution, get in touch or give it a try with the guide “Get started with React grid in 5 minutes”. I’m happy to answer any questions you may have.

Setting the background

Here’s a simple application that I’ll use throughout the series. We have a button that simply increments a number rendered on the screen:

And here’s the implementation:

You can play with it here. As you can see, it’s a simple component that returns two child elements button and span from the render method. As soon as you click on the button, the state of the component is updated inside the handler. This, in turn, results in the text update for the span element.

There are various activities React performs during reconciliation. For example, here are the high-level operations React performs during the first render and after state update in our simple application:

• updates count property in the state of ClickCounter
• retrieves and compares children of ClickCounter and their props
• updates props for the span element

There are other activities performed during reconciliation like calling lifecycle methods or updating refs. All these activities are collectively referred to as “work” in the Fiber architecture. The type of work usually depends on the type of React element. For example, for a class component, React needs to create an instance, while it doesn’t do that for a functional component. As you know, we have many kinds of elements in React, e.g. class and functional components, host components (DOM nodes), portals etc. The type of React element is defined by the first parameter to the createElement function. This function is generally used in the render method to create an element.

Before we begin our exploration of the activities and the main fiber algorithm, let’s first get ourselves familiar with the data structures used internally by React.

From React Elements to Fiber nodes

Every component in React has a UI representation we can call a view or a template that’s returned from the render method. Here’s the template for our ClickCounter component:

React Elements

Once a template goes through the JSX compiler, you end up with a bunch of React elements. This is what’s really returned from the render method of React components, not HTML. Since we’re not required to use JSX, the render method for our ClickCounter component could be re-written like this:

The calls to React.createElement in the render method will create two data structures like this:

You can see that React adds the property $$typeof to these objects to uniquely identify them as React elements. Then we have properties type, key and props that describe the element. The values are taken from what you pass to the React.createElement function. Notice how React represents text content as children of the span and button nodes. And how the click handler is part of the button element props. There are other fields on React elements like the ref field that are beyond the scope of this article.

The React element for ClickCounter doesn’t have any props or a key:

Fiber nodes

During reconciliation data from every React element returned from the render method is merged into the tree of fiber nodes. Every React element has a corresponding fiber node. Unlike React elements, fibers aren’t re-created on every render. These are mutable data structures that hold components state and DOM.

We discussed earlier that depending on the type of a React element the framework needs to perform different activities. In our sample application, for the class components ClickCounter it calls lifecycle methods and the render method, whereas for the span host component (DOM node) it performs DOM mutation. So each React element is converted into a Fiber node of corresponding type that describes the work that needs to be done.

You can think of a fiber as a data structure that represents some work to do or, in other words, a unit of work. Fiber’s architecture also provides a convenient way to track, schedule, pause and abort the work.

When a React element is converted into a fiber node for the first time, React uses the data from the element to create a fiber in the createFiberFromTypeAndProps function. In the consequent updates React reuses the fiber node and just updates the necessary properties using data from a corresponding React element. React may also need to move the node in the hierarchy based on the key prop or delete it if the corresponding React element is no longer returned from the render method.

Check out the ChildReconciler function to see the list of all activities and corresponding functions React performs for existing fiber nodes.

Because React creates a fiber for each React element and since we have a tree of those elements, we’re going to have a tree of fiber nodes. In the case of our sample application it looks like this:

All fiber nodes are connected through a linked list using the following properties on fiber nodes: child, sibling and return. For more details on why it works this way, check out my article The how and why on React’s usage of linked list in Fiber if you haven’t read it already.

Current and work in progress trees

After the first render, React ends up with a fiber tree that reflects the state of the application that was used to render the UI. This tree is often referred to as current. When React starts working on updates it builds a so-called workInProgress tree that reflects the future state to be flushed to the screen.

All work is performed on fibers from the workInProgress tree. As React goes through the current tree, for each existing fiber node it creates an alternate node that constitutes the workInProgress tree. This node is created using the data from React elements returned by the render method. Once the updates are processed and all related work is completed, React will have an alternate tree ready to be flushed to the screen. Once this workInProgress tree is rendered on the screen, it becomes the current tree.

One of React’s core principles is consistency. React always updates the DOM in one go — it doesn’t show partial results. The workInProgress tree serves as a “draft” that’s not visible to the user, so that React can process all components first, and then flush their changes to the screen.

In the sources you’ll see a lot of functions that take fiber nodes from both the current and workInProgress trees. Here’s the signature of one such function:

Each fiber node holds a reference to its counterpart from the other tree in the alternate field. A node from the current tree points to the node from the workInProgress tree and vice versa.

Side-effects

We can think of a component in React as a function that uses the state and props to compute the UI representation. Every other activity like mutating the DOM or calling lifecycle methods should be considered a side-effect or, simply, an effect. Effects are also mentioned in the docs:

You’ve likely performed data fetching, subscriptions, or manually changing the DOM from React components before. We call these operations “side effects” (or “effects” for short) because they can affect other components and can’t be done during rendering.

You can see how most state and props updates will lead to side-effects. And since applying effects is a type of work, a fiber node is a convenient mechanism to track effects in addition to updates. Each fiber node can have effects associated with it. They are encoded in the effectTag field.

So effects in Fiber basically define the work that needs to be done for instances after updates have been processed. For host components (DOM elements) the work consists of adding, updating or removing elements. For class components React may need to update refs and call the componentDidMount and componentDidUpdate lifecycle methods. There are also other effects corresponding to other types of fibers.

Effects list

React processes updates very quickly and to achieve that level of performance it employs a few interesting techniques. One of them is building a linear list of fiber nodes with effects for quick iteration. Iterating the linear list is much faster than a tree, and there’s no need to spend time on nodes without side-effects.

The goal of this list is to mark nodes that have DOM updates or other effects associated with them. This list is a subset of the finishedWork tree and is linked using the nextEffect property instead of the child property used in the current and workInProgress trees.

Dan Abramov offered an analogy for an effects list. He likes to think of it as a Christmas tree, with “Christmas lights” binding all effectful nodes together. To visualize this, let’s imagine the following tree of fiber nodes where the highlighted nodes have some work to do. For example, our update caused c2 to be inserted into the DOM, d2 and c1 to change attributes, and b2 to fire a lifecycle method. The effect list will link them together so React can skip other nodes later:

You can see how the nodes with effects are linked together. When going over the nodes, React uses the firstEffect pointer to figure out where the list starts. So the diagram above can be represented as a linear list like this:

As you can see, React applies effects in the order from children and up to parents.

Root of the fiber tree

Every React application has one or more DOM elements that act as containers. In our case it’s the div element with the ID container.

React creates a fiber root object for each of those containers. You can access it using the reference to the DOM element:

This fiber root is where React holds the reference to a fiber tree. It is stored in the current property of the fiber root:

The fiber tree starts with a special type of fiber node which is HostRoot. It’s created internally and acts as a parent for your topmost component. There’s a link from the HostRoot fiber node back to the FiberRoot through the stateNode property:

You can explore the fiber tree by accessing the topmost HostRoot fiber node through the fiber root. Or you can get an individual fiber node from a component instance like this:

Fiber node structure

Let’s now take a look at the structure of fiber nodes created for the ClickCounter component

and the span DOM element:

There’s quite a lot of fields on fiber nodes. I’ve described the purpose of the fields alternate, effectTag and nextEffect in previous sections. Let’s now see why we need others.

stateNode
Holds the reference to the class instance of a component, a DOM node or other React element type associated with the fiber node. In general, we can say that this property is used to hold the local state associated with a fiber.

type
Defines the function or class associated with this fiber. For class components, it points to the constructor function and for DOM elements it specifies the HTML tag. I use this field quite often to understand what element a fiber node is related to.

tag
Defines the type of the fiber. It’s used in the reconciliation algorithm to determine what work needs to be done. As mentioned earlier, the work varies depending on the type of React element. The function createFiberFromTypeAndProps maps a React element to the corresponding fiber node type. In our application, the property tag for the ClickCounter component is 1 which denotes a ClassComponent and for the span element it’s 5 denoting a HostComponent.

updateQueue
A queue of state updates, callbacks and DOM updates.

memoizedState
State of the fiber that was used to create the output. When processing updates it reflects the state that’s currently rendered on the screen.

memoizedProps
Props of the fiber that were used to create the output during the previous render.

pendingProps
Props that have been updated from new data in React elements and need to be applied to child components or DOM elements.

key
Unique identifier with a group of children to help React figure out which items have changed, have been added or removed from the list. It’s related to the “lists and keys” functionality of React described here.

You can find the complete structure of a fiber node here. I’ve omitted a bunch of fields in the explanation above. Particularly, I skipped the pointers child, sibling and return that make up a tree data structure which I described in my previous article. And a category of fields like expirationTime, childExpirationTime and mode that are specific to Scheduler.

General algorithm

React performs work in two main phases: render and commit.

During the first render phase React applies updates to components scheduled through setState or React.render and figures out what needs to be updated in the UI. If it’s the initial render, React creates a new fiber node for each element returned from the render method. In the following updates, fibers for existing React elements are re-used and updated. The result of the phase is a tree of fiber nodes marked with side-effects. The effects describe the work that needs to be done during the following commit phase. During this phase React takes a fiber tree marked with effects and applies them to instances. It goes over the list of effects and performs DOM updates and other changes visible to a user.

It’s important to understand that the work during the first render phase can be performed asynchronously. React can process one or more fiber nodes depending on the available time, then stop to stash the work done and yield to some event. It then continues from where it left off. Sometimes though, it may need to discard the work done and start from the top again. These pauses are made possible by the fact that the work performed during this phase doesn’t lead to any user-visible changes, like DOM updates. In contrast, the following commit phase is always synchronous. This is because the work performed during this stage leads to changes visible to the user, e.g. DOM updates. That’s why React needs to do them in a single pass.

Calling lifecycle methods is one type of work performed by React. Some methods are called during the render phase and others during the commit phase. Here’s the list of lifecycles called when working through the first render phase:

• [UNSAFE_]componentWillMount (deprecated)
• [UNSAFE_]componentWillReceiveProps (deprecated)
• getDerivedStateFromProps
• shouldComponentUpdate
• [UNSAFE_]componentWillUpdate (deprecated)
• render

As you can see, some legacy lifecycle methods that are executed during the render phase are marked as UNSAFE from the version 16.3. They are now called legacy lifecycles in the docs. They will be deprecated in future 16.x releases and their counterparts without the UNSAFE prefix will be removed in 17.0. You can read more about these changes and the suggested migration path here.

Are you curious about the reason for this?

Well, we’ve just learned that because the render phase doesn’t produce side-effects like DOM updates, React can process updates asynchronously to components asynchronously (potentially even doing it in multiple threads). However, the lifecycles marked with UNSAFE have often been misunderstood and subtly misused. Developers tended to put the code with side-effects inside these methods which may cause problems with the new async rendering approach. Although only their counterparts without the UNSAFE prefix will be removed, they are still likely to cause issues in the upcoming Concurrent Mode (which you can opt out of).

Here’s the list of lifecycle methods executed during the second commit phase:

• getSnapshotBeforeUpdate
• componentDidMount
• componentDidUpdate
• componentWillUnmount

Because these methods execute in the synchronous commit phase, they may contain side effects and touch the DOM.

Okay, so now we have the background to take a look at generalized algorithm used to walk the tree and perform work. Let’s dive in.

Render phase

The reconciliation algorithm always starts from the topmost HostRoot fiber node using the renderRoot function. However, React bails out of (skips) already processed fiber nodes until it finds the node with unfinished work. For example, if you call setState deep in the components tree, React will start from the top but quickly skip over the parents until it gets to the component that had its setState method called.

Main steps of the work loop

All fiber nodes are processed in the work loop. Here is the implementation of the synchronous part of the loop:

In the code above, the nextUnitOfWork holds a reference to the fiber node from the workInProgress tree that has some work to do. As React traverses the tree of Fibers, it uses this variable to know if there’s any other fiber node with unfinished work. After the current fiber is processed, the variable will either contain the reference to the next fiber node in a tree or null. In that case React exits the work loop and is ready to commit the changes.

There are 4 main functions that are used to traverse the tree and initiate or complete the work:

• performUnitOfWork
• beginWork
• completeUnitOfWork
• completeWork

To demonstrate how they are used, take a look at the following animation of traversing a fiber tree. I’ve used the simplified implementation of these functions for the demo. Each function takes a fiber node to process and as React goes down the tree you can see the currently active fiber node changes. You can clearly see on the video how the algorithm goes from one branch to the other. It first completes the work for children before moving to parents.

Note that straight vertical connections denote siblings, whereas bent connections denote children, e.g. b1 doesn’t have children, while b2 has one child c1.

Here’s the link to the video where you can pause the playback and inspect the current node and the state of functions. Conceptually, you can think of “begin” as “stepping into” a component, and “complete” as “stepping out” of it. You can also play with the example and the implementation here as I explain what these functions do.

Let’s start with the first two functions performUnitOfWork and beginWork:

The function performUnitOfWork receives a fiber node from the workInProgress tree and starts the work by calling beginWork function. This is the function that will start all the activities that need to be performed for a fiber. For the purposes of this demonstration, we simply log the name of the fiber to denote that the work has been done. The function beginWork always returns a pointer to the next child to process in the loop or null.

If there’s a next child, it will be assigned to the variable nextUnitOfWork in the workLoop function. However, if there’s no child, React knows that it reached the end of the branch and so it can complete the current node. Once the node is completed, it’ll need to perform work for siblings and backtrack to the parent after that. This is done in the completeUnitOfWork function:

You can see that the gist of the function is a big while loop. React gets into this function when a workInProgress node has no children. After completing the work for the current fiber, it checks if there’s a sibling. If found, React exits the function and returns the pointer to the sibling. It will be assigned to the nextUnitOfWork variable and React will perform the work for the branch starting with this sibling. It’s important to understand that at this point React has only completed work for the preceding siblings. It hasn’t completed work for the parent node. Only once all branches starting with child nodes are completed does it complete the work for the parent node and backtracks.

As you can see from the implementation, both performUnitOfWork and completeUnitOfWork are used mostly for iteration purposes, whereas the main activities take place in the beginWork and completeWork functions. In the following articles in the series we’ll learn what happens for the ClickCounter component and the span node as React steps into beginWork and completeWork functions.

Commit phase

The phase begins with the function completeRoot. This is where React updates the DOM and calls pre and post mutation lifecycle methods.

When React gets to this phase, it has 2 trees and the effects list. The first tree represents the state currently rendered on the screen. Then there’s an alternate tree built during the render phase. It’s called finishedWork or workInProgress in the sources and represents the state that needs to be reflected on the screen. This alternate tree is linked similarly to the current tree through the child and sibling pointers.

And then, there’s an effects list — a subset of nodes from the finishedWork tree linked through the nextEffect pointer. Remember that the effect list is the result of running the render phase. The whole point of rendering was to determine which nodes need to be inserted, updated, or deleted, and which components need to have their lifecycle methods called. And that’s what the effect list tells us. And it’s exactly the set of nodes that’s iterated during the commit phase.

For debugging purposes, the current tree can be accessed through the current property of the fiber root. The finishedWork tree can be accessed through the alternate property of the HostFiber node in the current tree.

The main function that runs during the commit phase is commitRoot. Basically, it does the following:

• Calls the getSnapshotBeforeUpdate lifecycle method on nodes tagged with the Snapshot effect
• Calls the componentWillUnmount lifecycle method on nodes tagged with the Deletion effect
• Performs all the DOM insertions, updates and deletions
• Sets the finishedWork tree as current
• Calls componentDidMount lifecycle method on nodes tagged with the Placement effect
• Calls componentDidUpdate lifecycle method on nodes tagged with the Update effect

After calling the pre-mutation method getSnapshotBeforeUpdate, React commits all the side-effects within a tree. It does it in two passes. The first pass performs all DOM (host) insertions, updates, deletions and ref unmounts. Then React assigns the finishedWork tree to the FiberRoot marking the workInProgress tree as the current tree. This is done after the first pass of the commit phase, so that the previous tree is still current during componentWillUnmount, but before the second pass, so that the finished work is current during componentDidMount/Update. In the second pass React calls all other lifecycle methods and ref callbacks. These methods are executed as a separate pass so that all placements, updates, and deletions in the entire tree have already been invoked.

Here’s the gist of the function that runs the steps described above:

Each of those sub-functions implements a loop that iterates over the list of effects and checks the type of effects. When it finds the effect pertaining to the function’s purpose, it applies it.

Pre-mutation lifecycle methods

Here is, for example, the code that iterates over an effects tree and checks if a node has the Snapshot effect:

For a class component, this effect means calling the getSnapshotBeforeUpdate lifecycle method.

DOM updates

commitAllHostEffects is the function where React performs DOM updates. The function basically defines the type of operation that needs to be done for a node and executes it:

It’s interesting that React calls the componentWillUnmount method as part of the deletion process in the commitDeletion function.

Post-mutation lifecycle methods

commitAllLifecycles is the function where React calls all remaining lifecycle methods componentDidUpdate and componentDidMount.

We’re finally done. Let me know what you think about the article or ask questions in the comments. Check out the next article in the series In-depth explanation of state and props update in React. I have many more articles in the works providing in-depth explanation for scheduler, children reconciliation process and how effects list is built. I also have plans to create a video where I’ll show how to debug the application using this article as a basis.

For more insights follow me on Twitter and on Medium. Thanks for reading! If you liked this article, hit that clap button below 👏. It means a lot to me and it helps other people see the story.

Inside Fiber: in-depth overview of the new reconciliation algorithm in React was originally published in React In Depth on Medium, where people are continuing the conversation by highlighting and responding to this story.