fix(react-email): inherit lang and dir on <Body> from <Html> without React context
Email contexts: mimicking React context without React context
Fixes #3652.
<Body> hardcoded lang="en" dir="ltr", which conflicts with <Html lang="pl"> in non-English emails. Inheriting them from <Html> requires context-like propagation, but React context can't be used: email templates may be rendered inside RSC (no createContext, no hooks), with react-dom/server, or in the browser.
The mechanism
This PR adds an internal "email context" primitive (src/components/email-context/) that carries values through the element tree itself instead of through the renderer:
createEmailContext(name, defaultValue)creates a context keyed by a global symbol (Symbol.for), so duplicated CJS/ESM copies of the module interoperate.- Providers (
markAsEmailContextProvider+provideEmailContext) walk theirchildrenat render time and clone every marked consumer element with the values injected into a private prop (__reactEmailContexts). - Consumers (
markAsEmailContextConsumer+readEmailContext) read the value from their props with a plain function — no hooks — and strip the private prop before spreading into host elements. - Component boundaries are crossed lazily: unknown function/forwardRef/memo components found during propagation are replaced with an
EmailContextInjectorelement that, when React renders it, calls the original component in place and continues propagating through its output. Because this happens inside an actual React render (unlike Tailwind's eagermapReactTree), hooks inside user components keep working — they're just attributed to the injector. Async components (RSC) are handled by chaining the propagation onto the returned thenable. - Nested providers shadow outer ones: outer propagation stops at a nested provider element and hands its values over through the same private prop, and the inner provider merges its own value on top.
Known caveats (documented on propagateEmailContexts): only the children prop is traversed (e.g. not Suspense's fallback), and consumers hidden inside class components, React.lazy, render-prop functions or client references fall back to their defaults — the same places where the propagation simply degrades to today's behavior rather than breaking.
The fix
<Html> provides { lang, dir } through an email context and <Body> consumes it:
<Html lang="pl">→<body dir="ltr" lang="pl">(and the innertd), instead oflang="en"- Explicit
lang/diron<Body>still win - Standalone
<Body>keeps theen/ltrdefaults
Works with <Tailwind> between (or around) Html and Body, through custom layout components, and through async components.
Testing
- Unit specs for the mechanism (direct/structural nesting, custom components with hooks, forwardRef/memo, async components, nested providers, client rendering via
createRoot, no prop leakage, class-component caveats) and for theBodyinheritance scenarios — all rendered through@react-email/render(Fizz). - An RSC compatibility spec that renders
<Html lang="pl">→ async layout →<Body>with the real Flight renderer (react-server-dom-webpack, added as a dev dependency) in a subprocess under--conditions=react-server— whereReact.createContextdoesn't exist — and asserts the body/td host elements carrylang="pl"in the flight payload. - Full
react-emailsuite: 45 files / 314 tests passing, plus typecheck, lint and build; verified the issue's exact repro against the builtdist.


Summary by cubic
Make inherit lang and dir from without React context, fixing mismatched language metadata in non‑English emails. Works across RSC, server, and client renders.
-
Bug Fixes
- now inherits lang/dir from ; explicit props still override; standalone keeps en/ltr defaults.
- Works through custom layouts, async components, and with ; no private props leak into the DOM.
- Added a small internal “email context” to propagate values without hooks or React context; updated docs to note inheritance.
-
Dependencies
- Added dev dependency
react-server-dom-webpack@19.2.4for a Flight-based RSC compatibility test.
- Added dev dependency