Better hydration errors are coming to Next.js!

Better hydration errors are coming to Next.js!

Hydration errors have been a complete meme in the web development space. Developers usually criticize the lack of good developer experience when it comes to hydration errors as they didn't use to provide useful errors.... until now.

If you prefer video content, I have uploaded a YouTube video on my channel on the same topic.

Before we move forward if you don't already know what hydration errors are, they are the errors that are displayed when the server renders the React tree, and the initial render by the client is different. However, there are more reasons, and I'd love to link the hydration errors section in the Next.js documentation.

So Guillermo Rauch (CEO of Vercel) recently tweeted the following.

The hydration error diffs displayed in the tweet do really seem pretty cool. They would help many developers spot where the hydration error is coming from, which is a positive step towards the developer experience.

These changes are in the canary version of Next.js that is not recommended for production as it could have bugs.

So I decided to make a sample app with hydration errors and comparing the hydration errors received in the latest stable version vs the canary version.

Reproducing a hydration error

I have reproduced hydration errors using Date. I have made a server component where I'm computing the current Date and passing it to a nested client component.

Following is the code for app/page.tsx.

import ClientComponent from "@/components/client-component";

export default function Home() {
  const date = new Date();

  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <ClientComponent date={date.toString()} />

Following is the code for client-component.tsx.

"use client";

export default function ClientComponent({ date }: { date: string }) {
  return <div>{Date().toString() || date}</div>;

As you can see, ClientComponent is a client component nested inside a server component and being provided a date as prop. The client tries to render Date().toString() and if it fails, it renders the date sent by the server. Now, if we had a real server, the time zones would be different, and it would be an instant hydration error. However, in the dev server, the time zones are same and you need to reload the page a couple of times to see the hydration errors (to get seconds different on the client and server).

Of course, there might be better ways of doing this, but this is just what came to my mind first, so here we go.

Hydration error in the current stable version

Here's the hydration error displayed when I ran the above code using the current stable version of Next.js (14.1.1).

Hydration errors in Next.js 14.1.1

It's not the best error, especially when looking at the new one. However, it's way better than before when we absolutely had no idea what was causing the hydration errors.

Hydration error in the canary version

Please do not use the canary version of Next.js in the production environment. It could result in bugs. This article is using canary version for educational purposes. The new hydration errors will eventually be coming to the stable version.

So, the warnings aside, the command to install the canary version of Next.js is the following.

npm install next@canary

Now, when we run the code, we see the following hydration error.

Hydration errors in the canary version of Next.js

This is a much cleaner error! We see the exact diff, locate where the error is happening, see what the client and the server are rendering, and fix the error! Well, if you're stuck on some annoying hydration error, I'd recommend checking out Next.js documentation on fixing hydration errors.


Who am I kidding? People will still create memes on hydration errors, and I'm all in for that. Sometimes, they're funny.

On a serious note, I think this is definitely a step towards a better developer experience. Developers have been complaining about the terrible developer experience offered by Next.js ever since the app router and RSC came around. I think with time, things should be fixed.