Email Template Development

This skill guides the development of email templates using React Email with Tailwind CSS.

When to use this skill

•Creating new email templates
•Modifying existing email templates
•Testing email rendering in different clients
•Debugging email template styling
•Compiling React Email to production HTML

Quick Commands

bash

make dev-emails    # Start React Email dev server (http://localhost:3001)
make build-emails  # Compile React Email to HTML with Jinja2 variables

Development Workflow

1. Start Development Server

bash

make dev-emails

Opens React Email preview UI at http://localhost:3001:

•Live preview of all templates
•Mobile/desktop view toggle
•Built-in Tailwind CSS support
•Auto-reload on changes

2. Create or Edit Templates

Templates location: backend/emails/templates/

Shared Components:

•_BaseLayout.tsx: Main email layout wrapper with Tailwind support
•_Button.tsx: Styled button component

Example Template:

tsx

import { Button, Html, Text, Tailwind } from '@react-email/components';
import { BaseLayout } from './_BaseLayout';

interface WelcomeEmailProps {
  userName: string;
  loginUrl: string;
}

export const WelcomeEmail = ({ userName, loginUrl }: WelcomeEmailProps) => (
  <BaseLayout previewText="Welcome to Arive!">
    <Text className="text-lg font-semibold text-foreground mb-4">
      Hello {userName}!
    </Text>
    <Text className="text-muted-foreground mb-6">
      Thanks for joining Arive. Get started by logging in:
    </Text>
    <Button href={loginUrl} className="bg-primary text-primary-foreground">
      Log In Now
    </Button>
  </BaseLayout>
);

WelcomeEmail.PreviewProps = {
  userName: "John Doe",
  loginUrl: "https://app.tryarive.com/login",
} as WelcomeEmailProps;

export default WelcomeEmail;

3. Use Tailwind CSS Classes

The email templates support Tailwind CSS, which gets compiled to inline styles:

tsx

<div className="bg-neutral-50 p-4 rounded-lg border border-neutral-200">
  <Text className="text-foreground font-semibold">Important Notice</Text>
  <Text className="text-muted-foreground text-sm">Details here...</Text>
</div>

Available Theme Colors:

•text-foreground / bg-foreground
•text-background / bg-background
•text-primary / bg-primary
•text-muted / bg-muted
•text-muted-foreground
•Full neutral gray scale: neutral-50 through neutral-950

Config: backend/emails/tailwind.config.ts

4. Add Jinja2 Variables

Props in React components become Jinja2 template variables:

React:

tsx

interface MyEmailProps {
  userName: string;
  confirmUrl: string;
}

export const MyEmail = ({ userName, confirmUrl }: MyEmailProps) => (
  <BaseLayout>
    <Text>Hello {userName}</Text>
    <Button href={confirmUrl}>Confirm</Button>
  </BaseLayout>
);

Compiled HTML:

html

<p>Hello {{ userName }}</p>
<a href="{{ confirmUrl }}">Confirm</a>

5. Register Template Variables

Edit backend/emails/scripts/build.ts:

typescript

const TEMPLATE_VARIABLES: Record<string, Record<string, string>> = {
  'WelcomeEmail': {
    userName: 'John Doe',
    loginUrl: 'https://app.tryarive.com/login',
  },
  'MyNewEmail': {
    userName: 'Test User',
    confirmUrl: 'https://app.tryarive.com/confirm/abc123',
  },
};

6. Build Production Templates

bash

make build-emails

This compiles:

•React Email components → HTML
•Tailwind CSS classes → inline styles
•Props → Jinja2 variables
•Output: backend/templates/emails-react/*.html.jinja2

7. Use Template in Backend

Add method to EmailService in backend/app/lib/email.py:

python

async def send_welcome_email(
    self,
    to_email: str,
    user_name: str,
    login_url: str,
) -> None:
    """Send welcome email to new user."""
    await self._send_email(
        template_name="WelcomeEmail.html.jinja2",
        to_email=to_email,
        subject="Welcome to Arive!",
        template_vars={
            "userName": user_name,
            "loginUrl": login_url,
        },
    )

Call from route handler:

python

@post("/register")
async def register_user(
    data: RegisterRequest,
    email_service: EmailService,
) -> UserResponse:
    user = await create_user(data)
    await email_service.send_welcome_email(
        to_email=user.email,
        user_name=user.name,
        login_url=f"https://app.tryarive.com/login",
    )
    return user

Template Structure

code

backend/emails/
├── templates/           # React Email source (.tsx)
│   ├── _BaseLayout.tsx  # Shared layout component
│   ├── _Button.tsx      # Shared button component
│   ├── WelcomeEmail.tsx # Example template
│   └── MyEmail.tsx      # Your new template
├── scripts/
│   ├── build.ts         # Build script (React → HTML)
│   └── watch.ts         # Dev server script
├── tailwind.config.ts   # Tailwind CSS config
└── package.json         # npm dependencies

backend/templates/emails-react/  # Compiled output (generated)
├── WelcomeEmail.html.jinja2
└── MyEmail.html.jinja2

Design System Guidelines

Colors

Use semantic color names that match the frontend:

•Foreground: Main text color (text-foreground)
•Muted: Secondary text (text-muted-foreground)
•Primary: Brand color for CTAs (bg-primary)
•Neutral grays: Backgrounds and borders (bg-neutral-50, border-neutral-200)

Typography

tsx

<Text className="text-2xl font-bold text-foreground">Heading</Text>
<Text className="text-base text-foreground">Body text</Text>
<Text className="text-sm text-muted-foreground">Caption</Text>

Spacing

tsx

<div className="p-6">           {/* Padding */}
<div className="mb-4">          {/* Margin bottom */}
<div className="space-y-4">     {/* Vertical spacing between children */}

Layout

tsx

<Container className="max-w-xl">  {/* Max width container */}
  <Section className="bg-neutral-50 rounded-lg p-6">
    {/* Content */}
  </Section>
</Container>

Testing Email Rendering

1. Preview in Dev Server

•Check desktop and mobile views
•Test all interactive elements
•Verify spacing and alignment

2. Send Test Emails

python

# In backend shell or test script
from app.lib.email import EmailService

email_service = EmailService()
await email_service.send_welcome_email(
    to_email="your-email@example.com",
    user_name="Test User",
    login_url="https://app.tryarive.com/login",
)

3. Email Client Testing

Test in multiple email clients:

•Gmail (web + mobile app)
•Outlook (web + desktop)
•Apple Mail (macOS + iOS)
•Others as needed

Common Issues

Styles not applying

•Tailwind not compiling: Run make build-emails
•Inline styles missing: Check Tailwind config includes all classes
•Email client stripping styles: Use supported CSS properties only

Variables not rendering

•Jinja2 syntax errors: Check template output in backend/templates/emails-react/
•Missing variables: Verify TEMPLATE_VARIABLES in build.ts
•Type mismatches: Ensure props match template variables

Images not loading

•Relative paths: Use absolute URLs for images
•CORS issues: Ensure image hosting allows email embedding
•Size: Optimize images for email (< 100KB recommended)

Best Practices

•Mobile-first: Design for mobile screens, test responsive behavior
•Inline styles: Tailwind automatically inlines, but verify after build
•Alt text: Always include alt text for images
•Preheader text: Set via previewText prop in BaseLayout
•CTA buttons: Make them prominent and tap-friendly (44px min height)
•Dark mode: Consider email client dark mode support
•Accessibility: Use semantic HTML and proper color contrast

Production Deployment

Before deploying:

•Run make build-emails to compile templates
•Commit compiled templates in backend/templates/emails-react/
•Templates are included in Docker image build
•No Node.js runtime needed in production

Backend serves templates via Litestar's JinjaTemplateEngine at runtime.