Dynamic image generation for React Email

[dielduarte]

Goals

Explore APIs dynamic image generation for React Email

Background

The idea

A first-class way to render dynamic visuals in React Email as images. If we
can render JSX/HTML+CSS to an image, one primitive covers barcodes, QR codes,
charts, and more. Likely path: satori for
HTML/CSS → SVG, then SVG → PNG (SVG has poor email-client support).

The hard part: the API

Rendering is the easy part. The real challenge is how the user gets the image:

• Where is it hosted? (export to a CDN and reference by URL?)
• How does it work in React Server Components vs. plain Node? Supporting both
  cleanly is the crux.
• What's the ergonomic surface — component, render helper, build step?

Questions

1. Is image-based generation the right direction (vs. HTML components like feat: add barcode component for email-safe HTML table barcodes #2960)?
2. What should the API — especially the hosting/URL story — look like?
3. Scope: barcodes/QR/charts first, or a general "render-to-image" primitive?

We'll likely close #2960 in favor of settling this first.

Proposal

We don't have a proposal yet, we will use this discussion to explore.

[hducati]

I will share my thoughts here and I hope it helps with something :)

HTML-based visuals still have the advantage that they don't require external hosting and remain visible when email clients block images. They can be reasonable for simple linear barcodes. However, they do not generalize well to QR codes, charts, typography, or more complex visuals. Even though an image-based API has infra costs (it's also more complex), it provides a reusable primitive and more predictable rendering across email clients.

Rough sketch:

@react-email/image package broken into three layers:

1. A low-level renderImage() primitive that converts JSX/HTML+CSS → SVG with Satori and then SVG -> PNG. It would only render the image, with no uploads or hosting assumptions.

import { renderImage } from '@react-email/image/node';

const image = await renderImage(<RevenueChart data={data} />, {
  width: 600,
  height: 240,
  fonts: [inter],
});

It could return the image bytes alongside the information required to publish and render it - something like this:

interface RenderedImage {
  data: Uint8Array;
  contentType: 'image/png';
  width: number;
  height: number;
  digest: string;
}

2. Hosting would be handled through a user-provided publisher interface:

interface ImagePublisher {
  publish(image: RenderedImage): Promise<{
    url: string;
  }>;
}

Users could implement it with S3, Vercel Blob, their own CDN, etc. Resend could also ship an official resendPublisher as a convenience, though it wouldn't be required.

const image = await renderImage(<RevenueChart data={data} />, {
  width: 600,
  height: 240,
});

const { url } = await publisher.publish(image);

The publisher would be responsible for returning a URL. It should also be idempotent by digest: if the same image has already been published, it should return the existing URL instead of uploading it again.

This is especially important for batch sending, where the same email could be rendered for thousands of recipients.

The URL can then be used with the existing React Email Img component:

<Img
  src={url}
  width="600"
  height="240"
  alt="A cool image!"
/>

3. For server-side usage, maybe a component that composes: rendering, publishing and Img

import { DynamicImage } from '@react-email/image/server';

export async function Email() {
  return (
    <DynamicImage
      publisher={s3Publisher}
      width={600}
      height={240}
      alt="Revenue increased from $18k to $31k"
    >
      <RevenueChart data={data} />
    </DynamicImage>
  );
}

Its implementation would be roughly like this:

async function DynamicImage({
  children,
  publisher,
  alt,
  width,
  height,
}) {
  const image = await renderImage(children, {
    width,
    height,
  });

  const { url } = await publisher.publish(image);

  return (
    <Img
      src={url}
      width={width}
      height={height}
      alt={alt}
    />
  );
}

DynamicImage would not need to depend on RSC specifically. It could be an async server-only component supported by the existing React Email async rendering pipeline.

This means the same component could work when rendering an email from plain Node or from within an RSC application, without depending on Next.js or RSC-specific APIs.

The package boundaries could make the runtime requirements explicit:

@react-email/image        // Shared types
@react-email/image/node   // Satori + PNG rasterization
@react-email/image/server // Rendering + publishing + DynamicImage