DEV Community: Rinat Rezyapov

Gentle introduction to Relay framework (React + GraphQL)

Rinat Rezyapov — Fri, 20 Jan 2023 16:21:52 +0000

Table Of Content

Introduction
What is Relay?
What is GraphQL?
Why GraphQL is better than Rest API?
If GraphQL is better why Rest API is still here?
Some frequent questions from beginners or prejudices
Let's build React app with Relay
Structure of the project
Creating Node.js http server
Adding GraphQL support into our server
Creating React + Relay application
Generating schema.graphql file
Creating GraphQL query in our client app
Update Component

Introduction

This post aims to gently introduce React developers to Relay framework. We'll start with a brief description of Relay and GraphQL (in simple terms) and then we'll create a simple React app that makes one simple query. This is a very beginner-friendly introduction so I intentionally avoid deep dives or advanced examples. Let's start!

What is Relay?

In short, Relay is a framework that helps you to incorporate GraphQL query language into React applications.

What is GraphQL?

In simple terms, GraphQL is a better version of Rest API (this is the author's opinion and not an assertion).

Why GraphQL is better than Rest API?

For a number of reasons:

GraphQL has one endpoint instead of multiple. This helps frontend developers to develop application more quickly because there is no need to write new requests to backend or change old ones.
GraphQL uses a schema that describes entities and their types. This schema is synced between the frontend and the backend. GraphQL also generates documentation that allows frontend developers to compose queries without the help of backend developers or other manually created documentation.
You can request only the needed fields of an entity and request a set of different entities as one request. Imagine you fetched a book entity which has an authors field with an array of author ids. Now you need to make another request to fetch information about authors by id. This will create a waterfall problem in your React application. Relay and GraphQL handle this for you.

If GraphQL is better why Rest API is still here?

Moving from Rest API to GraphQL is a quite complex process. First of all, frontend and backend developers need to learn it and be on the same page. Secondly, public APIs can't just move to GraphQL overnight because the API consumers still use Rest API clients. Although, some public APIs can afford to have Rest API and GraphQL at the same time. And if your API is not public facing, after some preparations, you can gradually adopt GraphQL like it was done by Facebook. Finally, it's just hard to replace such a fundamental approach as Rest API. Perhaps, GraphQL will just occupy its niche as it was in the case of WebSockets.

Some frequent questions from beginners or prejudices

Q. Do you still need a state management library if you use Relay?
A. No, Relay can completely replace state management libraries such as Redux.
Q. Is Relay and GraphQL slower than Rest API?
A. Not as you can notice in the web application. There is some additional computational overhead regarding schema and typing system which could affect real-time applications or real-time game applications but for such applications, you wouldn't use JavaScript, let alone React, Relay, GraphQL...
Q. Does Relay (GraphQL) has Database requirements?
A. No, Relay (GraphQL) is agnostic to the data source.

Let's build React app with Relay

Structure of the project

-- React-Relay-App
---- client (Create React App)
---- server (Node.js + http)

Creating Node.js http server

Let's start with the server. We will create a simple Node.js server that will have GreetingsQuery which will answer with Hello World!.

Install Node.js
Go to React-Relay-App -> server folder and initialize npm (you need it to install npm packages later).

cd React-Relay-App
cd server
npm init

Then create index.js file and add the code for a simple http server that answers with status code 200 and Hello World text for now.

// ./server/index.js

const http = require('http');

const hostname = '127.0.0.1';
const port = 5000;

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

Launch created server by typing in the terminal:

node index

If everything is ok you should get this message:

Server running at http://127.0.0.1:5000/

Then open http://127.0.0.1:5000/ in the browser. Server should respond with Hello World.

Adding GraphQL support into our server

Install graphql-http npm package

npm i graphql-http

Import all necessary assets to create GraphQL Schema into index.js file.

// ./server/index.js

const { GraphQLSchema, GraphQLObjectType, GraphQLString } = require('graphql');
const { createHandler } = require('graphql-http/lib/use/node');

Then add the code for the GraphQL schema that has a query called GreetingsQuery with a greetings field that answers Hello World!.

// ./server/index.js

const schema = new GraphQLSchema({
    query: new GraphQLObjectType({
        name: 'GreetingsQuery',
        fields: {
            greetings: {
                type: GraphQLString,
                resolve: () => 'Hello World!',
            },
        },
    }),
});

After the schema is created we need to pass it to a handler.

// ./server/index.js

const handler = createHandler({ schema });

Then we can use this handler object in http.createServer function to handle all /graphql requests. Replace the previous content of http.createServer function with the following.

// ./server/index.js

const server = http.createServer((req, res) => {
    if (req.url.startsWith('/graphql')) {
        res.setHeader('Access-Control-Allow-Origin', '*');
        res.setHeader('Access-Control-Request-Method', '*');
        res.setHeader('Access-Control-Allow-Methods', 'OPTIONS, GET');
        res.setHeader('Access-Control-Allow-Headers', '*');
        if ( req.method === 'OPTIONS' ) {
            res.writeHead(200);
            res.end();
            return;
        }

        handler(req, res);
    } else {
        res.writeHead(200).end('Please, use /graphql suffix.');
    }
});

Ignore res.setHeader invocations since their purpose is to configure CORS and is not related to GraphQL directly.

Final result of our server code

// ./server/index.js

const http = require('http');
const { GraphQLSchema, GraphQLObjectType, GraphQLString } = require('graphql');
const { createHandler } = require('graphql-http/lib/use/node');

const hostname = '127.0.0.1';
const port = 5000;

const schema = new GraphQLSchema({
    query: new GraphQLObjectType({
        name: 'GreetingsQuery',
        fields: {
            greetings: {
                type: GraphQLString,
                resolve: () => 'Hello World!',
            },
        },
    }),
});

const handler = createHandler({ schema });

const server = http.createServer((req, res) => {
    if (req.url.startsWith('/graphql')) {
        res.setHeader('Access-Control-Allow-Origin', '*');
        res.setHeader('Access-Control-Request-Method', '*');
        res.setHeader('Access-Control-Allow-Methods', 'OPTIONS, GET');
        res.setHeader('Access-Control-Allow-Headers', '*');
        if ( req.method === 'OPTIONS' ) {
            res.writeHead(200);
            res.end();
            return;
        }

        handler(req, res);
    } else {
        res.writeHead(200).end('Please, use /graphql suffix.');
    }
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`);
});

Now let's re-start our server and open http://127.0.0.1:5000/graphql in the browser. You should get the following message:

{"errors":[{"message":"Missing query"}]}

Which is completely ok. GraphQL expects valid query, you can't make a request to a endpoint and get response, like you would do with GET method in Rest API.

Creating React + Relay application

Now, since our server is ready to answer GraphQL queries, we can start with our client-side part.
I will use Create React App tool to generate React application, but the steps below can be applied to any other React web application or even React Native mobile application.

Go to React-Relay-App folder and create React project with the name client.

cd React-Relay-App
npx create-react-app client

After the generation process is finished, go to the client folder and install all necessary packages.

cd client
npm i graphql react-relay relay-compiler babel-plugin-relay

graphql - the main GraphQL npm package
react-relay - the main Relay npm package
relay-compiler - goes through all your client files and parses GraphQL code
babel-plugin-relay - helps JavaScript to understand GraphQL code

Next, create relay.config.js file in client folder

// ./client/relay.config.js

module.exports = {
    src: "./src",
    language: "javascript",
    schema: "../data/schema.graphql",
    exclude: ["**/node_modules/**", "**/__mocks__/**", "**/__generated__/**"],
  }

src points to the folder where React components with GraphQL code will be located.
schema points to the shared between backend and frontend schema file. We will return to it later.

Also, create .babelrc file in the client folder and add the following content.

// ./client/.babelrc

{
  "plugins": [
    "relay"
  ]
}

Finally, add the following script into scripts section of package.json file.

// ./client/package.json

  "scripts": {
    "relay": "relay-compiler"
  }

We will launch this script every time we add new GraphQL code to our React components. For simplicity, we will do it manually.

Now let's launch Relay script that we added before.

npm run relay

We will get the following error:

 - The `schema` configured for project `default` does not exist at `../data/schema.graphql`.

That means that Relay on the client side expects schema.graphql from backend side to correctly validate GraphQL code in React components. In my opinion, this is the most important part of GraphQL because it completely elliminates misunderstandings between frontend and backend developers when using API and creates a strong contract between them.

Now let's go back to server and create a script that generates schema.graphql file.

Generating schema.graphql file

First, let's create data folder in React-Relay-App folder. Out project structure should look like this:

-- React-Relay-App
---- client
---- server
---- data

Then go into server folder and create updateSchema.js file with the following content.

// ./server/updateSchema.js

const fs = require('fs');
const path = require('path');
const { schema } = require('./index');
const { printSchema } = require('graphql');

const schemaPath = path.resolve(__dirname, '../data/schema.graphql');

fs.writeFileSync(schemaPath, printSchema(schema));

console.log('Finished updating schema ' + schemaPath);

This will generate schema.graphql file in the ../data/schema.graphql folder.

Now we need to export schema from our index.js file.

// ./server/index.js

module.exports = {
    schema
}

And let's add update script to package.json file of our server project:

// ./server/package.json


"scripts": {
    "update": "node ./updateSchema"
}

After that, run updateSchema script.

npm run update

If everything is ok, then you will get the message:

Finished updating schema \React-Relay-App\data\schema.graphql

And you can find generated schema.graphql file inside data folder with the following content:

schema {
  query: GreetingsQuery
}

type GreetingsQuery {
  greetings: String
}

Now, it's time to go back to our client and launch npm run relay one more time.

Creating GraphQL query in our client app

Now that we have schema.graphql file in the data folder, let's go to client folder and run npm run relay:

cd client
npm run relay

You should get the following message:

> client@0.1.0 relay
> relay-compiler

[INFO] [default] compiling...
[INFO] [default] compiled documents: 0 reader, 0 normalization, 0 operation text
[INFO] Done.

That means relay-compiler went through all files in client/src folder and didn't find GraphQL code, so there is nothing to generate. Let's fix it!

Create relay folder in client/src. Indside relay folder create environment.js file with the following content.

// ./client/src/relay/environment.js

import React from 'react';
import {
    Store,
    RecordSource,
    Environment,
    Network,
    Observable,
} from "relay-runtime";
import { RelayEnvironmentProvider } from "react-relay";

const fetchFn = (params, variables) => {
    const response = fetch("http://localhost:5000/graphql", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
            query: params.text,
            variables,
        }),
    });

    return Observable.from(response.then((data) => data.json()));
};

function createEnvironment() {
    const network = Network.create(fetchFn);
    const store = new Store(new RecordSource());
    return new Environment({ store, network });
}

export default function RelayEnvironment({ children }) {
    const environment = React.useMemo(() => {
        return createEnvironment();
    }, []);

    return (
        <RelayEnvironmentProvider environment={environment}>
            {children}
        </RelayEnvironmentProvider>
    );
}

Don't focus too much on these settings as they are made only once at the beginning of a project. What it does is creates wrapper around fetch and then passes it to Relay library which handles network requests. Then we create RelayEnvironment provider to use it as wrapper around our root App component.

Now, let's go to client/src/index.js file and wrapp out React application with RelayEnvironmentProvider:

// ./client/src/relay/index.js

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
import RelayEnvironment from './relay/environment';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <RelayEnvironment>
      <React.Suspense fallback="Loading...">
        <App />
      </React.Suspense>
    </RelayEnvironment>
  </React.StrictMode>
);

Notice, that we use React Suspense here which is a must when you use Relay.

We're almost done. Let's go to App component and create GraphQL request. We create AppQuery outside App component.

// ./client/src/App.jsx

import graphql from 'babel-plugin-relay/macro';

const AppQuery = graphql`
  query AppQuery {
    greetings,
  }
`;

function App() {
...

Relay enforces several rules, one is that we must start the name of a query with a component's name, so result should be AppQuery.

And then inside App component we use hook useLazyLoadQuery to make a query.

// ./client/src/App.jsx

function App() {
  const data = useLazyLoadQuery(
    AppQuery,
    {},
  );
...

After that we render data result in our App component as {data.greetings}. The full App component should look like this:

// ./client/src/App.jsx

import { useLazyLoadQuery } from 'react-relay';
import graphql from 'babel-plugin-relay/macro';
import logo from './logo.svg';
import './App.css';

const AppQuery = graphql`
  query AppQuery {
    greetings,
  }
`;

function App() {
  const data = useLazyLoadQuery(
    AppQuery,
    {},
  );

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          <code>{data.greetings}</code>
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
        and 
        <a
          className="App-link"
          href="https://relay.dev/docs/"
          target="_blank"
          rel="noopener noreferrer"
        >
          Relay
        </a>
      </header>
    </div>
  );
}

export default App;

Ok, we added GraphQL query. Now we can start the app and see results! Not so fast! After adding GraphQL code into React components we should run npm run relay so it can autogenerate needed code for runtime.

npm run relay
> client@0.1.0 relay
> relay-compiler

[INFO] [default] compiling...
[INFO] [default] compiled documents: 1 reader, 1 normalization, 1 operation text
[INFO] Done.

Notice that inside src folder the folder name __generated__ appeared. That's the runtime code that Relay is needed to function correctly. You don't need to look inside.

Now is the time to start server and client and see results!

Congratulations! We did it! I hope now you see why I choose to make this example as easy as possible. Even given that, the post turned out to be quite big.
Anyway, that's just 10% of the capabilities of Relay framework and GraphQL and ahead of us are mutations, arguments, variables, fragments and many more.

Links:

Build your own React.js - Part 4. State Updates

Rinat Rezyapov — Mon, 21 Feb 2022 19:42:24 +0000

Table Of Content

Introduction
Adding state to class component
Update Component

Introduction

In the previous articles, we implemented the mounting process of the class component and its children to the DOM. Although mounting into the DOM is the crucial step of the rendering process in React.js, it's the updating of the DOM where React.js really shines. As you may know, React.js do it by keeping "virtual" DOM in memory and syncing it with the real DOM, thus making DOM manipulations faster.

There are many ways to trigger an update process in React.js. It could be user interaction, some event triggered by setInterval or notification from a web socket. We will use a user interaction because it's the most common.

We know that React.js has setState API which updates state object and, by default, triggers re-rendering. setState can be launched in different parts of the application (except render() method of a class component), but for now, we will focus on updating state in response to user interaction with our application. For example, a user clicked a button, which triggered onClick event handler, which in turn updated the local state of the class component by calling setState.

Let's implement this flow but with one restriction, instead of adding support for event handlers to DOM nodes, e.g. onClick attribute of a button, we will use the click event listener and update the local state of a class component each time user clicks somewhere in the window of a browser. The reason for this restriction is that supporting event handling in React.js is a topic for another conversation. Maybe we will return to this subject later.

Adding state to class component

For now, let's change the App class component for our future local state implementation.

We will start by adding the constructor method to the App class component. Inside the constructor, we first call super method. This is an important step because overwise the state initialization won't work. If you want to know more about super Dan Abramov wrote a whole article about it.
Secondly, we initialize clickCount field with the value 0 inside state object of the App class component. We will also change the content of the render method with this.state.clickCount value rendering inside div element.

  // index.js

 class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      clickCount: 0,
    }
  }

  render() {
    return {
      type: "div",
      props: {
        children: this.state.clickCount
      }
    };
  }
}

Here I want to go back in time a little bit for those who follow Build your own React.js series from the beginning. Those who are new can skip this part.

Since we now render value with the type of number in the div element, we need to teach our DOMComponentWrapper to render numbers. We will do it by adding typeof props.children === "number" in the condition.

   // DOMComponentWrapper.js
  _createInitialDOMChildren(props) {
    if (
      typeof props.children === "string" || 
      typeof props.children === "number"
    ) {
      this._domNode.textContent = props.children;
    }
  }

Ok, let's return back to present times. Sorry for that little adventure in time.

Now we need to call setState every time a user clicks the left button of the mouse. For that, we need to add an event listener (remember we agreed that we won't add support for event handling?). Usually, we add an event listener in componentDidMount component's lifecycle, but since we don't have lifecycles yet, we are going to add it in the constructor of a class component.

I skipped clearing an event listener on the class component unmount intentionally (don't do it in a real project!).

  // index.js

 class App extends Component {
  constructor(props) {
    super(props);
    this.state = {
      clickCount: 0,
    }
    window.addEventListener('click', () => {
      this.setState({clickCount: this.state.clickCount + 1});
    })
  }
 ...

Let's now add setState method to the Component class so that the App class component can inherit it.

class Component {
  constructor() {
    ...
    this._pendingState = null;
    ...
  }
  setState(partialState) {
    this._pendingState = partialState;
    UpdateQueue.enqueueSetState(this, partialState);
  }
  ...

Method setState takes partialState as an argument. It's called partialState because setState doesn't require you to provide a full updated state object as an argument, it only needs part of the state that you want to update, so it can merge it into the current state object.

We assign partialState to this._pendingState in the constructor and then call UpdateQueue.enqueueSetState(this, partialState) with an instance of the App class component and partialState as an arguments.

Let's create UpdateQueue.js with enqueueSetState function.

// UpdateQueue.js
import Reconciler from "./Reconciler";

function enqueueSetState(instance, partialState) {
  instance._pendingState = Object.assign(
    {}, 
    instance.state, 
    partialState
  );
  Reconciler.performUpdateIfNecessary(instance);
}

Nothing special here, we just take partialState and merge it with the state object of the instance using Object.assign. Empty object as a first argument is just making sure that we create a new object every time.

In the real React.js library enqueueSetState also queueing multiple partialStates so that at the right time it could do batch update.

After that, we pass control to Reconciler.performUpdateIfNecessary(instance) which in turn passes control back to the method performUpdateIfNecessary of the instance of the App class component which in turn inherited from Component class.

// Reconciler.js

function performUpdateIfNecessary(component) {
  component.performUpdateIfNecessary();
}

It might seem weird to you that we call this intermediate performUpdateIfNecessary function that does nothing and then just call Component's performUpdateIfNecessary from it. Remember, in the real React.js there is more complicated logic inside these functions (such as batch state update) we just skip this logic and try to preserve the order of function calls.

In the Component class, we create performUpdateIfNecessary method and call Component's updateComponent method from it.

// Component.js

performUpdateIfNecessary() {
    this.updateComponent(this._currentElement);
}

Update Component

Now, let's look at the updateComponent method. It's a big one, so let's go through it step by step.

  updateComponent(nextElement) {
    this._currentElement = nextElement; // 1
    this.props = nextElement.props;
    this.state = this._pendingState; // 2
    this._pendingState = null;

    let prevRenderedElement = this._renderedComponent._currentElement;
    let nextRenderedElement = this.render(); // 3

    if (shouldUpdateComponent(prevRenderedElement, nextRenderedElement)) { // 4
      Reconciler.receiveComponent(this._renderedComponent, nextRenderedElement);
    }
  }
...

First, we update _currentElement and props of the App class component instance to the nextElement values.

this._currentElement = nextElement; 
this.props = nextElement.props;

In our case the nextElement will be just object:

{
  props: {
    title: "React.js"
  },
  type: App
}

Then we assign _pendingState which is { clickCount: 1 } to the current state of the App class component instance. And we clear _pendingState after that by setting it to null.
```
this.state = this._pendingState;
this._pendingState = null;
```
We assign this._renderedComponent._currentElement to prevRenderedElement variable and this.render() to nextRenderedElement variable.
```
let prevRenderedElement = this._renderedComponent._currentElement;
let nextRenderedElement = this.render();
```
The values of these variables, in our case, are following:
```
// prevRenderedElement 
{
    "type": "div",
    "props": {
        "children": 0 // this.state.clickCount
    }
}
// nextRenderedElement 
{
    "type": "div",
    "props": {
        "children": 1 // this.state.clickCount
    }
}
```
As you can see it's just the state of the div element in the App class component's render method before and after the user clicked and the event listener called this.setState({clickCount: this.state.clickCount + 1}) in the constructor of the App class component.
With these preparations, we are ready to decide whether should we update the component or just re-mount it. We call shouldUpdateComponent with the previous and the next div element.
```
shouldUpdateComponent(prevRenderedElement, nextRenderedElement)
```
Let's create a file with the name shouldUpdateComponent.js and create shouldUpdateComponent function inside:
```
// shouldUpdateComponent.js

function shouldUpdateComponent(prevElement, nextElement) {
  // this needs only for primitives (strings, numbers, ...)
  let prevType = typeof prevElement;
  let nextType = typeof nextElement;

  if (prevType === 'string') {
    return nextType === 'string';
  }

  return prevElement.type === nextElement.type;
}
```
Here you can see one of the two assumptions that React.js makes when comparing two trees of elements.

Two elements of different types will produce different trees.

In our case, the element div doesn't change its type so we can reuse the instance and just update it.

Let's return to updateComponent method of the Component class.

if (
     shouldUpdateComponent(
       prevRenderedElement, 
       nextRenderedElement
     )
    ) {
      Reconciler.receiveComponent(
        this._renderedComponent, 
        nextRenderedElement
      );
    }
    ...

We know that, in our case, shouldUpdateComponent will return true and Reconciler.receiveComponent will get called with the following parameters:

// this._renderedComponent
DOMComponentWrapper {
    _currentElement: {
        type: "div",
        props: {
            "children": "0"
        }
     },
    _domNode: {}
 }

// nextRenderedElement
{
    type: "div",
    props: {
        children: 1
    }
}

Let's add receiveComponent to the Reconciler.
```
// Reconciler.js

function receiveComponent(component, element) {
  component.receiveComponent(element);
}
```
Again, this is the place where more optimizations happen in the real React.js, for now, we won't focus on that.

The important part here is that the component argument of the function is not the App class component, but DOMComponentWrapper. That's because DOM elements (div, span, etc) that need to be rendered are wrapped in DOMComponentWrapper so that handling of these elements state (props, children) was easier and similar to handling class components state (see previous posts about DOMComponentWrapper).

Now we need to go to DOMComponentWrapper and add receiveComponent method.

  receiveComponent(nextElement) {
    this.updateComponent(this._currentElement, nextElement);
  }

  updateComponent(prevElement, nextElement) {
    this._currentElement = nextElement;
    // this._updateDOMProperties(prevElement.props, nextElement.props);
    this._updateDOMChildren(prevElement.props, nextElement.props);
  }

As you can see updateComponent for DOMComponentWrapper looks a bit different from Component's. I intentionally commented out this._updateDOMProperties because we are not interested in updating DOM properties for now and it will only complicate things.

So let's jump into this._updateDOMChildren:

  _updateDOMChildren(prevProps, nextProps) {
    let prevType = typeof prevProps.children;
    let nextType = typeof nextProps.children;
    if (prevType !== nextType) {
      throw new Error('switching between different children is not supported');
     }

    // Childless node, skip
    if (nextType === 'undefined') {
      return;
    }

     if (nextType === 'string' || nextType === 'number') {
      this._domNode.textContent = nextProps.children;
     }
   }

First, we throw an error if, in our case, the type of children of our div element is changing prevType !== nextType. For example from number 0 to string no data. We won't support it for now.

Secondly, we check if div element has children at all nextType === 'undefined'. If not, we skip.

Then we check if the type of children of the div element is string or number. That's our case because this.state.clickCount (which is child of the div) has the type of number.

So we just grab the nextProps.children and insert it into div text content.

Let's stop here because we already covered too much. At this point, you'll be able to open our app and see the number incrementing at each click. That means our custom written React.js library can handle the state.

Congratulation!

In the next posts, we will continue to improve the state handling in our library.

Links:

My experience migrating projects to Next.js

Rinat Rezyapov — Fri, 30 Apr 2021 17:41:30 +0000

Official documentation about migration to Next.js is pretty comprehensive and guides you through almost all the common steps that you need to take in the process.

Still, there could be some use cases specific only to your React.js application.

Pages folder

Next.js bases its file system routing on pages folder. This is a pretty neat approach but comes with some limitations. The problem with classic React.js applications is that some of them might not even have pages folder or have it deeply nested in the folder structure.

root
|
└───src
│   │
│   └───app
│       │   App.tsx
│       │   ...
|       └───pages
│   
└───template
│   │
│   └───components
│   └───colors

More to that - Next.js allows only two locations of pages folder:

root/pages
root/src/pages

So keep in mind that you'll have to do some folder structure refactoring before moving to Next.js.

Components that use Web API

You probably know that you can't use window object server-side and you need to always check whether window is defined before accessing it.

For components that extensively use Web API (charts, animations) and too complex to refactor, it's easier to dynamically import the whole component from the parent component.

import dynamic from 'next/dynamic';

const ChartsComponent = dynamic(
  async () => dynamic(() import('app/components/ChartsComponent')),
  { ssr: false },
)

Next Router isReady

Sometimes a user is redirected to your React.js application from other services with some information in query parameters. It could be an email about registration confirmation with confirmation token: https://yourReactApp.com/token or redirection from a OAuth provider.
In such cases you usually catch these query parameters using window.location.search and then process them.
I noticed that when I moved my application to Next.js these query parameters didn't appear in Next's router at first render and only on the second render I could see them in router.query. This behaviour broke my authentication process. Turned out that this is because Next's router fields are updated server-side first and only then client-side. To skip the first update with the empty query you have to use router.isReady field in useEffect hook as a second argument:

import { useRouter } from 'next/router';

const RedirectsCatcherComponent = () => {
  const router = useRouter();
  useEffect((() => {
    if (router.query.token) {
      proceedAuthentication(router.query.token);
    }
  }), [router.isReady])
}

Dockerfile

If you use Docker containers in your infrastructure you could use the example of Dockerfile in the official documentation or if you use npm:

FROM node:alpine AS builder

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
RUN npm install --production

USER node

FROM node:alpine
WORKDIR /usr/src/app
COPY --from=builder /usr/src/app .
EXPOSE 3000

ENV NODE_OPTIONS=--max_old_space_size=1024

CMD ["npm", "start"]

Basically what it does here is it builds static assets using production and dev dependencies and then install only production dependencies that needed to start Next.js server.

Notice ENV NODE_OPTIONS=--max_old_space_size=1024 here. If your Docker container resources are limited, the build process sometimes might crash with the error Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory. This environment variable solves the problem. Just make sure that is slightly lower value is set than Docker container memory limit value.

You are not static anymore

With great power comes great responsibility

I'm sure you decided to use Next.js mainly because you wanted to improve the performance of your React.js application with server-side rendering.
One thing to consider is that you as a frontend developer will be responsible for running Node.js server that will serve static assets. Everything that is running tends to crash, so bear in mind that you will need to consider some kind of failover solution. It could be pm2 or Nomad or even multiple Docker containers in nginx upstream configuration.

Can Next.js replace nginx?

It depends on what kind of job your nginx performs. If it's only modifying headers then Next.js can do it also. It even can set security headers with the help of a third party library.
For some more advanced use cases, such as determining the real user's IP address you would probably need to use custom Next.js server.

Authentication

As I said before, if you are using Next.js you are probably going to use server-side rendering.
A typical client-side React.js application usually uses JWT tokens for authentication and stores them in a browser's storage.
As you may also know browser's storage is not available server-side and you won't be able to get tokens and use them to make authenticated requests to the backend and render authenticated pages server-side.
If it's your case then you need to think about storing authentication tokens in cookies. After that you will be able to get authentication tokens in req.headers.cookie server-side.

async function getServerSideProps(context) {
  if (req.headers.cookie) {
    const token = getToken(req.headers.cookie);
    // make requests
  }
}

If you need to perform authentication client-side you just retrieve the cookies from the browser.

The process of moving from browser's storage to cookies in terms of storing tokens is usually pretty complex, especially if you are using an OAuth protocol.
If you store tokens client-side then you probably have a mechanism that periodically refreshes these tokens and checks if they are valid. You will need to move this mechanism to the backend side since the backend will be responsible for handling tokens and putting them in cookies. If you are using an OAuth provider, it's even harder. So think about this step in advance.

For now, that's it. From my experience, migrating to Next.js most of the time was a surprisingly positive experience, so if you planned to move to Next.js - make preparations and do it now!

Build your own React.js - Part 3. MultiChild

Rinat Rezyapov — Mon, 22 Feb 2021 18:38:45 +0000

Table Of Content

Introduction
Two cases of multichild
Implementing MultiChild class
ChildReconciler
Rendering

A flowchart of what we will cover in this article

Introduction

This is the third part of Build your own React.js series. Click here if you didn't read the second part.

In this part, we are going to implement the logic for rendering multiple children. It's a very important feature because without it React.js applications would consist of only one element and one child. Although you could have such mini components in your app it's not practical.

Two cases of multichild

In the previous article, we rendered our first class component into DOM.

  // index.js

  class App extends Component {
    render() {
      return {
        type: "div",
        props: { children: `We are building ${this.props.title}` }
      };
    }
  }

Our App class component has a children prop which is basically a string. JSX version of it would look like this:

  // index.js

  class App extends Component {
    render() {
      return (
        <div>
          {`We are building ${this.props.title}`}
        </div>
      )
    }
  }

How to render more children? To do this, we need to be able to handle an array of children. Like this:

  // index.js

  class App extends Component {
    render() {
      return {
          type: "div",
          props: { 
            children: [
              {
                type: "h1",
                props: { 
                  children: `We are building ${this.props.title}` 
                }
              }, 
              {
                type: "h2",
                props: { children: `And it's cool!` }
              }
            ]
          }
      }
    }
  }

