fix(react-email): inherit lang and dir on <Body> from <Html> without React context

Draft
GA
4mo ago
+1043-16

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 their children at 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 EmailContextInjector element 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 eager mapReactTree), 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 inner td), instead of lang="en"
  • Explicit lang/dir on <Body> still win
  • Standalone <Body> keeps the en/ltr defaults

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 the Body inheritance 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 — where React.createContext doesn't exist — and asserts the body/td host elements carry lang="pl" in the flight payload.
  • Full react-email suite: 45 files / 314 tests passing, plus typecheck, lint and build; verified the issue's exact repro against the built dist.

Slack Thread

Open in Web Open in Cursor 

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.4 for a Flight-based RSC compatibility test.