YIN - Build our own React SSR framework

In this article, we are going to build our own SSR framework with React + Vite + Express.

You can think of it as a really simple version of Next.js 12 with the ability to SSR according to the file-routes system, performing client-side route change and user event after hydration.

Now let’s get started.

TL:DR

CSR vs. Traditional SSR
Introduce React SSR
Build our React SSR
SSR with routing
Wrap up 🚀

CSR vs. Traditional SSR

Client Side Rendering

CSR refers to Client Side Rendering. If you are familiar with React, then you are familiar with CSR.

When a user enters a website, browser will get an empty HTML file with a script requesting for our React JS file.

1<!doctype html>
2<html lang="en">
3  <head>
4    <!-- ... -->
5  </head>
6  <body>
7    <div id="root"><!-- we get empty div here --></div>
8    <script type="module" src="/src/main.tsx"></script>
9  </body>
10</html>

After loading and finish executing the React, React will then mount the entire App to the browser, at this point can the user finally see and interact with the website UI.

As you may notice, the rendering of the page content can only starts after React takes over control, this can lead to some drawbacks:

Users initially see only empty HTML while waiting React to load and execute, this lead to bad user experience
Since empty HTML lacks the website information and body, it’s bad for the SEO.

Traditional Server Side Rendering

SSR refers to Server Side Rendering. Traditionally, SSR means that when the user enters a website, the server renders the HTML with all the content it needs and respond to the client. This is better for SEO and the “initial” user experience.

Notice that I use “initial”. For the later user interaction, such as route change within the same page, the user will always have to request a new HTML, this can lead to bad interaction experience later.

Comparison on CSR and Traditional SSR

In the next section, we will introduce React SSR, which combines the advantages of traditional SSR and CSR.

Introduce React SSR

So what do you mean by “React SSR combines the advantages of traditional SSR and CSR”?

Well, the concept behind React SSR is actually a combination of Traditional SSR and CSR.

Concept of React SSR

When a user enters a website, the server will render the React App into HTML using a method called renderToString provided by React and sends the HTML back to the user. With this, user gets a contentful HTML initially.

And since the app is written with JSX, React can simply use the those JSX components on the client side too. This means, when the initial HTML is loaded on the browser, React “hydrates” the same components into the pre-rendered HTML, meaning it attaches client-side logic such as hooks and events onto the HTML, building a copy of vDOM, and taking control of the all subsequent user interactions.

Comparison on CSR, Traditional SSR and React SSR

Now we know the concepts, in the next section, we will start to build our simple React SSR framework with React, Vite and Express.

Build our React SSR

In this section, we will build our React SSR with Vite and Express.

Feel free to check the repo here 👈🏻

Project setup

Vite actually provides a CLI to setup all we need to build a React SSR.

1$ npm create vite-extra@latest
2# Project name: react_ssr_ssg_demo
3# Select a template: › ssr-react
4# Select a variant: › TypeScript

Then run:

1$ cd react_ssr_ssg_demo
2$ npm install
3$ npm run dev

Here is the current project structure:

1.
2├── index.html # container HTML
3├── package-lock.json
4├── package.json
5├── public
6│   └── vite.svg
7├── server.js # server for HTML requests
8├── src
9│   ├── App.css
10│   ├── App.tsx # our react app 
11│   ├── assets
12│   │   └── react.svg
13│   ├── entry-client.tsx # react for hydration
14│   ├── entry-server.tsx # react for rendering react app into HTML on server
15│   ├── index.css
16│   └── vite-env.d.ts
17├── tsconfig.json
18├── tsconfig.node.json
19└── vite.config.ts

React SSR flow

When a user enters the website, our server will get a request for HTML, this request is handled by server.js .

server.js processes the request, get the url and giving it to entry-server.tsx, this is where React renders the React components according to the url into HTML string using a method called renderToString.

After server.js get the HTML string returned from entry-server.tsx, it puts the string into index.html and sends back to the browser. Now the user sees the initial rendered HTML.

Parsing the server-rendered HTML, browser will see the script:

1<script type="module" src="/src/entry-client.tsx"></script>

and requests for our client side react entry-client.tsx. After loading client side React, React will “hydrate” the entire vDOM into current HTML, attaching all hooks and events onto it, and taking control over the later user interaction.

Let’s walk through each file.