or JSX version:

  // index.js

  class App extends Component {
    render() {
      return (
           <div>
             <h1>
               {`We are building ${this.props.title}`}
             </h1>
             <h2>
               {`And it's cool!`}
             </h2>
           </div>
      )
    }
  }

And here I want to stop a little bit on the cases of multi-child. There are actually two that you probably use every time but not aware that they are handled by React.js a little bit differently.

The first case is rendering DOM elements by declaring them in the render method like this:

    <div>
      <h1></h1>
      <h2></h2>
    <div>

Another one is rendering an array of DOM elements or strings like you usually do when you get an array of data from the server and want to show this data to the user:

   <div>
     {["Are we?", "Really?", ["Well...", "That is impressive"]]}
   <div>

Doesn't matter if in reality we would map over it and wrap each string into p element, React.js will handle any case.

Note, that an array can consist of subarrays and these cases also should be handled.

Why I separate these cases? Because in the second one, when we render an array of subarrays there is no such term as children. You can't say that subarray ["Well...", "That is impressive"] is children of its parent array, it's still children of div but we need to somehow indicate that it's subarray when we render it.

Yes, it's confusing so let's build MultiChild class to clarify this.

Implementing MultiChild class

From the previous articles, we remember that instantiateComponent function handles elements with children. It checks if the type of the element object is string e.g. 'div' and if so passes it to HostComponent.construct which in turn uses DOMComponentWrapper to create DOM element:

// Component.js

function instantiateComponent(element) {
  let wrapperInstance;
  if (typeof element.type === "string") {
    wrapperInstance = HostComponent.construct(element);
  }
  ...
  return wrapperInstance;
}

// HostComponent.js

function construct(element) {
  return new DOMComponentWrapper(element);
}

Since DOMComponentWrapper class creates the actual DOM element and it's children we need to handle multi children there. We will extend the existent _createInitialDOMChildren method of the DOMComponentWrapper class with the handler for props.children of array type:

// DOMComponentWrapper.js

//before
_createInitialDOMChildren(props) {
    if (typeof props.children === "string") {
      this._domNode.textContent = props.children;
    }
  }

//after
  _createInitialDOMChildren(props) {
    if (typeof props.children === 'string') {
      this._domNode.textContent = props.children;
    } else if (Array.isArray(props.children)) {
      let mountImages = this.mountChildren(props.children);
      DOM.appendChildren(this._domNode, mountImages);
    }
  }

You probably spotted a new this.mountChildren method there that DOMComponentWrapper class doesn't have. This method is a method of MultiChild class that we are going to implement and extend DOMComponentWrapper from it.

  // MultiChild.js

class MultiChild {
  mountChildren(children) {
    const renderedChildren = ChildReconciler.instantiateChildren(children);
    this._renderedChildren = renderedChildren;

    return Object.keys(renderedChildren).map((childKey, i) => {
      let child = renderedChildren[childKey];
      child._mountIndex = i;

      return Reconciler.mountComponent(child);
    });
  }
}

