Skip to content

Show HTML Diff in Dev Error Overlay for Hydration Errors #37847

@karlhorky

Description

@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

Screen Shot 2022-06-20 at 16 23 37

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

Screen Shot 2022-06-20 at 16 24 09

Screen Shot 2022-06-20 at 16 25 29

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

Screen Shot 2022-06-20 at 16 26 29

Screen Shot 2022-06-20 at 16 26 51

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

Screen Shot 2022-06-20 at 16 26 47

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: jsx-eslint/eslint-plugin-react#3310

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions