Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings
Discussion options

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

  1. Intended Support: Is @react-email/render intended to work in server-only environments like Convex?

  2. Required Polyfills: What's the complete list of browser APIs that need to be polyfilled for server-side usage?

  3. Alternative Approaches: Is there a recommended server-only rendering method that doesn't rely on browser APIs?

  4. Environment Detection: Would the library benefit from detecting the runtime environment and using appropriate rendering strategies?

Suggested Solutions

  1. Built-in Environment Detection: Automatically detect server vs browser and use appropriate rendering methods
  2. Server-only Export: Provide a separate import like @react-email/render/server that doesn't use browser APIs
  3. Comprehensive Polyfill Guide: Document all required polyfills for different server environments
  4. Alternative Render Method: Provide a renderToString method that uses Node.js-compatible APIs

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!
You must be logged in to vote

Replies: 0 comments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Category
🙏
Q&A
Labels
None yet
1 participant
@chandrabhan-singh-1
Morty Proxy This is a proxified and sanitized view of the page, visit original site.