Dev.to

Understanding Hydration Errors by building a SSR React Project

If you’ve written React code in any server-rendered framework, you’ve almost certainly gotten a hydration error. These look like: Text content does not match server-rendered HTML or Error: Hydration failed because the initial UI does not match what was rendered on the server And after the first time you see this, you quickly realize you can just dismiss it and move on… kind of odd for an error message that’s so in-your-face (later on, we’ll see that you might not want to dismiss them entirely). So, what is a hydration error? And when should you care about them vs ignore them? In this post, we’re going learn more about them by building a very simple React / Express App that uses server-side rendering. But before we can answer that, we need to know what Server-Side Rendering is in the first place. What is server side rendering? Server-Side Rendering (SSR) is a technique where the server renders the HTML of a page before sending it to the client. Historically, you’d find SSR applications commonly used along-side template engines like Jinja, Handlebars, or Thymeleaf (for all my Java friends out there) — which made the process of building applications like this simple. We can contrast this with Client-Side Rendering (CSR) where the server sends a minimal HTML file and the majority of the work for rendering the page is done in javascript in the browser. Building an example React SSR application To start, we’ll install Express for our server and React: npm install express react react-dom Then, we’ll make a basic React component with a prop: import React from 'react'; interface AppProps { message: string; } function App({ message }: AppProps) { return {message} } export default App; Finally, we make an Express server that renders this component: import express from 'express'; import React from 'react'; import { renderToString } from 'react-dom/server'; import App from './components/App'; const app = express(); const htmlTemplate = (reactHtml: string) => ` React SSR Example ${reactHtml} `; app.get('/', (req, res) => { const message = 'Hello from the server!'; const appHtml = renderToString(React.createElement(App, { message })); const fullPageHtml = htmlTemplate(appHtml) res.send(fullPageHtml); }); app.listen(3000, () => { console.log(`Server running at http://localhost:3000`); }); We run our server, navigate to http://localhost:3000, and we see that it worked: But, let’s see what happens when we add a counter to our component: function App({ message }: AppProps) { const [count, setCount] = React.useState(0) return ( {message} Counter: {count} setCount(c => c+1)}>Increment ); } It loads correctly, but clicking the button doesn’t do anything: This is because renderToString produces static HTML but doesn’t have any Javascript for handling events (like onClick ). What we need is a way for the browser to attach event handlers and enable interactivity on top of server-rendered HTML — and that’s what hydration does. Hydrating our React Application The key function here is hydrateRoot, whose description is: hydrateRoot lets you display React components inside a browser DOM node whose HTML content was previously generated by react-dom/server. We can contrast that with createRoot, which you’ll find in CSR applications: createRoot lets you create a root to display React components inside a browser DOM node. createRoot assumes that it is setting up / displaying all the React components from scratch. hydrateRoot assumes that it is setting up / displaying all the React components on top of our server rendered HTML. If we look back on our htmlTemplate, you can see that we are rendering our server HTML inside a div tag with an ID: [server-rendered-html] So to “hydrate” our application, we just need to add some Javascript code on the client side, calling hydrateRoot and referencing this div: import React from 'react'; import { hydrateRoot } from 'react-dom/client'; import App from './components/App'; hydrateRoot( document.getElementById('root'), ); // Note that for this example, we're hard-coding the props // But in a real application, we'd pass them down from the server // One way to do this is to add a tag that sets // window.__INITIAL_PROPS__ = {"message": "Hello from the server!"} // and then loads it here. To make sure this runs, we’ll also need to update our template to add this script. We can add that underneath our ${reactHtml} in our template: ${reactHtml} For the purposes of not making this post too long, I am skipping over an important step here which is bundling our client entrypoint. For that you can use something like Vite or Rollup. But, once we have that set up and we run our new code with hydrateRoot, our counter now works: What happens when the

Apr 4, 2025 - 17:55
 0
Understanding Hydration Errors by building a SSR React Project

If you’ve written React code in any server-rendered framework, you’ve almost certainly gotten a hydration error. These look like:

Text content does not match server-rendered HTML

or

Error: Hydration failed because the initial UI does not match what was rendered on the server

And after the first time you see this, you quickly realize you can just dismiss it and move on… kind of odd for an error message that’s so in-your-face (later on, we’ll see that you might not want to dismiss them entirely).

So, what is a hydration error? And when should you care about them vs ignore them?

In this post, we’re going learn more about them by building a very simple React / Express App that uses server-side rendering.

But before we can answer that, we need to know what Server-Side Rendering is in the first place.

What is server side rendering?

Server-Side Rendering (SSR) is a technique where the server renders the HTML of a page before sending it to the client.

Historically, you’d find SSR applications commonly used along-side template engines like Jinja, Handlebars, or Thymeleaf (for all my Java friends out there) — which made the process of building applications like this simple.

We can contrast this with Client-Side Rendering (CSR) where the server sends a minimal HTML file and the majority of the work for rendering the page is done in javascript in the browser.

Building an example React SSR application

To start, we’ll install Express for our server and React:

npm install express react react-dom

Then, we’ll make a basic React component with a prop:

import React from 'react';

interface AppProps {
    message: string;
}
function App({ message }: AppProps) {
    return <div><h1>{message}</h1>div>
}
export default App;

Finally, we make an Express server that renders this component:

import express from 'express';
import React from 'react';
import { renderToString } from 'react-dom/server';
import App from './components/App';

const app = express();
const htmlTemplate = (reactHtml: string) => `



  
  React SSR Example


  
${reactHtml}



`;
app.get('/', (req, res) => {
    const message = 'Hello from the server!';
    const appHtml = renderToString(React.createElement(App, { message }));
    const fullPageHtml = htmlTemplate(appHtml)
    res.send(fullPageHtml);
});
app.listen(3000, () => {
  console.log(`Server running at http://localhost:3000`);
});

We run our server, navigate to http://localhost:3000, and we see that it worked:

Image that says

But, let’s see what happens when we add a counter to our component:

function App({ message }: AppProps) {
    const [count, setCount] = React.useState(0)
    return (
        <div>
            <h1>{message}</h1>
            <p>Counter: {count}</p>
            <button onClick={() => setCount(c => c+1)}>Increment</button>
         </div>
    );
}

It loads correctly, but clicking the button doesn’t do anything:

This is because renderToString produces static HTML but doesn’t have any Javascript for handling events (like onClick ).

What we need is a way for the browser to attach event handlers and enable interactivity on top of server-rendered HTML — and that’s what hydration does.

Hydrating our React Application

The key function here is hydrateRoot, whose description is:

hydrateRoot lets you display React components inside a browser DOM node whose HTML content was previously generated by react-dom/server.

We can contrast that with createRoot, which you’ll find in CSR applications:

createRoot lets you create a root to display React components inside a browser DOM node.

createRoot assumes that it is setting up / displaying all the React components from scratch. hydrateRoot assumes that it is setting up / displaying all the React components on top of our server rendered HTML.

If we look back on our htmlTemplate, you can see that we are rendering our server HTML inside a div tag with an ID:

 id="root">[server-rendered-html]

So to “hydrate” our application, we just need to add some Javascript code on the client side, calling hydrateRoot and referencing this div:

import React from 'react';
import { hydrateRoot } from 'react-dom/client';
import App from './components/App';

hydrateRoot(
    document.getElementById('root'), 
    <App message="Hello from the server!" />
);
// Note that for this example, we're hard-coding the props
// But in a real application, we'd pass them down from the server
// One way to do this is to add a