Using Replay to Solve Hydration Errors

[scefali]

Introduction

Hydration Errors are quite common yet hard to fix. They happen when the HTML in the first render cycle doesn't match the HTML sent by the server. It causes both a full re-render can sometimes can cause adverse side effects. Currently, hydration errors are being filtered out by Sentry's inbound filters because Sentry cannot give helpful debugging information and they are very noisy. Our goal is to make hydration errors actionable so developers can actually fix them.

Using Session Replay

We can use session replays to display a visual and html diff of when the app starts up. Because we're filtering out the error events we've added an additional replay.hydrate-error breadcrumb to the Replay SDK to record when these errors occur, similar to a click event.

Once we have the hydration error breadcrumb, we can get the initial pageload and compare it with the html state at the time of the replay.hydrate-error event. Comparing these visually and using an html diff it should point people into the right direction of the hydration error's source.

We'd love to hear from you on:

1. How well a solution like this would help you debug hydration errors?
2. Whether you have any other suggestions for how we can improve the experience around fixing hydration errors?

Getting Started

See this changelog for notes on how to get started https://changelog.getsentry.com/announcements/diff-hydration-errors-with-replay

[brettdh]

This would be so lovely to have... in Remix. 😅

[scttcper]

@brettdh there's a good chance it already works with remix if you have a fully updated sdk. See this changelog for how to get started

[brettdh]

Finally got a chance to test this, as I have a real hydration error that I'm struggling with. After upgrading @sentry/remix to latest (7.113.0) and reproducing the error, here's what I get:

Both the HTML and visual diffs look identical. Should I open a bug, or is there a setup step I'm missing?

[scttcper]

there's a few possibilities:

• the replay didn't start early enough to capture the initial html (more common in localhost). Race between when the replay starts recording and when the hydration error happens.
• the hydration error is in the header which isn't currently shown in the diff
• if you have maskAllText enabled, maybe the hydration error was in the text?

you can also open an issue or link here. if you're using cloudflare there's a good chance one of the settings is changing your headers

[brettdh]

Thanks for the quick response. To those possibilities:

• I don't currently have reporting to Sentry enabled on localhost; these errors are reported from Remix running in AWS Lambda + API Gateway. If it's a race condition, though, could I temporarily insert a sleep somewhere to avoid the race? If so, where?
• Hmm, I don't think I was aware that a difference in headers could cause a hydration error, but I also don't think my current changes could have caused a change in the headers. Also, I do see the same hydration error on localhost (though I don't report it to Sentry in that case), which I think eliminates the possibility of AWS header-munging being the cause of the hydration error.
• I have maskAllText set to false.

[scttcper]

We've published a changelog with how to get started debugging hydration errors using session replay https://changelog.getsentry.com/announcements/diff-hydration-errors-with-replay

[brysongilbert]

This has the makings of a super useful feature, thank you! 🙏 One thing we have noticed at a glance is that differences in attribute order are highlighted in the diff. For example:

(Note that this is just a one-line snippet of a much larger diff. And in this case the particular line comes from framework code, not app code.)

I stand to be corrected on this but I don't believe React cares about attribute order, in terms of a hydration mismatch. So you get a little visual noise from these if you're looking at a relatively larger/longer diff.

Wish list item: for only missing/new attributes or differing attribute values, to be highlighted, and for attribute order (where the attribute and value are otherwise identical) to be ignored.

[felixmosh]

For some reason, the "Before hydaration" is always empty...
I'm using Next.js v13

Using the cdn bundle script in the head of the page.

<script src="https://browser.sentry-cdn.com/8.20.0/bundle.replay.min.js" integrity="sha384-3RyGu38xD2r+OrNF2g9Ekem9LqdE766XjQCz0pIzabGm4T52CIDxkyWUq7klKDVd" crossorigin="anonymous" defer=""></script>

Any idea why?

[scttcper]

@felixmosh I haven't investigated using the cdn bundle for this, i imagine the defer property at the very least would impact the ability to load soon enough to capture the "before"

[felixmosh]

This is weird...since the the lib does capture the hydration phase... No?

[ryan953]

Good news everyone, we've moved this feature into GA today! Every Sentry org will be able to install the Replay integration and have Hydration Errors captured automatically. Make sure you're on SDK version 7.87.0 or higher.

https://sentry.io/changelog/debug-hydration-errors-with-our-diff-tool---now-generally-available/