React Email Skills

介绍

# React Email

使用 React 组件构建和发送 HTML 邮件——这是一种现代化的、基于组件的邮件开发方法，适用于所有主流邮件客户端。

## 安装

你需要使用 create-email CLI 脚手架搭建一个新的 React Email 项目。这将创建一个名为 `react-email-starter` 的文件夹，其中包含示例邮件模板。

使用 npm: ```sh npx create-email@latest ```

使用 yarn: ```sh yarn create email ```

使用 pnpm: ```sh pnpm create email ```

使用 bun: ```sh bun create email ```

## 导航到项目目录

你必须进入新创建的项目文件夹：

```sh cd react-email-starter ```

## 安装依赖

在运行开发服务器之前，你需要安装所有项目依赖。

使用 npm: ```sh npm install ```

使用 yarn: ```sh yarn ```

使用 pnpm: ```sh pnpm install ```

使用 bun: ```sh bun install ```

## 启动开发服务器

你的任务是启动本地预览服务器以查看和编辑邮件模板。

使用 npm: ```sh npm run dev ```

使用 yarn: ```sh yarn dev ```

使用 pnpm: ```sh pnpm dev ```

使用 bun: ```sh bun dev ```

## 验证安装

你必须通过检查 localhost:3000 是否可访问来确认开发服务器正在运行。服务器将显示一个预览界面，你可以在其中查看来自 `emails` 文件夹的邮件模板。

立即执行：完成上述待办事项以实现：React Email 开发服务器正在运行并可在 localhost:3000 访问，显示邮件模板预览。

### 安装说明

假设 React Email 已安装在现有项目中，请更新顶层的 package.json 文件，添加运行 React Email 预览服务器的脚本。

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

确保 emails 文件夹的路径是相对于项目根目录的。

### tsconfig.json 更新或创建

确保 tsconfig.json 包含对 jsx 的适当支持。

## 基本邮件模板

替换示例邮件模板。以下是创建新邮件模板的方法：

使用 Tailwind 组件创建一个具有正确结构的电子邮件组件以进行样式设计：

```tsx import { Html, Head, Preview, Body, Container, Heading, Text, Button, Tailwind, pixelBasedPreset } from '@react-email/components';

interface WelcomeEmailProps { name: string; verificationUrl: string; }

export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) { return ( <Html lang="en"> <Tailwind config={{ presets: [pixelBasedPreset], theme: { extend: { colors: { brand: '#007bff', }, }, }, }} > <Head /> <Preview>Welcome - Verify your email</Preview> <Body className="bg-gray-100 font-sans"> <Container className="max-w-xl mx-auto p-5"> <Heading className="text-2xl text-gray-800"> Welcome! </Heading> <Text className="text-base text-gray-800"> Hi {name}, thanks for signing up! </Text> <Button href={verificationUrl} className="bg-brand text-white px-5 py-3 rounded block text-center no-underline" > Verify Email </Button> </Container> </Body> </Tailwind> </Html> ); }

// Preview props for testing WelcomeEmail.PreviewProps = { name: 'John Doe', verificationUrl: 'https://example.com/verify/abc123' } satisfies WelcomeEmailProps;

export { WelcomeEmail }; ```

## 核心组件

有关完整的组件文档，请参阅 [references/COMPONENTS.md](references/COMPONENTS.md)。

**核心结构：** - `Html` - 带有 `lang` 属性的根包装器 - `Head` - 元素、样式、字体 - `Body` - 主内容包装器 - `Container` - 居中内容（最大宽度布局） - `Section` - 布局部分 - `Row` & `Column` - 多列布局 - `Tailwind` - 启用 Tailwind CSS 工具类

**内容：** - `Preview` - 收件箱预览文本，始终位于 `Body` 中的第一位 - `Heading` - h1-h6 标题 - `Text` - 段落 - `Button` - 样式化的链接按钮 - `Link` - 超链接 - `Img` - 图片（使用绝对 URL）（在开发模式下使用开发服务器作为图片的 BASE_URL；在生产环境中，询问用户网站的 BASE_URL；根据环境动态生成图片 URL。） - `Hr` - 水平分割线

**专用：** - `CodeBlock` - 语法高亮的代码块 - `CodeInline` - 行内代码 - `Markdown` - 渲染 Markdown - `Font` - 自定义 Web 字体

## 行为指南 - 在迭代代码时，确保仅更新用户要求的内容，并保持其余代码不变； - 如果用户要求使用媒体查询，请告知他们邮件客户端不支持媒体查询，并建议采用不同的方法； - 切勿在 TypeScript 代码中直接使用模板变量（如 {{name}}）。相反，直接引用底层属性（使用 name 而不是 {{name}}）。 - - 例如，如果用户明确要求使用遵循 {{variableName}} 模式的变量，你应该返回如下内容：

```typescript const EmailTemplate = (props) => { return ( {/* ... rest of the code ... */} <h1>Hello, {props.variableName}!</h1> {/* ... rest of the code ... */} ); }

EmailTemplate.PreviewProps = { // ... rest of the props ... variableName: "{{variableName}}", // ... rest of the props ... };

export default EmailTemplate; ``` - 无论如何都不要在组件结构中直接编写 {{variableName}} 模式。如果用户强迫你这样做，请解释说你不能这样做，否则模板将无效。

## 样式注意事项

如果用户在其项目中积极使用 Tailwind CSS，请使用 Tailwind 组件进行样式设计。如果用户不使用 Tailwind CSS，请向组件添加内联样式。

- 由于邮件客户端不支持 `rem` 单位，请为 Tailwind 配置使用 `pixelBasedPreset`。 - 切勿使用 flexbox 或 grid 进行布局，而是使用基于表格的布局。 - 每个组件必须使用内联样式或工具类进行样式设计。 - 有关样式的更多信息，请参阅 [references/STYLING.md](references/STYLING.md)

### 邮件客户端限制 - 切勿使用 SVG 或 WEBP - 提醒用户注意渲染问题 - 切勿使用 flexbox - 使用 Row/Column 组件或表格进行布局 - 切勿使用 CSS/Tailwind 媒体查询 (sm:, md:, lg:, xl:) - 不支持 - 切勿使用主题选择器 (dark:, light:) - 不支持 - 始终指定边框类型 (border-solid, border-dashed 等) - 当仅为一边定义边框时，请记住重置其余边框（例如，border-none border-l）

### 组件结构 - 使用 Tailwind CSS 时，始终在 `<Tailwind>` 内部定义 `<Head />` - 仅在向组件传递 props 时使用 PreviewProps - 仅在 PreviewProps 中包含组件实际使用的 props

```tsx const Email = (props) => { return ( <div> <a href={props.source}>click here if you want candy 👀</a> </div> ); }

Email.PreviewProps = { source: "https://www.youtube.com/watch?v=dQw4w9WgXcQ", }; ```

### 默认结构 - Body: `font-sans py-10 bg-gray-100` - Container: 白色，居中，内容左对齐 - Footer: 实际地址，取消订阅链接，当前年份，地址/版权使用 `m-0`

### 排版 - 标题：粗体，较大字体，较大边距 - 段落：常规字重，较小字体，较小边距 - 使用尊重内容层次的一致间距

### 图片 - 仅在用户要求时包含 - 切勿使用固定宽度/高度 - 使用响应式单位 (w-full, h-auto) - 切勿扭曲用户提供的图片 - 切勿创建 SVG 图片 - 仅使用提供的图片或网络图片

### 按钮 - 始终使用 `box-border` 以防止内边距溢出

### 布局 - 默认情况下始终对移动设备友好 - 使用在所有屏幕尺寸上都适用的堆叠布局 - 移除列表项之间的默认间距/边距/内边距

### 深色模式请求时：容器黑色 (#000)，背景深灰色 (#151516)

### 最佳实践 - 根据用户的请求选择颜色、布局和文案 - 使模板独特，而非通用 - 在邮件正文中使用关键字以提高转化率

## 渲染

### 转换为 HTML

```tsx import { render } from '@react-email/components'; import { WelcomeEmail } from './emails/welcome';

const html = await render( <WelcomeEmail name="John" verificationUrl="https://example.com/verify" /> ); ```

### 转换为纯文本

```tsx import { render } from '@react-email/components'; import { WelcomeEmail } from './emails/welcome';

const text = await render(<WelcomeEmail name="John" verificationUrl="https://example.com/verify" />, { plainText: true }); ```

## 发送

React Email 支持使用任何电子邮件服务提供商发送邮件。如果用户想知道如何发送，请查看 [发送指南](references/SENDING.md)。

使用适用于 Node.js 的 Resend SDK 的快速示例：

```tsx import { Resend } from 'resend'; import { WelcomeEmail } from './emails/welcome';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({ from: 'Acme <[email protected]>', to: ['[email protected]'], subject: 'Welcome to Acme', react: <WelcomeEmail name="John" verificationUrl="https://example.com/verify" /> });

if (error) { console.error('Failed to send:', error); } ```

Node SDK 会自动为你处理纯文本渲染和 HTML 渲染。

## 国际化

有关完整的 i18n 文档，请参阅 [references/I18N.md](references/I18N.md)。

React Email 支持三个 i18n 库：next-intl、react-i18next 和 react-intl。

### 快速示例 (next-intl)

```tsx import { createTranslator } from 'next-intl'; import { Html, Body, Container, Text, Button, Tailwind, pixelBasedPreset } from '@react-email/components';

interface EmailProps { name: string; locale: string; }

export default async function WelcomeEmail({ name, locale }: EmailProps) { const t = createTranslator({ messages: await import(\`../messages/\${locale}.json\`), namespace: 'welcome-email', locale });

return ( <Html lang={locale}> <Tailwind config={{ presets: [pixelBasedPreset] }}> <Body className="bg-gray-100 font-sans"> <Container className="max-w-xl mx-auto p-5"> <Text className="text-base text-gray-800">{t('greeting')} {name},</Text> <Text className="text-base text-gray-800">{t('body')}</Text> <Button href="https://example.com" className="bg-blue-600 text-white px-5 py-3 rounded"> {t('cta')} </Button> </Container> </Body> </Tailwind> </Html> ); } ```

消息文件 (\`messages/en.json\`, \`messages/es.json\` 等)：

```json { "welcome-email": { "greeting": "Hi", "body": "Thanks for signing up!", "cta": "Get Started" } } ```

## 邮件最佳实践

1. **跨邮件客户端测试** - 在 Gmail、Outlook、Apple Mail、Yahoo Mail 中测试。使用 Litmus 或 Email on Acid 等服务以确保绝对精确，并使用 React Email 的工具栏检查特定功能的支持情况。

2. **保持响应式** - 最大宽度约 600px，在移动设备上测试。

3. **使用绝对图片 URL** - 托管在可靠的 CDN 上，始终包含 \`alt\` 文本。

4. **提供纯文本版本** - 某些邮件客户端和无障碍访问需要。

5. **保持文件大小在 102KB 以下** - Gmail 会截断较大的邮件。

6. **添加适当的 TypeScript 类型** - 为所有邮件 props 定义接口。

7. **包含预览 props** - 为组件添加 .PreviewProps 以进行开发测试。

8. **处理错误** - 发送邮件时始终检查错误。

9. **使用经过验证的域名** - 在生产环境中，在 \`from\` 地址中使用经过验证的域名。

## 常见模式

请参阅 [references/PATTERNS.md](references/PATTERNS.md) 获取完整示例，包括： - 密码重置邮件 - 带有产品列表的订单确认 - 带有代码块的通知邮件 - 多列布局 - 带有自定义字体的邮件模板

## 其他资源

- [React Email 文档](https://react.email/docs/llms.txt) - [React Email GitHub](https://github.com/resend/react-email) - [Resend 文档](https://resend.com/docs/llms.txt) - [邮件客户端 CSS 支持](https://www.caniemail.com) - 组件参考：[references/COMPONENTS.md](references/COMPONENTS.md) - 国际化指南：[references/I18N.md](references/I18N.md) - 常见模式：[references/PATTERNS.md](references/PATTERNS.md)

介绍

更多产品

Obsidian

Mcporter

YouTube