Clerk causes hydration errors when used with Remix's streaming (defer()).

[tavoyne]

Preliminary Checks

• I have reviewed the documentation: https://clerk.com/docs

• I have searched for existing issues: https://github.com/clerk/javascript/issues

• I have not already reached out to Clerk support via email or Discord (if you have, no need to open an issue here)

• This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.

Reproduction

https://github.com/tavoyne/clerk-error

Publishable key

pk_test_Y2xvc2luZy1lbGstOTcuY2xlcmsuYWNjb3VudHMuZGV2JA

Description

If you try to load the home page, you'll see the following error in the console:

Error: This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering. The usual way to fix this is to wrap the original update in startTransition.
    at updateDehydratedSuspenseComponent (chunk-3IHV7RO6.js?v=cfe72da2:15345:56)
    at updateSuspenseComponent (chunk-3IHV7RO6.js?v=cfe72da2:15118:24)
    at beginWork (chunk-3IHV7RO6.js?v=cfe72da2:15939:22)
    at beginWork$1 (chunk-3IHV7RO6.js?v=cfe72da2:19753:22)
    at performUnitOfWork (chunk-3IHV7RO6.js?v=cfe72da2:19198:20)
    at workLoopSync (chunk-3IHV7RO6.js?v=cfe72da2:19137:13)
    at renderRootSync (chunk-3IHV7RO6.js?v=cfe72da2:19116:15)
    at performConcurrentWorkOnRoot (chunk-3IHV7RO6.js?v=cfe72da2:18678:83)
    at workLoop (chunk-3IHV7RO6.js?v=cfe72da2:197:42)
    at flushWork (chunk-3IHV7RO6.js?v=cfe72da2:176:22)

This hydration error causes the entire component tree to be re-rendered.

When you remove the ClerkApp() HOC in root.tsx, the document is properly hydrated and the error disappears.

This also happens in production.

Environment

System:
  OS: macOS 14.1
  CPU: (16) x64 Intel(R) Core(TM) i9-9880H CPU @ 2.30GHz
  Memory: 2.25 GB / 32.00 GB
  Shell: 5.9 - /bin/zsh
Binaries:
  Node: 20.9.0 - ~/.nvm/versions/node/v20.9.0/bin/node
  npm: 10.1.0 - ~/.nvm/versions/node/v20.9.0/bin/npm
Browsers:
  Chrome: 127.0.6533.89
  Chrome Canary: 129.0.6640.0
  Safari: 17.1

[anagstef]

Hello @tavoyne! Thank you for opening this issue.

I can see that relevant hydration issues in Remix are resolved with a Canary version of React. 🤔
Can you please try installing React 19 RC and see if the issue persists?

npm i react@rc react-dom@rc

If you can't use React 19 due to dependency restrictions, try the following:

"dependencies": {
  "react": "18.3.0-canary-a870b2d54-20240314",
  "react-dom": "18.3.0-canary-a870b2d54-20240314",
},
"overrides": {
  "react": "18.3.0-canary-a870b2d54-20240314",
  "react-dom": "18.3.0-canary-a870b2d54-20240314"
},

I tried with your provided repository and it seems that the error goes away, but maybe you could try in your main project and see if it resolves the issues.

references:

• hydration error when there is a chrome extension that modifies DOM remix-run/remix#4822
• https://x.com/kiliman/status/1769730243772780825

[tavoyne]

Hey @anagstef,

React 19 doesn’t "fix" the issue; it just has a different way of dealing with hydration errors.

There’s still a hydration error underneath, and that is the problem. This can be observed with a spinner as the error resets it.