// DOMComponentWrapper.js

class DOMComponentWrapper extends MultiChild {
  constructor(element) {
    super();
    this._currentElement = element;
    this._domNode = null;
  }
...

Notice we added super() into DOMComponentWrapper constructor. It's basically the way of calling MultiChild class (parent) constructor before using DOMComponentWrapper class (child) constructor. More about that is here.

Now let's stop at ChildReconciler.instantiateChildren. The author of the original implementation added the following comment:

Instantiate all of the actual child instances into a flat object. This handles all of the complicated logic around flattening subarrays.

By reading this you normally think that it takes an object of elements and it's children and children's children and transforms it into a flat object. And it's a valid thought. But turns out that this function is implemented for slightly different purposes.

Unfortunately, our App class component has quite simple elements structure in its render and we won't see both two cases of multi-child that I mentioned later. So let's change the children prop of h1 element into an array in our App class component:

// index.js

{
      type: "div",
      props: { 
        children: [
          {
            type: "h1",
            props: { 
              children: [
                `We are building ${this.props.title}`, 
                [
                  'Are we?', 
                  'Really?', 
                  [
                    'Well...', 
                    'That is impressive'
                  ]
                ]
              ]
            }
          }, 
         {
           type: "h2",
           props: { children: `And it's cool!` }
         }
        ]
      }
  }

Now the children prop is an array of strings that contains another array of strings and so on. You might be confused by this example because in a real React.js app we use flat array of data and then transform it into elements using map method. But this example is also completely valid and I used it intentionally to show why ChildReconciler.instantiateChildren is necessary.

By the way, this is how the example above looks in JSX:


