Show HTML Diff in Dev Error Overlay for Hydration Errors

[karlhorky]

Describe the feature you'd like to request

Hi there 👋 As always, thanks for the continuing effort on Next.js!! 🙌

The messaging for hydration errors in the dev overlay in Next.js leave something to be desired.

Hydration errors can happen for a variety of reasons, but looking at an example of invalid DOM nesting (based on Triggering validateDOMNesting causes Hydration failed (#36765)), the error is very generic and not very helpful (especially for beginners).

Here's a StackBlitz: https://stackblitz.com/edit/nextjs-iqm44f?file=pages%2Findex.js

Paging to the 2nd and 3rd errors using the arrows at the top left, the messages and traces are also equally generic:

If you open the DevTools console, you will find some more useful information:

However, this is hidden away in the DevTools, and mixed in with other generic or misleading errors:

Describe the solution you'd like

Error messages for any hydration errors in the dev overlay should be:

A) Useful B) Immediately actionable (without further research)

For me, this would indicate:

1. Displaying the expected and actual html
2. Displaying the component name and filename where the error occured (maybe also a clickable link to the file)
3. Displaying a "diff"-type design of the expected and actual html, formatted and syntax highlighted, like the one below

- server
+ client

-<p>
+<p />
  <p>initial</p>
-</p>
+<p />

cc @gaearon

Describe alternatives you've considered

Creating an ESLint rule to catch the issue before the error ever appears in the browser: https://github.com/jsx-eslint/eslint-plugin-react/issues/3310

[gaearon]

I wonder if this is a good time to consider showing console.error from React in the box. Because conceptually they are errors and typically contain the actual cause before something throws.

[karlhorky]

Nice, TIL about the WIP PRs to React from @gaearon and @himself65

• https://github.com/facebook/react/pull/24250
• https://github.com/facebook/react/pull/27808

[karlhorky]

Alternative: @samijaber created @builder.io/react-hydration-overlay, which could be pulled into Next.js core

• https://github.com/BuilderIO/hydration-overlay
• https://www.npmjs.com/package/@builder.io/react-hydration-overlay

[himself65]

This is cool

Alternative: @samijaber created @builder.io/react-hydration-overlay, which could be pulled into Next.js core

• BuilderIO/hydration-overlay
• npmjs.com/package/@builder.io/react-hydration-overlay

[himself65]

It captures two timestamp html and uses DiffViewer.

https://github.com/BuilderIO/hydration-overlay/blob/661aa0e17a50777fe9d7222fe0759d84798b1c3e/packages/lib/src/Overlay.tsx#L8

[huozhi]

We landed a hydration diff in 14.2.0, please checkout the blog post! I'll close this issue for now!

Related PRs: #62590, #62684, #62728, #63342 #62993, #63288, #63365, #63403

[karlhorky]

Amazing, thanks @huozhi 🎉 Look forward to using it. This will be a huge help for learners / beginners too.

[rtman]

@huozhi Ive just tried this and am not seeing any diff or component stack. Is this only for app router (we are using pages). Is there something that I need to do to enable this?

For reference I'm using 14.2.3

[huozhi]

@rtman can you file a new issue with reproduction for this? Thanks

[github-actions[bot]]

This closed issue has been automatically locked because it had no new activity for 2 weeks. If you are running into a similar issue, please create a new issue with the steps to reproduce. Thank you.