React Email Bundler

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/react-email.ts
• src/lib/react-email-bundler.ts
• src/lib/esbuild/rendering-utilities-exporter.ts
• src/commands/emails/send.ts
• src/commands/broadcasts/create.ts
• src/commands/templates/create.ts
• src/commands/templates/update.ts
• tests/lib/react-email-bundler.test.ts

The React Email Bundler transforms React components (.tsx files) into static HTML strings for email delivery. It integrates esbuild to compile modern React syntax into a format compatible with Node.js rendering utilities. This system allows you to use standard React patterns to design emails while ensuring the final output is a raw HTML payload suitable for the Resend API.

Architecture and Core Pipeline

The bundling pipeline follows a multi-stage process: path validation, compilation, rendering, and cleanup. The module src/lib/react-email.ts orchestrates these stages using a spinner to provide visual feedback in the terminal.

Main Orchestration

The buildReactEmailHtml function serves as the entry point. It resolves the template path and verifies that the target exists as a file. If validation fails, it returns an error with the code react_email_build_error.

Sources: [src/lib/react-email.ts:14-41](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/lib/react-email.ts#L14-L41)

Bundling Logic

The bundler uses esbuild to package the React component. It creates a temporary directory in the operating system's temporary folder with a resend-react-email- prefix. The compiler targets the node platform and outputs a cjs (CommonJS) file named after the input template.

Key configuration for the bundler:

• Format: CommonJS (cjs).
• JSX: Automatic mode.
• Platform: Node.js.
• Entry Points: The user-provided .tsx path.

Sources: [src/lib/react-email-bundler.ts:12-32](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/lib/react-email-bundler.ts#L12-L32), [tests/lib/react-email-bundler.test.ts:54-61](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/tests/lib/react-email-bundler.test.ts#L54-L61)

Custom esbuild Plugins

The bundler utilizes a specific plugin, renderingUtilitiesExporter, to ensure the resulting bundle contains the necessary exports for rendering.

Rendering Utilities Exporter

This plugin intercepts the loading of the email template file and appends specific exports. It exports the render function from supported React Email modules and the createElement function from React. It attempts to resolve the render function from the following packages in order:

1. react-email (version 6.0+)
2. @react-email/components (version 5.x)
3. @react-email/render

If the plugin cannot find these packages, it throws an error instructing you to install one of them in your project.

Sources: [src/lib/esbuild/rendering-utilities-exporter.ts:7-58](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/lib/esbuild/rendering-utilities-exporter.ts#L7-L58)

CLI Integration

Several command groups utilize the React Email Bundler via the --react-email flag. This flag is consistently defined as mutually exclusive with direct HTML inputs to prevent payload conflicts.

Supported Commands

Command Group	Flag	Purpose
emails send	--react-email <path>	Bundle and send a template immediately.
broadcasts create	--react-email <path>	Bundle a template for a bulk broadcast.
templates create	--react-email <path>	Bundle and save a template to the Resend dashboard.
templates update	--react-email <path>	Replace an existing template's HTML with a bundled version.

Sources: [src/commands/emails/send.ts:69-72](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/commands/emails/send.ts#L69-L72), [src/commands/broadcasts/create.ts:28-31](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/commands/broadcasts/create.ts#L28-L31), [src/commands/templates/create.ts:28-31](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/commands/templates/create.ts#L28-L31)

Mutual Exclusivity Rules

The CLI enforces strict validation rules when using the bundler:

• You cannot use --react-email simultaneously with --html or --html-file.
• You cannot use --react-email with --template in the send command.
• In the emails send command, you can still provide a --text flag as a plain-text fallback alongside --react-email.

Sources: [src/commands/emails/send.ts:139-148](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/commands/emails/send.ts#L139-L148), [src/commands/templates/create.ts:85-92](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/commands/templates/create.ts#L85-L92)

Error Handling

The system defines specific error codes to identify where the bundling or rendering process failed.

Error Code	Meaning
react_email_build_error	Occurs during file validation or the esbuild compilation phase.
react_email_render_error	Occurs when the compiled CJS bundle fails to execute or render to HTML.
file_read_error	Occurs if the bundler cannot read the source .tsx file or associated assets.

Sources: [src/lib/react-email.ts:60-84](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/lib/react-email.ts#L60-L84), [src/commands/emails/send.ts:109-110](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/commands/emails/send.ts#L109-L110)

Implementation Example: Bundling Process

// From src/lib/react-email-bundler.ts
export async function bundleReactEmail(
  templatePath: string,
): Promise<BundleResult> {
  const resolved = path.resolve(templatePath);
  const tmpDir = mkdtempSync(path.join(tmpdir(), 'resend-react-email-'));

  try {
    const { build } = loadEsbuild();
    await build({
      bundle: true,
      entryPoints: [resolved],
      format: 'cjs',
      jsx: 'automatic',
      outExtension: { '.js': '.cjs' },
      outdir: tmpDir,
      platform: 'node',
      plugins: [renderingUtilitiesExporter([resolved])],
      write: true,
    });
  } catch (err) {
    rmSync(tmpDir, { recursive: true, force: true });
    throw err;
  }
  // ... returns paths
}

Sources: [src/lib/react-email-bundler.ts:12-32](https://github.com/resend/resend-cli/blob/eb1830c4279fbcac0df286f40ca90f1676e8f7dd/src/lib/react-email-bundler.ts#L12-L32)

Conclusion

The React Email Bundler provides a bridge between developer-friendly React components and the standard HTML requirements of email clients. By utilizing esbuild and temporary directory management, it ensures that template compilation is fast, isolated, and automatically cleaned up after the email is sent or the template is created.