Understanding The React Source Code - Initial Rendering (Simple Component) I

Understanding The React Source Code

UI updating, in its essential, is data change. React offers a straightforward and intuitive approach to front-end program with all the moving parts converged in the form of states. Code review is also made easier to me as I like to start with data structures for a rough expectation of the functionalities and processing logic. From time to time, I was curious about how React works internally, hence this article.

It never hurts to have a deeper understanding down the stack, as it gives me more freedom when I need a new feature, more confidence when I want to contribute and more comfort when I upgrade.

This article will start walking through one of the critical paths of React by rendering a simple component, i.e., a <h1>. Other topics (e.g., Composite components rendering, state driven UI updating and components life cycle) will be discussed in the following articles in a similar, actionable manner.

Files used in this article:
isomorphic/React.js: entry point of ReactElement.createElement()

isomorphic/classic/element/ReactElement.js: workhorse of ReactElement.createElement()

renderers/dom/ReactDOM.js: entry point of ReactDOM.render()

renderers/dom/client/ReactMount.js: workhorse of ReactDom.render()

renderers/shared/stack/reconciler/instantiateReactComponent.js: create different types of ReactComponents based on element type

renderers/shared/stack/reconciler/ReactCompositeComponent.js: ReactComponents wrapper of root element

Tags used in the call stack:
- function call
= alias
~ indirect function call

As the locations of source code files can not be obviously derived from import statement in the flat module tree, I will use @ to help locating them in the code snippet listings.

Last words, this series is based on React 15.6.2.

From JSX to React.createElement()

I was not consciously aware of using React.createElement(), as the existence of it is masked by JSX from a developer’s point of view.

In compiling time, components defined in JSX is translated by Babel to React.createElement() called with appropriate parameters. For instance, the default App.js shipped with create-react-app:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';

class App extends Component {
  render() {
    return (
      <div className="App">
        <header className="App-header">
          <img src={logo} className="App-logo" alt="logo" />
          <h1 className="App-title">Welcome to React</h1>
        </header>
        <p className="App-intro">
          To get started, edit <code>src/App.js</code> and save to reload.
        </p>
      </div>
    );
  }
}

export default App;

is compiled to:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import React, { Component } from 'react';
import logo from './logo.svg';
import './App.css';

class App extends Component {
  render() {
    return React.createElement(
      'div',
      { className: 'App' },
      React.createElement(
        'header',
        { className: 'App-header' },
        React.createElement('img', { src: logo, className: 'App-logo', alt: 'logo' }),
        React.createElement(
          'h1',
          { className: 'App-title' },
          'Welcome to React'
        )
      ),
      React.createElement(
        'p',
        { className: 'App-intro' },
        'To get started, edit ',
        React.createElement(
          'code',
          null,
          'src/App.js'
        ),
        ' and save to reload.'
      )
    );
  }
}

export default App;

which is the real code executed by a browser. The code above shows a definition of a composite component App, in which JSX, a syntax of interweaving HTML tag in JavaScript code (e.g., <div className=”App”></div>), is translated to React.createElement() calls.

On the application level, this component will be rendered:

1
2
3
4
ReactDOM.render(
  <App />,
  document.getElementById('root')
);

normally by a JS entry module named “index.js”.

This nested components tree is a bit too complicated to be an ideal start point, so we forget it now and instead look at something easier - that renders a simple HTML element.

1
2
3
4
5
6
...
ReactDOM.render(
  <h1 style={{"color":"blue"}}>hello world</h1>,
  document.getElementById('root')
);
...

the babeled version of the above code is:

1
2
3
4
5
6
7
...
ReactDOM.render(React.createElement(
  'h1',
  { style: { "color": "blue" } },
  'hello world'
), document.getElementById('root'));
...

React.createElement() - create a ReactElement

The first step does not do much really. It simply constructs an ReactElement instance populated with whatever passed down to the call stack. The outcome data structure is:

The call stack is:

1
2
3
React.createElement
|=ReactElement.createElement(type, config, children)
  |-ReactElement(type,..., props)

React.createElement(type, config, children) is merely an alias of ReactElement.createElement();

