Skip to content

fix: hydration errors due to MUI changes#414

Draft
oiramS wants to merge 1 commit intomainfrom
fixMuiHydrationError
Draft

fix: hydration errors due to MUI changes#414
oiramS wants to merge 1 commit intomainfrom
fixMuiHydrationError

Conversation

@oiramS
Copy link
Copy Markdown
Contributor

@oiramS oiramS commented Mar 19, 2026

[PR] <title>

Description

Implement a custom document-hydration workaround: the server renders a stable , the browser hydrates only #root, and the head is re-owned after mount via a portal. React documents both that hydrated output must match the server HTML and that hydrateRoot can target a specific root node, while Remix documents app/entry.server.tsx and app/entry.client.tsx as the supported hooks for customizing server HTML and browser hydration. (react.dev (https://react.dev/reference/react-dom/client/hydrateRoot))

  • The warnings encountered (charSet mismatch, then missing in ) are hydration mismatches. React is explicit that the initial client render must match the server render, and that mismatches should be treated
    hydrateRoot))
  • Remix normally expects app/root.tsx to own document-level components like Meta and Links, but it also gives full control over the HTML response in entry.server and the hydration process in entry.client. The fix uses those official extension points to render a static server head first, then hydrate only the body app. That part is a custom workaround built on official APIs, not a stock Remix recipe. (v2.remix.run (https://
    v2.remix.run/docs/file-conventions/root/))
  • HydratedHead() uses React’s documented client-only pattern: useEffect runs only on the client, and createPortal can render part of the React tree into another DOM node. That makes document.head client-owned after hydration without asking React to reconcile the whole document head during hydration. (react.dev(https://react.dev/reference/react/useEffect))
  • The MUI changes are there to keep Emotion setup consistent. Material UI’s SSR guide says to create a fresh Emotion cache per request and share the same cache configuration between server and client. Final code keeps that concern centralized in createEmotionCache() and lets the server pass a cache explicitly through MuiProvider. (mui.com (https://mui.com/material-ui/guides/server-rendering/))

Fixes # (issue number)

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

  • Test A
  • Test B

Checklist:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings/errors
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes

@oracle-contributor-agreement oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Mar 19, 2026
@oiramS oiramS marked this pull request as draft March 19, 2026 00:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

OCA Verified All contributors have signed the Oracle Contributor Agreement. templates-ords-remix

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant