Quickstart Setup

Relevant source files

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

• README.md
• skills/react-email/SKILL.md
• packages/react-email/readme.md
• skills/react-email/references/COMPONENTS.md
• skills/react-email/references/STYLING.md
• CONTRIBUTING.md

React Email provides high-quality, unstyled components for creating emails using React and TypeScript. The system handles dark mode support and inconsistencies between major email clients like Gmail and Outlook.

You can initialize a project by scaffolding a new directory or by integrating the library into an existing codebase. The development workflow centers on a local preview server that offers real-time feedback for template changes.

Sources: README.md:14-17, skills/react-email/SKILL.md:20-22

Initializing the Project

You have two primary methods to start building with React Email: automatic scaffolding or manual installation.

Automatic Scaffolding

Use the create-email command to generate a pre-configured starter project. This creates an emails directory containing example templates and necessary configurations.

npx create-email@latest
cd react-email-starter
npm install
npm run dev

Sources: skills/react-email/SKILL.md:27-31, packages/react-email/readme.md:12-14

Manual Integration

If you have an existing project, install the package directly and configure a custom execution script.

1. Install the core package: npm i react-email@latest.
2. Add a development script to your package.json:

   {
     "scripts": {
       "email": "email dev --dir emails --port 3000"
     }
   }
   

3. Ensure your tsconfig.json supports JSX rendering for email components.

Sources: README.md:38, skills/react-email/SKILL.md:37-45

Development Environment Architecture

The environment relies on a CLI-driven development server. The email dev command triggers a watch process that rebuilds templates using esbuild.

The diagram shows the iterative loop where file changes trigger a rebuild and update the local preview interface.
Sources: packages/react-email/readme.md:20-25, skills/react-email/SKILL.md:33

CLI Command Reference

The email command manages the development lifecycle and asset exporting.

Command	Action	Key Options
dev	Starts the preview development server	--dir, --port, --esbuild-plugins
build	Builds the preview app for production	--dir
export	Generates static HTML and plain text files	--outDir, --pretty, --plainText
start	Runs the built preview application	-

Sources: skills/react-email/SKILL.md:198-207, packages/react-email/readme.md:20-35

Template Structure and Styling

Templates follow a specific component hierarchy to ensure compatibility across email clients. You should use the Tailwind component for styling and the pixelBasedPreset to avoid unsupported rem units.

The diagram represents the standard nesting order for a React Email template.
Sources: skills/react-email/references/COMPONENTS.md:73-86, skills/react-email/SKILL.md:52-87

Essential Component Hierarchy

1. <Html>: The root wrapper defining language and text direction.
2. <Tailwind>: Wraps content to enable utility classes. Define the <Head> inside this component.
3. <Body>: The main visible area.
4. <Preview>: The inbox summary text; it must be the first child of <Body>.
5. <Container>: A centering layout component with a default max-width of 37.5em. Use this once per email.

Sources: skills/react-email/SKILL.md:104-118, skills/react-email/references/COMPONENTS.md:88-112

Styling Rules

To prevent rendering failures, follow these styling constraints:

• Units: Always use pixelBasedPreset in your Tailwind config.
• Layout: Avoid Flexbox or CSS Grid. Use <Row> and <Column> components.
• Borders: Always specify a border type (e.g., border-solid) as they are not inherited.
• Buttons: Always apply the box-border class to <Button> components to prevent padding overflow.

Sources: skills/react-email/references/STYLING.md:14-25, skills/react-email/SKILL.md:139-152

Static Asset Management

Local images must reside in a static folder within your emails directory. For production, you must use absolute URLs pointing to a CDN.

const baseURL = process.env.NODE_ENV === "production"
  ? "https://cdn.example.com"
  : "";

// Usage
<Img src={`${baseURL}/static/logo.png`} alt="Logo" />

Sources: skills/react-email/SKILL.md:175-190, skills/react-email/references/STYLING.md:99-105

Summary

Setting up React Email involves initializing a development environment via the CLI and constructing templates using specialized React components. The development server provides a live preview at localhost:3000, while the email export command facilitates the generation of final HTML assets for production delivery. Adhering to the specific component hierarchy and styling constraints ensures consistent rendering across diverse email clients.

Sources: README.md:1-25, skills/react-email/SKILL.md:1-25