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.

The steps taken to deliver a built site to the browser are discussed below:

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.

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 ReactDOM.hydrate method

The hydrate() method is called internally by Gatsby from ReactDOM, which according to the React docs is:

Same as render(), but is used to hydrate a container whose HTML contents were rendered by ReactDOMServer.

Note: if you need to, the hydrate 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.

Transfer rendering to the React reconciler

After ReactDOM hydrates the content, the React reconciler can take over and diff the tree of elements. It then becomes responsible for making updates in the UI based on changing state or props.

Additional resources

Edit this page on GitHub