Getting TypeErrors and unable to access components built with @react-email/components as ReactNode #2407

chandrabhan-singh-1 · 2025-08-03T12:18:45Z

chandrabhan-singh-1
Aug 3, 2025

MessageChannel Error in Convex Server Environment - React Email Components Not Rendering

Environment

Framework: Next.js v15.2.3
Backend: Convex v1.25.4
Authentication: BetterAuth v1.3.4
React Email: @react-email/render v1.1.4, @react-email/components v0.4.0
Runtime: Convex server environment (Node.js-like)
Use Case: Authentication emails (password reset, email verification)

Problem Summary

React Email components fail to render in Convex server environment with MessageChannel is not defined error. Components appear to not be recognized as proper ReactNodes, requiring workarounds that still don't resolve the underlying issue.

Expected Behavior

Based on documentation, this should work:

import { render } from '@react-email/render';
import { MyEmailTemplate } from './email-template';

// This should work
const html = await render(<MyEmailTemplate name="John" url="https://example.com" />);

Actual Behavior

Issue 1: JSX Syntax Not Recognized

Components cannot be passed as JSX to the render function. TypeScript throws errors:

'>' expected
'MyEmailTemplate' refers to a value, but is being used as a type here

Issue 2: Function Call Workaround Fails

When calling components as functions instead of JSX:

// Workaround attempt
const html = await render(MyEmailTemplate({ name: "John", url: "https://example.com" }));

This results in:
Uncaught ReferenceError: MessageChannel is not defined

Minimal Reproduction

Email Component (`components/email/verification-email.tsx`)

import * as React from "react";
import { Html, Body, Container, Heading, Text, Button, Link } from "@react-email/components";

interface VerificationEmailProps {
  name: string;
  url: string;
}

export const VerificationEmail = ({ name, url }: VerificationEmailProps) => {
  return (
    <Html>
      <Body>
        <Container>
          <Heading>Verify your email</Heading>
          <Text>Hello {name},</Text>
          <Text>Click the button below to verify your email:</Text>
          <Link href={url}>
            <Button>Verify Email</Button>
          </Link>
        </Container>
      </Body>
    </Html>
  );
};

Server-side Usage (Convex environment)

import { render } from "@react-email/render";
import { VerificationEmail } from "../components/email/verification-email";

// This fails with MessageChannel error
const emailHtml = await render(VerificationEmail({ name: "John", url: "https://example.com" }));

Error Details

Uncaught ReferenceError: MessageChannel is not defined
at [internal Convex runtime]

Investigation & Attempted Solutions

1. Polyfill Attempts

import "web-streams-polyfill/polyfill";  // Partial help
// Still need MessageChannel polyfill

2. React.createElement Approach

import React from "react";
const emailHtml = await render(React.createElement(VerificationEmail, { name, url }));
// Still throws MessageChannel error

Root Cause Analysis

The issue appears to be that @react-email/render uses browser-specific APIs (MessageChannel, potentially others) that are not available in Convex's server runtime environment. This is similar to issues that might occur in:

Vercel Edge Runtime
Cloudflare Workers
Other restricted server environments

Repository for Reproduction

Live reproduction: https://github.com/chandrabhan-singh-1/reminderrr.git

Example `.env.local` file

CONVEX_DEPLOYMENT=

NEXT_PUBLIC_CONVEX_URL=
NEXT_PUBLIC_APP_URL=
NEXT_PUBLIC_CONVEX_SITE_URL=

BETTER_AUTH_SECRET=

RESEND_API_KEY=""

The repo contains a complete setup with:

Convex backend configuration
BetterAuth integration
React Email components that demonstrate the issue
Email sending logic that fails

Impact

This blocks email functionality for user authentication in production applications using Convex as a backend. Currently have no working solution for sending styled emails.

Questions for Maintainers

Intended Support: Is @react-email/render intended to work in server-only environments like Convex?
Required Polyfills: What's the complete list of browser APIs that need to be polyfilled for server-side usage?
Alternative Approaches: Is there a recommended server-only rendering method that doesn't rely on browser APIs?
Environment Detection: Would the library benefit from detecting the runtime environment and using appropriate rendering strategies?

Workaround Request

If there's any temporary workaround or configuration that would allow React Email to work in Convex, that would be incredibly helpful while a proper solution is developed.

Thank you for your time and for maintaining this excellent library!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Getting TypeErrors and unable to access components built with @react-email/components as ReactNode #2407

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Getting TypeErrors and unable to access components built with @react-email/components as ReactNode #2407

Uh oh!

chandrabhan-singh-1 Aug 3, 2025

MessageChannel Error in Convex Server Environment - React Email Components Not Rendering

Environment

Problem Summary

Expected Behavior

Actual Behavior

Issue 1: JSX Syntax Not Recognized

Issue 2: Function Call Workaround Fails

Minimal Reproduction

Email Component (components/email/verification-email.tsx)

Server-side Usage (Convex environment)

Error Details

Investigation & Attempted Solutions

1. Polyfill Attempts

2. React.createElement Approach

Root Cause Analysis

Repository for Reproduction

Example .env.local file

Impact

Questions for Maintainers

Suggested Solutions

Workaround Request

Replies: 0 comments

chandrabhan-singh-1
Aug 3, 2025

Email Component (`components/email/verification-email.tsx`)

Example `.env.local` file