Overlay for hydration errors with explicit diff between renders
Tags: render
Published: 2023-12-27 18:23:39

---
title: Overlay for hydration errors with explicit diff between renders
published: true
date: 2023-12-16 00:03:00 UTC
tags: Render
canonical_url: https://reactjsexample.com/overlay-for-hydration-errors-with-explicit-diff-between-renders/
---

# Hydration Overlay 🕵️
 ![Overlay for hydration errors with explicit diff between renders](https://reactjsexample.com/content/images/2023/12/Code_2023-12_19-58-46.jpg)

This package displays an overlay during Hydration Errors, providing an explicit diff between the server-side and client-side renders.

![Overlay for hydration errors with explicit diff between renders](https://github.com/BuilderIO/hydration-overlay/raw/main/imgs/after.png)

## Installation

```
npm install @builder.io/react-hydration-overlay
```

## Usage

### `HydrationOverlay`

First, wrap the root of your app in the `HydrationOverlay` component.

```
import { HydrationOverlay } from "@builder.io/react-hydration-overlay";

const App = () => {
  return (
    <HydrationOverlay>
      <YourApp />
    </HydrationOverlay>
  );
};
```

### Plugin

Second, add the plugin for your framework. Currently, we only support Next.js.

#### Next.js

in `next.config.js`:

```
const {
  withHydrationOverlay,
} = require("@builder.io/react-hydration-overlay/next");

/\*\* @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",
})(nextConfig);
```

## Notes

- This package is currently in beta. Please report any issues you find!
- This package is not intended for production use. We highly recommend you remove this package from your production builds.

## Caveats

This package works by comparing the HTML received from the server with the HTML rendered by the client, which has one improtant consequence. React re-renders the entire app when hydration fails, potentially introducing even more changes.

The biggest example is `style` attributes: React appends `;` to each one and alters the whitespace. In [more extreme examples](https://x.com/samijaber_/status/1734760349662957906?s=20), it causes enormous diffs for properties like `all: unset`.

Therefore, this tool will give you false positives for style changes.

## How It Works

- The plugin injects `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 resulting HTML then.
- The `HydrationOverlay` component reads both HTML strings and compares them, and renders the overlay.

## Support

To add support for other frameworks, what is needed is a plugin that injects the `hydration-overlay-initializer.js` script into the app’s entry point. See [next-plugin.ts](https://github.com/BuilderIO/hydration-overlay/blob/main/packages/lib/src/next-plugin.ts) for more information. PRs welcome!

- Next.js
- Remix
- Vite SSR

## GitHub

[View Github](https://github.com/BuilderIO/hydration-overlay?ref=reactjsexample.com)