Understanding React Hydration

One of the central ideas of Gatsby is that HTML content is statically generated using React DOM server-side APIs. Another key feature is that this static HTML content can then be enhanced with client-side JavaScript via React hydration, which allows for app-like features in Gatsby sites.

What is hydration?

Hydration is the process of using client-side JavaScript to add application state and interactivity to server-rendered HTML. It’s a feature of React, one of the underlying tools that make the Gatsby framework. Gatsby uses hydration to transform the static HTML created at build time into a React application.

A typical React application relies on client-side rendering. Instead of parsing HTML to create the DOM, client-side rendering uses JavaScript to create it. A minimal HTML document serves as the application container, and only contains links to the JavaScript and CSS necessary to render the application.

With client-side rendering, most actions trigger local DOM updates instead of network requests. Clicking a navigation link builds the requested page on the client instead of requesting it from the server. Because they make fewer network requests, applications rendered in the browser provide a blazing-fast user experience — after the initial download.

That’s the drawback to client-side rendering: none of your site’s content is visible or interactive until the client downloads JavaScript and builds the DOM. However, not all clients can construct a DOM. For example, client-side rendering can prevent search engines and social media crawlers from consuming and indexing your site’s URLs. Browser users, on the other hand, may see a blank page or loading image while your JavaScript bundle downloads and executes.

Server-side rendering makes HTML available to the client before JavaScript loads. Your site visitors can see and read your content even if it is not fully interactive. Server rendering eliminates the blank page problem. Rendered HTML also makes it easier for search engines and social media crawlers to consume your site. Server-side rendering also has a drawback: every URL request requires another round trip to the server.

Hydration lets you take a hybrid approach.

Note: You’ll sometimes see developers use re-hydration instead of hydration. They’re interchangeable.

Gatsby’s build process uses Node.js and ReactDOMServer to create two different versions of your site. Each URL is available as both a static HTML page, and as a JavaScript component.

When a visitor requests their first URL from your site, the response contains static HTML along with linked JavaScript, CSS, and images. React then takes over and hydrates that HTML. React adds event listeners to the DOM created during HTML parsing, and turns your site into a full React application. Subsequent page requests are DOM updates managed by React.

How Gatsby uses React hydration

Build and render static assets

Running gatsby build starts up a Node.js server that processes your site: It creates a GraphQL schema, fetches data that your pages will pull in by extracting queries from your code and executing them, and it then renders each page’s HTML. You can read the GraphQL Concepts guide to learn how all parts interact with each other. The “Overview of the Gatsby Build Process” conceptual guide helps explain what’s happening at each step in the build process.

All of this data is gathered during the build and written into the /public folder. You can customize Gatsby’s configurations for Babel and webpack, as well as the HTML generated by your build, in order to tweak how your site gets built.

The ReactDOMClient.hydrateRoot method

The hydrateRoot() method is called internally by Gatsby from react-dom/client, which according to the React docs is:

Same as createRoot(), but is used to hydrate a container whose HTML contents were rendered by ReactDOMServer. React will attempt to attach event listeners to the existing markup.

Please note: If you need to, the hydrateRoot method can be replaced with a custom function by using the replaceHydrationFunction Browser API.

This means that the browser can “pick up” where the server left off with the contents created by Gatsby in the /public folder and render the site in the browser like any other React app would. Since the data and structure of the pages is already written out, it’s not necessary for Gatsby to go to another server asking for HTML or other data.

Partial hydration

If you don’t need the aforementioned app-like features everywhere and only need a bit of interactivity on your page here and there, then you should use Gatsby’s Partial Hydration feature. It enables you to only mark specific parts of your site as interactive while the rest of your site stays static by default. There will be no React hydration for these static portions. Follow the Partial Hydration how-to guide to learn more.

Additional resources

• Rendering on the Web from Google
• ReactDOMClient.hydrateRoot() from the React API Reference
• Partial Hydration Conceptual Guide