Watch Webinar: Figma - Design to Code in 80% Less Time

Announcing Visual Copilot - Figma to production in half the time logo
Talk to Us
Contact Sales
Talk to Us










Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required



Get StartedLogin

‹ Back to blog

Web Development

Announcing React Hydration Overlay - Easily Squash Hydration Errors

December 13, 2023

Written By Sami Jaber

TL;DR: go to to install the overlay and debug your hydration mismatch.

Last week, I spent hours debugging a tricky hydration mismatch. I had to:

  • copy the HTML sent over the wire,
  • console.log the HTML generated on the client and copy it,
  • paste both of them into an online diff checker tool.

I got tired of doing this, so I automated it. Hence!

How does it work?

The solution I landed on is fairly rudimentary (like all the best solutions!). The package works in 2 parts:

  • First, you use a plugin to inject hydration-overlay-initializer.js into your app's entry point. This script reads the HTML from the server and stores it, and then listens for hydration errors and stores the page's HTML that exists then.
  • Second, you wrap your app's root in HydrationOverlay, a component that will read the data from the previous step and display it in an overlay.

Currently, only Next.js via a Webpack Plugin. But PRs are more than welcome: what you need is to inject a script into the bundle's entry point, which is fairly straightforward task.

Install the dependnecy with npm (or pnpm, yarn, etc):

npm install

Add the overlay component to the root of your app:

import { HydrationOverlay } from "";

const App = () => {
  return (
      <YourApp />

Add the plugin to your next.config.js

const {
} = require("");

/** @type {import('next').NextConfig} */
const nextConfig = {
  /** your config here */

module.exports = withHydrationOverlay({
   * Optional: `appRootSelector` is the selector for the root element of your app. By default, it is `#__next` which works
   * for Next.js apps with pages directory. If you are using the app directory, you should change this to `main`.
  appRootSelector: "main",

And that's all. Read more in the project readme

As anyone who's had a React hydration mismatch knows, the errors are rather cryptic. In a large page, it becomes extremely difficult to find the mismatched element. While this tool isn't perfect, it automates away a cumbersome manual process that many currently resort to to pin down the exact mismatch.

NOTE: There is a WIP PR to fix this in React, so hopefully there will be a native solution to this problem soon. This plugin will remian handy for all older React versions.

When hydration fails, React will re-render your app on the client-side. It turns out that React renders things slightly differently in SSR VS CSR. The most visible one I've seen is style HTML attributes: whitespace and semi-colons are added in the CSR, and in some cases, the attributes are re-ordered and shorthand attributes are expanded (the most extreme case is all: unset which can seemingly turn into hundreds of properties!). So keep in mind that there will be some false positives when using this plugin. I still firmly believe that it is a net positive to have this tool in your arsenal when debugging hairy issues!

That's it! Go fix your hydration bugs!

Introducing Visual Copilot: convert Figma designs to code using your existing components in a single click.

Try Visual Copilot


Hand written text that says "A drag and drop headless CMS?"

Introducing Visual Copilot:

A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Like our content?

Join Our Newsletter

Continue Reading
Web Development15 MIN
Figma to Vue: Convert Designs to Clean Vue Code in a Click
WRITTEN BYVishwas Gopinath
June 14, 2024
Web Development12 MIN
Figma to Angular: Convert Designs to Clean Angular Code in a Click
WRITTEN BYVishwas Gopinath
May 16, 2024
Web Development18 MIN
Getting Started with Mitosis: Creating a Cross-Framework Design System
WRITTEN BYVishwas Gopinath
May 7, 2024