server.js

First, create a server and listen to a port:

1// server.js
2
3import express from 'express'
4
5// Constants
6const port = process.env.PORT || 5173
7
8// Create http server
9const app = express()
10
11// Start http server
12app.listen(port, () => {
13  console.log(`Server started at http://localhost:${port}`)
14})

Second, Vite provides us Hot Module Reload functionality, which lets us refresh our project when saving files, however, we don’t need this function in production, thus, we will declare a flag to determine whether we are in production mode or not:

1// server.js
2
3// Constants
4const isProduction = process.env.NODE_ENV === 'production'
5
6// Add Vite or respective production middlewares
7let vite
8if (!isProduction) {
9  const { createServer } = await import('vite')
10  vite = await createServer({
11    server: { middlewareMode: true },
12    appType: 'custom',
13    base
14  })
15  app.use(vite.middlewares)
16} else {
17  const compression = (await import('compression')).default
18  const sirv = (await import('sirv')).default
19  app.use(compression())
20  app.use(base, sirv('./dist/client', { extensions: [] }))
21}

Third, handle the request from the browser, and server HTML back to browser. We will get the rendered HTML from entry-server.tsx here and put it into the index.html:

1// Cached production assets
2const templateHtml = isProduction
3  ? await fs.readFile('./dist/client/index.html', 'utf-8')
4  : ''
5const ssrManifest = isProduction
6  ? await fs.readFile('./dist/client/.vite/ssr-manifest.json', 'utf-8')
7  : undefined
8
9// Serve HTML
10app.use('*', async (req, res) => {
11  try {
12    const url = req.originalUrl.replace(base, '')
13
14    let template
15    let render
16    if (!isProduction) {
17      // Always read fresh template in development
18      template = await fs.readFile('./index.html', 'utf-8')
19      template = await vite.transformIndexHtml(url, template)
20      render = (await vite.ssrLoadModule('/src/entry-server.tsx')).render
21    } else {
22      template = templateHtml
23      render = (await import('./dist/server/entry-server.js')).render
24    }
25
26    const rendered = await render(url, ssrManifest)
27
28    const html = template
29      .replace(`<!--app-head-->`, rendered.head ?? '')
30      .replace(`<!--app-html-->`, rendered.html ?? '')
31
32    res.status(200).set({ 'Content-Type': 'text/html' }).send(html)
33  } catch (e) {
34    vite?.ssrFixStacktrace(e)
35    console.log(e.stack)
36    res.status(500).end(e.stack)
37  }
38})

index.html

For index.html, the content will be replaced by the rendered HTML by server.js , and being send back to the browser. Noted that it will request entry-client.tsx once being parsed on the browser:

1<!--index.html-->
2
3<!DOCTYPE html>
4<html lang="en">
5  <head>
6    <meta charset="UTF-8" />
7    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
8    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
9    <title>Vite + React + TS</title>
10    <!--app-head-->
11  </head>
12  <body>
13    <div id="root"><!--app-html--></div>
14    <script type="module" src="/src/entry-client.tsx"></script>
15  </body>
16</html>

entry-server.tsx

For entry-server.tsx, what it does for now is to render the React App (JSX) into HTML string using a method provided by react-dom/server called renderToString :

1// entry-server.tsx
2
3import React from 'react'
4import ReactDOMServer from 'react-dom/server'
5import App from './App'
6
7export function render() {
8  const html = ReactDOMServer.renderToString(
9    <React.StrictMode>
10      <App />
11    </React.StrictMode>
12  )
13  return { html }
14}

entry-client.tsx

For entry-client.tsx, what it will do is to build a vDOM by the same React App pre-rendered on server and “hydrates” all client side hooks and events into the HTML on the client side.

One important thing to be noted is that we are using hydrateRoot method instead of createRoot , with hydrateRoot , we are not switching the HTML with our client React rendered App, instead we attach the client side logic into the HTML.

1import './index.css'
2import React from 'react'
3import ReactDOM from 'react-dom/client'
4import App from './App'
5
6ReactDOM.hydrateRoot(
7  document.getElementById('root') as HTMLElement,
8  <React.StrictMode>
9    <App />
10  </React.StrictMode>
11)

Server-rendered HTML must have a same DOM tree as the client React DOM tree, or else React will throw a “hydration error” to you in the console.

