Contributing & Workflow

Relevant source files

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

• README.md
• CONTRIBUTING.md
• skills/react-email/SKILL.md
• skills/react-email/TESTS.md
• packages/editor/package.json
• packages/ui/CHANGELOG.md

React Email provides a standardized workflow for building, testing, and contributing to high-quality email components. The process ensures cross-client compatibility and maintains a modern developer experience using React and TypeScript.

Contributors follow a structured path from environment setup to pull request submission. This guide outlines the technical requirements for local development and the behavioral guidelines for code updates.
Sources: README.md:92-98, CONTRIBUTING.md:1-6

Development Lifecycle

The development lifecycle follows a Test-Driven Development (TDD) approach to ensure that new features or bug fixes do not break existing email client compatibility.

The diagram shows the sequential steps required to move a feature from local setup to a community contribution.
Sources: CONTRIBUTING.md:16-22, skills/react-email/TESTS.md:3-5

Environment Setup

You initialize a project by either installing the core package or scaffolding a new starter project.

1. Install the latest package: npm i react-email@latest.
2. Scaffold a starter: npx create-email@latest.
3. Configure tsconfig.json to support JSX.
   Sources: README.md:44-46, skills/react-email/SKILL.md:43-52

Local Development Server

The development server provides a live preview interface for templates located in the emails folder.

• Run the server: email dev --dir emails --port 3000.
• The server performs hot reloading when you save changes.
• It detects compatibility issues for clients like Gmail, Outlook, and Apple Mail.
• You can narrow client warnings using the --clients flag (e.g., email dev --clients outlook).
  Sources: skills/react-email/SKILL.md:54-61, packages/ui/CHANGELOG.md:37-45

CLI Commands Reference

The react-email CLI facilitates common development tasks.

Command	Action
email dev	Starts the preview development server.
email build	Builds the preview application for production.
email start	Runs a built preview application.
email export	Converts templates to static HTML and plain text.
email resend setup	Connects the CLI to a Resend account via API key.
Sources: skills/react-email/SKILL.md:308-316, packages/ui/CHANGELOG.md:120-125

Testing and Verification

React Email utilizes Vitest for unit testing and a manual verification process for behavioral guidelines.

Automated Testing

The @react-email/editor package includes specialized test scripts for different environments.

{
  "scripts": {
    "test": "vitest run",
    "test:unit": "vitest run --project unit",
    "test:browser": "vitest run --project browser"
  }
}

Sources: packages/editor/package.json:96-101

Behavioral Compliance

When you update code, you must adhere to specific structural rules to ensure email client compatibility.

The sequence shows how the development server validates code against email client restrictions during the edit cycle.
Sources: skills/react-email/SKILL.md:143-155, packages/ui/CHANGELOG.md:37-45

Verification Checklist:

• Do not use rem units; always use the pixelBasedPreset with Tailwind.
• Avoid CSS Grid or Flexbox; use Row and Column components instead.
• Do not use SVG or WEBP images; use PNG or JPG only.
• Place {{variable}} patterns only in PreviewProps, never directly in JSX.
• Always include the box-border class on Button components.
  Sources: skills/react-email/SKILL.md:85-110, skills/react-email/SKILL.md:158-165

Build and Export Workflow

The build process optimizes the preview application, while the export command prepares templates for production delivery.

Building for Production

The email build command integrates with Turbo to optimize build times. You must resolve all linting errors before building.
Sources: CONTRIBUTING.md:21, packages/ui/CHANGELOG.md:214

Exporting Templates

The export workflow serializes React components into standard HTML.

1. Run email export --outDir ./dist.
2. The CLI generates both .html and .txt versions of every template.
3. Use the --pretty flag for formatted output or --plainText for text only.
   Sources: skills/react-email/SKILL.md:313, packages/ui/CHANGELOG.md:364-370

Reporting and Pull Requests

The project follows standard open-source contribution procedures for bugs and features.

• Bugs: Review the opening issues guide before reporting.
• Pull Requests: Follow the process for Request for Comments (RFCs) and PR submission.
• Codebase Overview: Read the Codebase overview guide for architectural details.
  Sources: CONTRIBUTING.md:8-14

This workflow ensures that every contribution maintains the standard of producing "next generation" email templates that work across Gmail, Outlook, and other archaic email clients.
Sources: README.md:26-30