React is a black box. Why does that matter?

React is arguably the most-loved frontend technology. One of the reasons for this success is undoubtedly React’s small API surface, which has grown in recent years but can still be learned in just a couple of hours.

Even though React’s API is small, many devs argue that React’s internals are not only quite complicated, but need to be known these days. So naturally, the question arises — does it matter that React is a black box? Does it help us, or does it impact us negatively?

In this article, I’ll explore the ins and outs of React’s abstraction model in pursuit of an answer.

React’s outside API

In many use cases, React’s outside API is pretty much nonexistent. If we write JSX like so:

const element = <div>Hello!</div>;

Or like so:

const Component = ({ children }) => (
  <>
    <p>I am a component</p>
    {children}
  </>
);

Then this is transpiled into a call to jsx from the react/jsx-runtime module. Even before the new JSX transform was introduced, all we had to do was to bring in React, such as:

import * as React from 'react';

const element = <div>Hello!</div>;

And a transpiler such as Babel or TypeScript would have transformed it to call React.createElement.

So we can see already that React’s most important API is pretty much hidden. With createElement or jsx being used implicitly, we never called the outside API explicitly.

Now, excluding more “classic” APIs such as Component or PureComponent (including their lifecycle), we know that React offers a lot more than we may want (or even need) to use. For instance, using lazy for lazy loading (e.g., for bundle splitting) capabilities is quite cool but requires a Suspense boundary.

On the other hand, we have APIs like useState and useEffect that bring in a certain magic. First, these are all functions, but these functions cannot be used just anywhere. They can only be used inside a component, and only when being called (i.e., rendered) from React. Even then, they may not behave exactly as we expect.

These are APIs that are quite leaky. To understand them, we need to have quite a sophisticated understanding of what happens inside of React — which brings us to the inside API.

React’s inside API

There are three kinds of inside APIs:

1. APIs that are usually only implemented by a few libraries (such as the reconciliation API — more on that later)
2. APIs that can sometimes be useful and reachable, but not stable, on the outside
3. APIs that cannot be reached from the outside; they are (and can) only be used internally

I don’t want to focus on No. 3 above, as this is anyway beyond our reach. Going for No. 2 does not make much sense either, as these are always subject to change and should be avoided. Which leaves us with APIs that are implemented by only a few libraries but have quite some impact.

As previously mentioned, the most important thing to implement is the reconciliation API. One implementation of this is provided by the render function of react-dom. Another example is renderToString from react-dom/server. What’s the difference?

Let’s consider a more complex (yet still simple) component:

const Component = () => {
  const [color, setColor] = useState('white');

  useLayoutEffect(() => {
    document.body.style.backgroundColor = color;
  }, [color]);

  return (
    <>
      <p>Select your preferred background color.</p>
      <select onChange={e => setColor(e.target.value)} value={color}>
        <option value="white">White</option>
        <option value="black">Black</option>
        <option value="red">Red</option>
        <option value="green">Green</option>
        <option value="blue">Blue</option>
      </select>
    </>
  );
};

There are parts about this component that make it less trivial to use within different rendering options. First, we obviously use the DOM directly, though only in the layout effect. Second, we use an effect — and a special one (“layout effect”), at that.

Using the DOM directly should be avoided as much as possible, but as seen in the example above, we sometimes miss the right methods to do things differently. To improve the situation, we could still guard this line like so:

if (typeof document !== 'undefined') {
  document.body.style.backgroundColor = color;
}

Or use some alternative check.

That still leaves us with useLayoutEffect. This one is highly rendering-specific and may not exist at all. For instance, using the renderToString function, we’ll get an error when we use this Hook.

One possibility, of course, is to fall back to the standard useEffect. But then we need to know the (not-so-obvious) difference between these two. In any case, the when of the useEffect execution is as foggy as the re-rendering strategy of calling the returned setter from a useState instance.

Let’s use this chance to step back a bit and explore why we care about any of this.

Comments

[Alex Lohr]

While this is a nice introduction to two of the basics, JSX and hooks, it stays very superficial. The switch from class components to hooks had brought a new architecture with it, called "fibers". Each of these fibers is the least complex representation of an element, hook or memoized value as an object, bound to each other in a tree and then being tree-walked on each render cycle, which means that fibers bound to a fiber that is inactive will not be visited.