Docs

What Causes Hydration Errors?

Server-side rendering in Next.js uses client-side hydration, provided by React. Hydration adds Javascript to make web pages interactive, but can cause errors if the HTML sent from the server doesn't match what's rendered by the client.

For example, if you render Date().now() from the server, Next.js will create text representing the current date and time in the HTML that's shipped to the client. When the client renders attempts to hydrate the HTML page, it will render a different date and time, since it hydrates at a different time.

function App () {
const time = Date.now();
return (
<div>
<p>{time}</p>
</div>
)
}

This component will render a div with a paragraph element. Next.js will send something like this from the server:

<div>
<p>282724948</p>
</div>

Since you're accessing the current time, down to the millisecond, when the client receives the HTML and bundle from the server, it'll try to render a different time. Something like this:

<div>
<p>246753764</p>
</div>

You can see how the server has one copy of HTML, and the client has a different copy. When React tries to hydrate, it'll throw an error because it's seeing a different HTML page.

Often, React will continue with its hydration process, and it does an excellent job. After all, the goal of the React team is to make sure your page can load. The same is true for HTML. As your page loads, if there are errors such as improper nesting, HTML will still create your web page. These improper HTML errors can go unnoticed because they're not brought to your attention, and nothing appears to break. However, they can impact your page load time and SEO score. A common example of HTML errors is improper nesting:

<p>
<div></div>
</p>

The problem is that a div should not be nested in a p tag. While this might seem obvious, some custom components can create nested div errors without your knowledge. For example, let's say we have this component:

function CoolStuff () {
return (
<div>
This is cool!
</div>
)
}

Looks like it just renders some text, so you might throw it into a div tag in your App, like this:

function App () {
return (
<div>
<p><CoolStuff/></p>
</div>
)
}

Your HTML now looks like this:

<div>
<p>
<div>
This is cool!
</div>
</p>
</div<

It might seem obvious, but you might never see an error in this case. Our extension checks for these errors, as well as the errors mentioned above. While we can't provide the solution to each hydration error, we can more effectively point you to the problem.

Tree Visualization

When using the extension on a Next.js, React, or Gatsby page, you can click the show tree button to see your DOM tree. Our algorithm names each node after its DOM node name. You might see many DIVs, P tags, etc. We do this to check for hydration errors, but you can use the tree visualizer for any other reason.

Our visualizer begins at the root node. First, it checks to see if the root node was hydrated. If not, you have a hydrateRoot error. Check the React docs for more info.

In addition to each node name, the tree checks for text content and event emitter functions. If there are any mismatches, the node is flagged. Note that sometimes your tree can hydrate with incorrect event emitters, so you can use the DOM tree to quickly check which functions are tied to which nodes.

Check the error message included in any nodes that are flagged. They can help point you in the correct direction to solve your problem.

Debugging Hydration Errors

Our debugging tool will point you in the right direction to show you which node is causing problems. It won't tell you exactly how to solve the issue though. Since a wide range of problems could cause hydration errors, there are too many to account for and document here.

If you get stuck, remember that there are a few common causes of hydration errors:

• Trying to access the Document or Window object within a component. Put any function or variable using external APIs in a useEffect hook or similar function so that they won't activate before your page loads.


• Rendering anything that could change as time goes by in a component. That includes using the Date object.


• Using custom or imported components that cause improper nesting errors


• If you're still having trouble, walk through your DOM tree and compare it to the components your server is trying to render. Try to spot any differences in the tree visualizer.

Performance Metrics

Our extension uses Lighthouse, Google's monitoring tool, to track your site's performance. It breaks reports into a few categories: performance, SEO, accessability, and best practices. We show you each score, as well as tips to improve performance.

The point of Next.js and other server-side rendering frameworks is to decrease load times and improve user experience. Performance problems can negate the awesome power of SSR. Fixing hydration errors helps with performance, but we offer other tips from Lighthouse to make sure you're fully realizing the potential of your framework.

Navigate to the performance tab to see your site's metrics. Give it a few seconds to load, then you can see your scores and tips to improve performance.

Saving Metrics

We offer a login option if you want to save performance metrics. This feature is useful if you want to track improvements in performance over time. You don't need to login to see metrics, but if you want them to persist over time, you need to login.

Tracking your performance over time can help you see the impact of your design decisions. To get the most out of our performance monitoring tool, we recommend logging in.