For example, if the server renders:

1const html = ReactDOMServer.renderToString(
2  <React.StrictMode>
3    <div>hihi</div>
4  </React.StrictMode>
5);

While client React renders:

1ReactDOM.hydrateRoot(
2  document.getElementById("root") as HTMLElement,
3  <React.StrictMode>
4    <App />
5  </React.StrictMode>
6);

You will get a hydration error like this:

SSR with routing

For now, our App still lack of routing system, let’s add one to it.

We will mimic the Nextjs file routing system using React Router DOM.

1$ npm i react-router-dom

Then create /pages folder inside /src , add some page components to it:

1.
2├── src
3│   │
4│   └── App.tsx
5│   ├── pages
6│   │   ├── About.tsx
7│   │   └── Home.tsx

1// src/pages/Home.tsx
2
3import { useState } from "react";
4import { Link } from "react-router-dom";
5
6const Home = () => {
7  const [count, setCount] = useState(0);
8  
9  const onClick = () => {
10    setCount(count + 1)
11  }
12
13  return (
14    // <div>
15    //   this is home page
16    //   <button 
17    //   type={"button"}
18    //   onClick={onClick}
19    //   >
20    //     add
21    //   </button>
22    //   <Link to="/about">to about page</Link>
23    // </div>
24  );
25};
26
27export default Home;

1// src/pages/About.tsx
2
3import { Link } from "react-router-dom";
4
5const About = () => {
6  return (
7    // <div>
8    //   this is about page
9    //   <Link to={"/"}>to home page</Link>
10    // </div>
11  );
12};
13
14export default About;

For App.tsx, erase all default content and add some routing logic to it:

1// src/App.tsx
2
3import { Route, Routes } from "react-router-dom";
4
5// Vite supports importing multiple modules
6// from the file system via the special import.meta.glob function
7const PagePathsWithComponents = import.meta.glob("./pages/*.tsx", {
8  eager: true,
9}) as Record<string, Record<any, any>>;
10
11const routes = Object.keys(PagePathsWithComponents).map((path: string) => {
12  const name = path.match(/\.\/pages\/(.*)\.tsx$/)![1];
13
14  return {
15    name,
16    path: name === "Home" ? "/" : `/${name.toLowerCase()}`,
17    component: PagePathsWithComponents[path].default,
18  };
19});
20
21export default function App() {
22  return (
23    <Routes>
24      {routes.map(({ path, component: Component }) => {
25        return <Route key={path} path={path} element={<Component />} />;
26      })}
27    </Routes>
28  );
29}

It imports all files with name .tsx as extension, and renders the component with matched route:

1<Routes>
2  {routes.map(({ path, component: Component }) => {
3    return <Route key={path} path={path} element={<Component />} />;
4  })}
5</Routes>

In entry-client.tsx , wrap the <App /> with BrowserRouter provider just like what we will do in normal CSR react app, this allows user to perform client-side route change when going to another page through <Link> provided by React Router DOM:

1// entry-client.tsx
2
3import { BrowserRouter } from "react-router-dom";
4
5// ...
6ReactDOM.hydrateRoot(
7  document.getElementById("root") as HTMLElement,
8  <React.StrictMode>
9    <BrowserRouter>
10      <App />
11    </BrowserRouter>
12  </React.StrictMode>
13);

In entry-server.tsx , however, we will use StaticRouter , this is because we will not memorize the route change history when user hit the route directly in the url bar since we don’t have History API like browserRouter does in the browser, we will render whole new HTML that matches the current url:

1// entry-server.tsx
2
3import { StaticRouter } from "react-router-dom/server";
4
5// ...
6const html = ReactDOMServer.renderToString(
7  <React.StrictMode>
8    <StaticRouter location={"/" + url}>
9      <App />
10    </StaticRouter>
11  </React.StrictMode>
12);

Now when user visit certain page through refresh or typing inside url bar, we will serve them whole new HTML, while navigating through <Link> button on browser, we will navigate to new page through client side routing:

Wrap up 🚀

That’s all for this article, we’ve learned what React SSR solves and how to build our own React SSR with file-routing system.

We still have a lot of functionalities to be built, such as Static Site Generation and pre-fetching data before rendering HTML. We will leave them to the future articles.

That’s it, thank you for reading, hope you enjoy it 🚀.