      <div>
        <h1>
          {[`We are building ${this.props.title}`, ['Are we?', 'Really?', ['Well...', 'That is impressive']]]}
        </h1>
        ...
      </div>

Now let's look at the abstract version of the output of ChildReconciler.instantiateChildren:

{
  '.0.0': "We are building Reactjs",
    '.1:0.0': "Are we?",
    '.1:1.0': "Really?",
      '.1:2:0.0': "Well...",
      '.1:2:1.0': "That is impressive",
}

Minimizing nesting is a common pattern in computer programming. This transformation will help not only to mount deeply nested children but also update them in the future.

ChildReconciler

Let's create ChildReconciler.js file and implement instantiateChildren in it.

// ChildReconciler.js

function instantiateChildren(children) {
  let childInstances = {};

  traverseAllChildren(children, instantiateChild, childInstances);

  return childInstances;
}

instantiateChildren holds childInstances object and passes it by reference to traverseAllChildren function. Once traverseAllChildren function is finished and childInstances object is populated, it returns it.

We also pass instantiateChild function to traverseAllChildren function as the second parameter. This function just checks if a child is already present in the childInstances object. If it's not present (isUnique) then it passed to instantiateComponent to be mounted into DOM and the result is added into childInstances object. name here is a unique identifier of the child that is generated by depth in the tree (mount index) and parent. Real React.js library also uses key prop here.

function instantiateChild(childInstances, child, name) {
  let isUnique = childInstances[name] === undefined;

  if (isUnique) {
    childInstances[name] = instantiateComponent(child);
  }
}

It's a little bit confusing here that instantiateChild function isn't declared in one file with traverseAllChildren and passed as a parameter but try to think of it in a way that traverseAllChildren takes childInstances object and instantiateChild function and use this function to populate childInstances object. Let's see how it happens:

// traverseAllChildren.js

const SEPARATOR = ".";
const SUBSEPARATOR = ":";

function traverseAllChildren(children, callback, traverseContext) {
  return traverseAllChildrenImpl(children, "", callback, traverseContext);
}

function traverseAllChildrenImpl(
  children,
  nameSoFar,
  callback,
  traverseContext
) {
  if (!Array.isArray(children)) {
    callback(
      traverseContext,
      children,
      nameSoFar + SEPARATOR + getComponentKey(children, 0)
    );
    return 1;
  }

  let subTreeCount = 0;
  let nextNamePrefix = nameSoFar === "" ? SEPARATOR : nameSoFar + SUBSEPARATOR;

  children.forEach((child, i) => {
    let nextName = nextNamePrefix + getComponentKey(child, i);
    subTreeCount += traverseAllChildrenImpl(
      child,
      nextName,
      callback,
      traverseContext
    );
  });

  return subTreeCount;
}

As you can see traverseAllChildren just calls traverseAllChildrenImpl. The first thought that you might have is that "Why just not call traverseAllChildrenImpl directly?". It's called in such a way because traverseAllChildrenImpl actually calls itself with the second parameter nameSoFar being always different (empty string at first call and then string identifier for a child). Of course, there are ways to call it directly with preserved functionality but that's not the scope of this article.

Before trying to understand how this quite big function works let's stop at getComponentKey function. Note how the component parameter of the function is not used but the author of the original implementation still left it here. That's because here React.js library uses the key prop to generate a unique id but we will just use toString(36). Number 36 is a radix. For numbers from 0 to 9, it will give a normal string representation of the number. For greater numbers it will use the letters of the alphabet alongside numbers, for example for 55 it will be 1j:

  function getComponentKey(component, index) {
    return index.toString(36);
  }

It's important to understand that traverseAllChildrenImpl function has two parts: one for non-array children and the second for array children. Also this function calls itself recursively and preserves subTreeCount alongside this calls by returning a number after each call.

subTreeCount is the counter for the number of children. We can't just use children.length here because as we saw earlier an array of children can contain subarrays.

Let's look at how traverseAllChildrenImpl processes our App class component:

type: "array"
nameSoFar: ""
parent: "div"
children: ["h1", "h2"]

type: "non-array" 
nameSoFar: ".0.0"
parent: "div" -> "array" // we can treat array also as a parent
children: "h1"

type: "non-array" 
nameSoFar: ".1.0"
parent: "div" -> "array"
children: "h2"

type: "array"
nameSoFar: ""
parent: "h1"
children: ["We are building Reactjs", ["Are we?", "Really?", ["Well...", "That is impressive"]]]

type: "non-array"
nameSoFar: ".0.0"
parent: "h1" -> []
children:  "We are building Reactjs"

type: "array"
nameSoFar: ".1"
parent: "h1" -> []
children:  ["Are we?", "Really?", ["Well...", "That is impressive"]]

type: "non-array"
nameSoFar: ".1:0.0"
parent: "h1" -> [[]]
children:  "Are we?"

type: "non-array"
nameSoFar: ".1:1.0"
parent: "h1" -> [[]]
children:  "Really?"

type: "array"
nameSoFar: ".1:2"
parent: "h1" -> [[]]
children:  ["Well...", "That is impressive"]

type: "non-array"
nameSoFar: ".1:2:0.0"
parent: "h1" -> [[[]]]
children:  "Well..."

type: "non-array"
nameSoFar: ".1:2:1.0"
parent: "h1" -> [[[]]]
children:  "That is impressive"

I think that a developer who knows how to console.log a function properly has a great advantage in quickly understanding what this function does. You will have your opportunity to console.log this function in a codesandbox example at the end of this article.

Again, don't get frustrated about not understanding some parts, it will come with time, just return to the example from time to time.

Note that ':' in nameSoFar denotes the fact that we entered a subarray. And '.0' at the end means that it's the non-array child.

Notice also that when children argument is not an array it calls callback function which is instantiateChild function. It actually populates childInstances object that we get at the end.

// ChildReconciler.js

function instantiateChild(childInstances, child, name) {
  let isUnique = childInstances[name] === undefined;
  if (isUnique) {
    childInstances[name] = instantiateComponent(child);
  }
}

As you can see we call instantiateComponent from instantiateChild. We know that instantiateComponent handles two types of elements:

Elements that has typeof type === 'string' (e.g. { type: 'div', props: ... });
Elements that has type field pointed to class: { type: App, props: ... };

But now as you can see we added another type of element which is a simple string, e.g. an element of the array ["Are we?", "Really?", ... ]. So now we need to also handle this type of elements:

// Component.js 

// before
function instantiateComponent(element) {
  let wrapperInstance;
  if (typeof element.type === "string") {
    wrapperInstance = HostComponent.construct(element);
  } else {
    wrapperInstance = new element.type(element.props);
    wrapperInstance._construct(element);
  }

  return wrapperInstance;
}

// after
function instantiateComponent(element) {
  let wrapperInstance;
  if (typeof element.type === "string") {
    wrapperInstance = HostComponent.construct(element);
  } else if (typeof element.type === 'function') {
    wrapperInstance = new element.type(element.props);
    wrapperInstance._construct(element);
  }  else if (typeof element === 'string' || typeof element === 'number') {
    wrapperInstance = HostComponent.constructTextComponent(element);
  }

  return wrapperInstance;
}

As you can see, typeof element === 'string' || typeof element === 'number' checks if elements is a simple string or number and then we call HostComponent.constructTextComponent. Let's add this function to HostComponent file:

// HostComponent.js
function constructTextComponent(element) {
  return construct({
    type: "span",
    props: {
      children: element
    }
  });
}

Basically, every string and number is wrapped in a span element using construct function which calls DOMComponentWrapper wrapper class.

Rendering

We are almost finished. Now let's go to the place where all this started.

// MultiChild.js

class MultiChild {
  mountChildren(children) {
    const renderedChildren = ChildReconciler.instantiateChildren(children);
    this._renderedChildren = renderedChildren;

    return Object.keys(renderedChildren).map((childKey, i) => {
      let child = renderedChildren[childKey];
      child._mountIndex = i;

      return Reconciler.mountComponent(child);
    });
  }
}

After we've got renderedChildren flat object we transform it into an array of keys [".0.0", ".1:0.0", ...], iterate over it and assign this keys to the respective child's property _mountIndex. We will use _mountIndex in the future when we perform updates. Then we call Reconciler.mountComponent with each child to get DOM element and all this is getting returned return Object.keys(renderedChildren) to the DOMComponentWrapper's _createInitialDOMChildren method and assigned into mountImages variable in the form of an array of DOM elements - [span, span, span, ...]

// DOMComponentWrapper.js

_createInitialDOMChildren(props) {
    if (typeof props.children === "string") {
      this._domNode.textContent = props.children;
    } else if (Array.isArray(props.children)) {
      let mountImages = this.mountChildren(props.children);
      DOM.appendChildren(this._domNode, mountImages);
    }
  }

Now we can append these DOM elements into our root node:

// DOM.js

function appendChildren(node, children) {
  if (Array.isArray(children)) {
    children.forEach(child => appendChild(node, child));
  } else {
    appendChild(node, children);
  }
}

That's it, we did it!

This is a flowchart of what we've covered so far

Feel free to open it in the second tab/monitor and go through this article again.

Now if you think that it was difficult, hold on! We are going to implement update logic in the following articles.

Links:

Build your own React.js - Part 2. React.Component

Rinat Rezyapov — Sat, 23 Jan 2021 14:27:07 +0000

Introduction

First of all, thank you for all your likes in the previous article, it encouraged me to finish the second part as soon as possible. If some parts of these articles seem confusing to you, please, leave a comment. It will be super helpful.

This is a second part of Build your own React.js series. Click here if you didn't read the first part.

Table Of Content

Implementing Component
Implementing DOMComponentWrapper
DOM

Implementing Component

In the previous article, we stopped at creating our first App class and passing it to render (ReactDOM.render in React.js) function. We figured out that in order to continue we need to implement Component class (React.Component in React.js) and extend App class from it.

From instantiateComponent function, we know that when we create an instance of the App class we pass element.props to its constructor and then call _construct method.

  // Component.js

  function instantiateComponent(element) {
    const wrapperInstance = new element.type(element.props);
    wrapperInstance._construct(element);

    return wrapperInstance;
  }

This means that Component class should be able to handle element.props in its constructor and should have the _construct method so that App class could inherit them.

Turns out this part is pretty simple. We get element.props in the constructor and assign them to this.props so that our instance of the App class could have access to its props.

  // Component.js

  class Component {
    constructor(props) {
      this.props = props;
      this._currentElement = null;
    }

