HTML Rendering Engine

Relevant source files

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

• packages/render/src/node/render.tsx
• skills/react-email/SKILL.md
• packages/render/src/node/render-node.spec.tsx
• packages/render/src/edge/render.spec.tsx
• packages/render/src/browser/render-web.spec.tsx
• packages/render/package.json

The HTML Rendering Engine transforms React components into email-ready HTML or plain text strings. It provides a unified API that adapts its rendering strategy based on the execution environment, including Node.js, Edge functions, and the browser. This engine manages the complexities of asynchronous rendering, Suspense boundaries, and email-specific post-processing to ensure compatibility across various email clients.

Sources: packages/render/src/node/render.tsx:1-12, skills/react-email/SKILL.md:195-207

Core Rendering Architecture

The engine centers around a polymorphic render function that dynamically imports react-dom/server components at runtime. It utilizes React 18+ streaming APIs to handle asynchronous components and large email templates without triggering hydration markers or premature resolution.

Execution Environment Detection

The engine checks for the availability of renderToReadableStream and the WritableStream global to determine if it should use a Web Stream-based approach or a Node.js-based PipeableStream.

The engine sets progressiveChunkSize to Number.POSITIVE_INFINITY to ensure the entire email renders in a single pass, preventing partial content delivery common in standard web streaming.
Sources: packages/render/src/node/render.tsx:16-59, packages/render/src/node/render-node.spec.tsx:167-185

Rendering Process Lifecycle

The rendering lifecycle involves component execution, error handling through boundaries, and specific cleanup operations.

1. Wrapper Injection: The engine wraps the input node in a Suspense component and a custom ErrorBoundary.
2. Streaming Resolution: It initiates a stream and waits for all content (including asynchronous Suspense data) to settle.
3. Multibyte Character Handling: The engine handles characters with higher byte counts (e.g., Japanese characters) gracefully to prevent corruption during stream reading.
4. Null Character Cleanup: For environments using React 18's renderToPipeableStream, the engine replaces \0 null characters to work around specific React bugs.
5. Preload Link Removal: The engine strips image preload links (<link rel="preload">) which are generally unsupported and unnecessary in email clients.

Sources: packages/render/src/node/render.tsx:24-74, packages/render/src/node/render-node.spec.tsx:43-65, packages/render/src/browser/render-web.spec.tsx:109-126

Configuration and Options

The render function accepts an Options object to modify the output behavior and format.

Option	Type	Description
plainText	boolean	If true, converts the generated HTML into a plain text string.
pretty	boolean	If true, applies formatting to the HTML output using Prettier.
unstableTextConversion	boolean	Uses an experimental text conversion logic when plainText is true.
htmlToTextOptions	object	Configuration passed to the underlying html-to-text converter.

Sources: packages/render/src/node/render.tsx:12-88, packages/render/package.json:107-111

Plain Text Conversion

When requested, the engine transforms the rendered HTML into accessible plain text. This process involves stripping HTML tags while maintaining a readable structure for email clients that do not support HTML or for users with accessibility needs.

Document Structure Implementation

For HTML output, the engine ensures the presence of a proper XHTML 1.0 Transitional DOCTYPE. If the React component does not provide its own DOCTYPE, the engine injects a default one to ensure consistent rendering in legacy email clients like Outlook.

const doctype =
  '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">';

const document = `${doctype}${html.replace(/<!DOCTYPE.*?>/, '')}`;

Sources: packages/render/src/node/render.tsx:83-86, packages/render/src/browser/render-web.spec.tsx:39-44

Summary

The HTML Rendering Engine provides a robust, environment-aware bridge between React components and email client requirements. By leveraging React's streaming APIs and implementing custom logic for environment detection and post-rendering cleanup, it delivers reliable HTML and plain text outputs for transactional and marketing emails.