1
2
3
4
5
6
7
8
9
10
11
12
...
var createElement = ReactElement.createElement;
...
var React = {
...
  createElement: createElement,
...
};

module.exports = React;

React@isomorphic/React.js

ReactElement.createElement(type, config, children) 1) copies the elements in config to props, 2) copies the children to props.children and 3) copies the type.defaultProps to props;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
...
  // 1)
  if (config != null) {
  ...extracting not interesting properties from config...
    // Remaining properties are added to a new props object
    for (propName in config) {
      if (
        hasOwnProperty.call(config, propName) &&
        !RESERVED_PROPS.hasOwnProperty(propName)
      ) {
        props[propName] = config[propName];
      }
    }
  }

  // 2)
  // Children can be more than one argument, and those are transferred onto
  // the newly allocated props object.
  var childrenLength = arguments.length - 2;
  if (childrenLength === 1) {
    props.children = children; // scr: one child is stored as object
  } else if (childrenLength > 1) {
    var childArray = Array(childrenLength);
    for (var i = 0; i < childrenLength; i++) {
      childArray[i] = arguments[i + 2]; // scr: multiple children are stored as array
    }

    props.children = childArray;
  }

  // 3)
  // Resolve default props
  if (type && type.defaultProps) {
    var defaultProps = type.defaultProps;
    for (propName in defaultProps) {
      if (props[propName] === undefined) {
        props[propName] = defaultProps[propName];
      }
    }
  }

  return ReactElement(
    type,
    key,
    ref,
    self,
    source,
    ReactCurrentOwner.current,
    props,
  );
...

ReactElement.createElement@isomorphic/classic/element/ReactElement.js

Then ReactElement(type ,... ,props) copies the type and props as they are to ReactElement and returns the instance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
...
var ReactElement = function(type, key, ref, self, source, owner, props) {
    // This tag allow us to uniquely identify this as a React Element
    $$typeof: REACT_ELEMENT_TYPE,

    // Built-in properties that belong on the element
    type: // scr:------------------> 'h1'
    key:  // scr:------------------> not of interest for now
    ref:  // scr:------------------> not of interest for now
    props: {
        children:       // scr:------------------> 'hello world'
        ...other props: // scr:------------------> style: { "color": "blue" }
    },

    // Record the component responsible for creating this element.
    _owner: owner, // scr: --------------> null
};
...

ReactElement@isomorphic/classic/element/ReactElement.js

The fields populated in the newly constructed ReactElement will be used directly by ReactMount.instantiateReactComponent(), which will be explained in detail very soon. Note that the next step will also create a ReactElement object with ReactElement.createElement(), so I will call the ReactElement object of this phase ReactElement[1].

ReactDom.render() - and render it

_renderSubtreeIntoContainer() - attach TopLevelWrapper to the ReactElement[1]

The purpose of the next step is to wrap the ReactElement[1] with another ReactElement (we call the instance a [2]) and set the ReactElement.type with TopLevelWrapper. The name TopLevelWrapper explains what it does - wrap the top level element of the component tree passed through render():

An important definition here is that of TopLevelWrapper, I type three stars here *** for you to CTL-f, as you might need to come back to this definition later. 

1
2
3
4
5
6
7
8
9
10
11
12
...
var TopLevelWrapper = function() {
  this.rootID = topLevelRootCounter++;
};
TopLevelWrapper.prototype.isReactComponent = {};
TopLevelWrapper.prototype.render = function() {
  return this.props.child;
};
TopLevelWrapper.isReactTopLevelWrapper = true;
...

TopLevelWrapper@renderers/dom/client/ReactMount.js

Please note that the entity assigned to ReactElement.type is a type (TopLevelWrapper) which will be instantiated in the following rendering steps. (Then ReactElement[1] will be extracted from this.props.child through render().)

The call stack to construct the designated object is as following:

1
2
3
4
5
6
7
8
ReactDOM.render
|=ReactMount.render(nextElement, container, callback)
|=ReactMount._renderSubtreeIntoContainer(
  parentComponent, // scr:-----------------> null
  nextElement,     // scr:-----------------> ReactElement[1]
  container,       // scr:-----------------> document.getElementById('root')
  callback'        // scr:-----------------> undefined
)