    _construct(element) {
      this._currentElement = element;
    }
  }

In the _construct method, we assign { type: App } element, to the _currentElement. We will discuss why we do it a little bit later.

Remember that only class instances can have this. It's an oversimplification but when you create, let's say an App class by declaring class App, you create a blueprint of the instance of that App class and it doesn't have this. But when you call new App() (we do it in instantiateComponent) you create an instance of the App class that has it's own this. In the Component class by saying this.props or this._currentElement we are referring to the props and _currentElement of the instance of whatever class that will extend Component class. Again, it's a very simplified explanation but hopefully, it will help you understand the logic behind this.

For now, let's return to the place where we created the App class and passed it to render. Since now we have Component class let's extend App class from it.

  // index.js

  class App extends Component {}

  ReactDOM.render(
    { type: App, props: { title: "React.js" } },
    document.getElementById("root")
  );

From now we can call our App class not just a class but a class component.

As you can see I also added props field to the element object to check if Component class constructor works. To see results, we need to go back to the mount function and console.log the result of the instantiateComponent function call.

  // react-dom.js

  function mount(element, node) {
    node.dataset[ROOT_KEY] = rootID;
    const component = instantiateComponent(element);
    console.log(component);
  }

  App: {
    props: {
      title: "React.js"
    },
    _currentElement: {
      type: App,
      props: {
        title: "React.js"
      }
    }
  }

On this scheme, App class component instance has its own props and _currentElement fields (this section) and get mountComponent and _construct methods from Component class using prototype chain (__proto__ section). If you want to know more about prototype chain, I would recommend to look at this video: The Definitive Guide to Object-Oriented JavaScript.

Nice! We've got an instance of our App class component with the fields that we expected.

Try to look at the dev console yourself using this Codesandbox example (marked as App instance in dev console).

Now let's continue implementing the mount function.

  // react-dom.js

  let instancesByRootID = {};
  let rootID = 1;

  function mount(element, node) {
    node.dataset[ROOT_KEY] = rootID;
    const component = instantiateComponent(element);

    instancesByRootID[rootID] = component;
    const renderedNode = Reconciler.mountComponent(component, node);
  }

We add the newly created instance of the App class component to the instancesByRootID object by rootID. We will need instancesByRootID object later when we will perform the update and unmount.

Next, we call mountComponent of the Reconciler. This is where the fun begins.

  // Reconciler.js

  function mountComponent(component) {
    return component.mountComponent();
  }

As you can see, mountComponent just calls mountComponent of the instance of the App class component itself. Since App class component extends Component class, we need to add mountComponent method to Component class.

  // Component.js

  class Component {
    ...
    mountComponent() {
      const renderedElement = this.render();
      ...
    }
  }

In the mountComponent we start with calling this.render function. You may think that it's the function that we've implemented at the beginning, i.e. ReactDOM.render but it's not. Remember how in the real React.js library we usually create a class component with render method and return jsx from it? That's the method that we call here. Except that we will use objects instead of jsx.

Notice how we declared render in App class component unlike previously we declared, for example, mountComponent in Component class. That's because mountComponent is an internal mechanism which is controlled by React.js library itself. render method in the App class component, on the other side, is controlled by developers, by you. You may say "How about props? Props are controlled by developers, but the assignment of props happens in the Component class". That's true, but we actually just say to React.js library "Hey! I need to pass these props to this class component" and React.js creates an instance of this class component with the props that you passed. In the real React.js application we never assign props inside of the constructor of the class component, right?

Do you remember what we usually assign in the constructor when we create a class component?

That's right! We assign state. So React.js kind of says to developer "Put the data that periodically changes in the state and put some jsx into render when you create a class component. And I will do the rest". That's really important to understand to go further.

Now we need to go to the App class component and create render method that returns div element with the text We are building ${this.props.title} as a child.

  // index.js

  class App extends Component {
    render() {
      return {
        type: "div",
        props: { children: `We are building ${this.props.title}` }
      };
    }
  }

  // is the same as
  class App extends Component {
    render() {
      return <div>{`We are building ${this.props.title}`}</div>
    }
  }

Let's look at the results of calling this.render in the Component class implementation.

  // Component.js

  mountComponent() {
    const renderedElement = this.render();
    console.log(renderedElement);
    // { type: "div", props: { children: `We are building ${this.props.title}` } }
    const renderedComponent = instantiateComponent(renderedElement);
  }

We've got what we declared in the render method of the App class component. Nice! Then, we call instantiateComponent with this result.

Implementing DOMComponentWrapper

The current implementation of instantiateComponent expects element.type to be a class component. So we need to add support for DOM elements in the element.type, i.e. div, a. Pay attention that we use string ("div") to describe a DOM element and not actual HTML tag (div).

  // Component.js

  // before
  function instantiateComponent(element) {
    const wrapperInstance = new element.type(element.props);
    wrapperInstance._construct(element);

    return wrapperInstance;
  }

  // after
  function instantiateComponent(element) {
    let wrapperInstance;
    if (typeof element.type === 'string') {
      wrapperInstance = HostComponent.construct(element);
    } else {
      wrapperInstance = new element.type(element.props);
      wrapperInstance._construct(element);
    }

    return wrapperInstance;
  }

We added the condition that checks if the type of element.type is a string (e.g. "div") and if it's true, we call HostComponent.construct which is very simple. I think the real React.js does some more work here and it was left in such a way just to preserve the structure.

  // HostComponent.js