For initial rendering, ReactMount._renderSubtreeIntoContainer() is simpler than it seems to be, in fact, most branches (for UI updating) in this function are skipped. The only line that is effective before the logic processes to next step is

1
2
3
4
5
6
7
...
    var nextWrappedElement = React.createElement(TopLevelWrapper, {
      child: nextElement,
    });
...

_renderSubtreeIntoContainer@renderers/dom/client/ReactMount.js

Now that it should be easy to see how the target object of this step is constructed with React.createElement, the function we just examined in the last section.

instantiateReactComponent() - create a ReactCompositeComponent using ReactElement[2]

The purpose of this is step is to create a primitive ReactCompositeComponent for the top level component:

The call stack of this step is:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
ReactDOM.render
|=ReactMount.render(nextElement, container, callback)
|=ReactMount._renderSubtreeIntoContainer()
  |-ReactMount._renderNewRootComponent(
      nextWrappedElement, // scr:------------------> ReactElement[2]
      container,          // scr:------------------> document.getElementById('root')
      shouldReuseMarkup,  // scr: null from ReactDom.render()
      nextContext,        // scr: emptyObject from ReactDom.render()
    )
    |-instantiateReactComponent(
        node,             // scr:------------------> ReactElement[2]
        shouldHaveDebugID /* false */
      )
      |-ReactCompositeComponentWrapper(
          element         // scr:------------------> ReactElement[2]
        );
      |=ReactCompositeComponent.construct(element)

instantiateReactComponent is the only long function that is worth discussing here. In our context, it checks the ReactElement[2].type (i.e., TopLevelWrapper) and creates a ReactCompositeComponent accordingly.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
function instantiateReactComponent(node, shouldHaveDebugID) {
  var instance;

...
  } else if (typeof node === 'object') {
    var element = node;
    var type = element.type;
...

    // Special case string values
    if (typeof element.type === 'string') {
...
    } else if (isInternalComponentType(element.type)) {
...
    } else {
      instance = new ReactCompositeComponentWrapper(element);
    }
  } else if (typeof node === 'string' || typeof node === 'number') {
...
  } else {
...
  }

...
  return instance;
}

instantiateReactComponent@renderers/shared/stack/reconciler/instantiateReactComponent.js

It is worth noting that new ReactCompositeComponentWrapper() is a direct call of ReactCompositeComponent constructor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
...
// To avoid a cyclic dependency, we create the final class in this module
var ReactCompositeComponentWrapper = function(element) {
  this.construct(element);
};
...

...
Object.assign(
  ReactCompositeComponentWrapper.prototype,
  ReactCompositeComponent,
  {
    _instantiateReactComponent: instantiateReactComponent,
  },
);
...

ReactCompositeComponentWrapper@renderers/shared/stack/reconciler/instantiateReactComponent.js

Then the real constructor get called:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
  construct: function(element) {
    this._currentElement = element; // scr:------------> ReactElement[2]
    this._rootNodeID = 0;
    this._compositeType = null;
    this._instance = null;
    this._hostParent = null;
    this._hostContainerInfo = null;

    // See ReactUpdateQueue
    this._updateBatchNumber = null;
    this._pendingElement = null;
    this._pendingStateQueue = null;
    this._pendingReplaceState = false;
    this._pendingForceUpdate = false;

    this._renderedNodeType = null;
    this._renderedComponent = null;
    this._context = null;
    this._mountOrder = 0;
    this._topLevelWrapper = null;

    // See ReactUpdates and ReactUpdateQueue.
    this._pendingCallbacks = null;

    // ComponentWillUnmount shall only be called once
    this._calledComponentWillUnmount = false;
  },

ReactCompositeComponent@renderers/shared/stack/reconciler/ReactCompositeComponent.js

We name the object created in this step ReactCompositeComponent[T] (T for top).

After the ReactCompositeComponent object is constructed, the next step is to call batchedMountComponentIntoNode, initialize ReactCompositeComponent[T] and mount it, which will be discussed in detail in the next article.

That's it. Did I make a serious mistake? or miss out on anything important? Or you simply like the read. Send me a comment on -- I'd be chuffed to hear your feedback.