  function construct(element) {
    return new DOMComponentWrapper(element);
  }

DOMComponentWrapper, as you can see from the name, is a class wrapper around DOM elements (such as "div"). This wrapper is necessary for storing the state (don't confuse with the class component state) of the element. Also, it creates homogeneity between handling class components and DOM elements because it's quite similar to Component implementation.

  // DOMComponentWrapper.js

  class DOMComponentWrapper {
    constructor(element) {
      //element == {type: "div", props: {children: We are building ${this.props.title}}}
      this._currentElement = element;
    }
  }

For now, we just get an element in the constructor and assign it to the _currentElement.

Now we need to return to the mountComponent of the the Component class. We get DOMComponentWrapper from instantiateComponent and pass it to Reconciler.mountComponent. Remember we used it in mount function in the beginning? The difference is that we used it to mount App class component and now we use it to mount the content of render method of an App class instance.

  // Component.js

  class Component {
    constructor(props) {
      this.props = props;
      this._currentElement = null;
      this._renderedComponent = null;
    }
    ...
    mountComponent() {
      const renderedElement = this.render();
      const renderedComponent = instantiateComponent(renderedElement);
      console.log(renderedComponent) // DOMComponentWrapper

      this._renderedComponent = renderedComponent; // needed for update 
      return Reconciler.mountComponent(renderedComponent);
    }
  }

Don't feel frustrated if you don't understand some parts - it will make sense after several passes as it was in my case. Also, there will be a flowchart at the end of the article that will, hopefully, help you to build a mental model of the process.

In Reconciler we call mountComponent of the DOMComponentWrapper.

  // Reconciler.js

  function mountComponent(component) { // DOMComponentWrapper
    return component.mountComponent();
  }

Let's implement it.

  // DOMComponentWrapper.js

  class DOMComponentWrapper {
    constructor(element) {
      this._currentElement = element;
      this._domNode = null;
    }

    mountComponent() {
      let el = document.createElement(this._currentElement.type);
      this._domNode = el;
      this._createInitialDOMChildren(this._currentElement.props);
      return el;
    }
  }

We take element from _currentElement that we assigned when we created DOMComponentWrapper and use it to create a div DOM element by calling document.createElement('div'). Exciting!

_domNode will hold the newly created DOM element.

Now time to create children of this div element. For it, we need to implement _createInitialDOMChildren.

  // DOMComponentWrapper.js

  class DOMComponentWrapper {
    constructor(element) {
      this._currentElement = element;
      this._domNode = null; // <div></div>
    }
    ...
    _createInitialDOMChildren(props) {
      // element === { children: `We are building ${props.title}` }
      if (typeof props.children === "string") {
        this._domNode.textContent = props.children;
      }
    }
  }

We assume for now, that children prop of the element can only be of string type.

In _createInitialDOMChildren we get DOM node from _domNode and assign children prop, which is string, to its textContent attribute. Now we have

  <div>We are building React.js</div>

DOM element.

We are very close to rendering our App class component to the screen.

Let's return to the mount function and add final steps.

  // react-dom.js

  function mount(element, node) {
    node.dataset[ROOT_KEY] = rootID;
    const component = instantiateComponent(element);
    instancesByRootID[rootID] = component;
    const renderedNode = Reconciler.mountComponent(component, node);
    console.log(renderedNode) // <div>We are building React.js</div>
  }

DOM

We know that Reconciler.mountComponent(component, node) returns a DOM element. We need to append it to the root node <div id="root"></div> in our HTML file so we could see it in the browser. For that let's create DOM tools. They are pretty easy. [].slice.call(node.childNodes) is just a way to create an array from node.childNodes because originally node.childNodes is not an array.

  // DOM.js

  function empty(node) {
    [].slice.call(node.childNodes).forEach(node.removeChild, node);
  }

  function appendChild(node, child) {
    node.appendChild(child);
  }

If you are not sure what the DOM is, you may read this article.

Now let's empty our root node in case if something was appended to it before and then append <div>We are building React.js</div> to it using DOM.appendChild(node, renderedNode). Then we increment rootID (we will discuss later why we do it).

  // react-dom.js

  function mount(element, node) {
    node.dataset[ROOT_KEY] = rootID;
    const component = instantiateComponent(element);
    instancesByRootID[rootID] = component;
    const renderedNode = Reconciler.mountComponent(component, node);
    DOM.empty(node);
    DOM.appendChild(node, renderedNode);
    rootID++;
  }

Voila! We rendered our first Class Component to the screen using our own React.js implementation.

Codesandbox example

Feel free to open it in the second tab/monitor and go through this article again.

In this article, we were able to render only one child { children: We are building ${this.props.title} } but in the real React.js application we usually have multiple children. In the next episode of the Build your own React.js series we will implement MultiChild class that will help us with that.

Links:

Build your own React.js - Part 1. ReactDOM.render

Rinat Rezyapov — Wed, 20 Jan 2021 19:17:49 +0000

Introduction

These series of articles are based on the Paul O Shannessy - Building React From Scratch talk that he gave in 2016.

He also uploaded source code to the GitHub repo.

Unfortunately, the talk was only 30 minutes long and to fully understand each part of this simplified implementation of React.js I spent days reading the source code and the comments. Even though the comments and the talk were super helpful, some parts of the code were like rocket science to me, especially recursive labyrinths of madness, until I was enlightened.

And now I decided to create a series of articles based on my notes and 'aha' moments.

I also recently found out that React.js team added their annotations to Building React From Scratch talk. And this document is pretty good (I hope it was available when I first started deep dive in it) but I still decided to create my own, more detailed version, maybe someone will find it easier to understand.

Main points to consider before starting to read these articles:

This is simplified React.js implementation, meaning that some parts of React.js are not included, such as refs, function components, keys, rendering arrays e.t.c;
This is the implementation of pre-fiber React.js. That is 15.x.x version;
For simplicity sake, I'm going to change some confusing for me parts of the original implementation and I'm not going to use package dependencies at all. That means, for example, instead of using babel plugin to transform jsx I will describe elements using JavaScript objects;
These articles are written in a very simple way so even beginners in JavaScript and React.js should understand what is going on;
At the end of each article, I will put a link to Codesandbox example and flowchart of what we've covered.
The source code will be available in this repo (by commit for each article);

Someone might ask a question "Why to spend time trying to understand the mechanics of the older version of React.js?"

Because I think you need to know "how it started" to understand "how it's going".

Let's go!

How it starts

Let's start with refreshing our memory about how elements are described in React.js without using jsx.

  // Describing component
  <App /> -> { type: App }
   // Describing component with props
  <App title="React.js" /> -> {type: App, props: {title: "React.js"}}

  // Describing element
  <div></div> -> { type: "div" }

Notice the difference: for class component we use class component itself in the type field, for a DOM element we use string representation of this element. For now, that's all that we need to know.

I also want to clarify that by saying element I mean two things:

Object with the type field pointing to a class component (App) or DOM element ('div');
Simple JavaScript string (remember we can render strings?);

As you may know, typical React.js application starts by calling ReactDOM.render function where we pass an element as the first argument and a node which we use as a mounting point as the second argument.

To simplify things I want to add one restriction: we pass only class component element as the first argument to ReactDOM.render.

ReactDOM.render({ type: App }, document.getElementById("root"))

Let's look at how we would implement this render function.

function render(element, node) {
  if (isRoot(node)) {
    update(element, node);
  } else {
    mount(element, node);
  }
}

As you can see, render function checks by using isRoot function whether we already mounted App class component to the node with the root id or not. If the class component is already mounted we perform the update, if not mount.

  const ROOT_KEY = "root";

  function isRoot(node) {
    return node.dataset[ROOT_KEY];
  }

isRoot checks if our node has an HTML5 dataset attribute with the name data-root. We set this attribute in the mount function, which we will discuss later.

Mount

Since initially we didn't mount anything to the node and didn't set data-root attribute we skip update and call mount function.

  function mount(element, node) {
    node.dataset[ROOT_KEY] = rootID;
    const component = instantiateComponent(element);
    ... 
  }

In the mount, we set data-root attribute of the node to signalise that we are performing mounting.

Then, we instantiate the class component. Let's discuss what it means.

instantiateComponent will be used in several places and several conditions will be added to the body of the function in the future but for now, we just assume that element argument will be an object with the type field pointing to a class component.

  function instantiateComponent(element) {
    const wrapperInstance = new element.type(element.props);
    wrapperInstance._construct(element);

    return wrapperInstance;
  }

Since element.type points to a class component we can use it to create an instance of this class component.

From React.js docs: Class components have instances, but you never need to create a component instance directly—React takes care of this.

Well, in this case, we are building our own React.js so we have to take care of this :) Calling new element.type(element.props) in the following code snippet is the same as calling class constructor new App(element.props).

  const element = { type: App, props: { title: "React.js" }}
  new element.type(element.props) ---> new App({ title: "React.js" })

After an instance of the class component is created instantiateComponent function calls this strange _construct method of the newly created instance. But what the heck is _construct? Let's answer this question by trying to fire up what we already implemented. Spoiler alert: It will break.

First render

We will create App class component and use a div element with root id in our HTML file as a mounting point just as we do it in a real React.js application. But watch carefully, doesn't something look suspicious to you?

class App {}

render({ type: App }, document.getElementById("root"));

Codesandbox example

That's right! Our App class must extend React.Component class to become a legitimate React.js class component. And _construct method of the instance of App class that we created is actually the method of React.Component class that App inherits when we create it as:

  class App extends React.Component {

  }

Let's call our implementation of React.Component just Component from now.

If you are not sure how classes and prototype chain work in JavaScript I recommend watching this video about it.

This is a flowchart of what we've covered so far:

That's it for now. In the next episode of the Build your own React.js series we will implement Component class.

Thanks for reading! If you liked this article and want more content like this, checkout my blog and make sure to follow me on Twitter!

Links: