react-email

Name: react-email
Author: resend

React Email

使用 React 元件建立並發送 HTML 電子郵件。以元件為基礎的現代化電子郵件開發方式，相容於所有主流郵件客戶端。

安裝

npm i react-email

或建立新專案：

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

這適用於任何套件管理工具（npm、yarn、pnpm、bun），請自行替換對應指令。

開發伺服器會在 localhost:3000 啟動，並提供 emails 資料夾中範本的預覽介面。

加入現有專案

安裝套件並在 package.json 中加入腳本：

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

請確保 emails 資料夾的路徑相對於專案根目錄。同時確認 tsconfig.json 已正確支援 JSX。

基本電子郵件範本

使用 Tailwind 元件建立結構完整的電子郵件元件：

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

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 />
        <Body className="bg-gray-100 font-sans">
          <Preview>歡迎 - 驗證您的電子郵件</Preview>
          <Container className="max-w-xl mx-auto p-5">
            <Heading className="text-2xl text-gray-800">
              歡迎！
            </Heading>
            <Text className="text-base text-gray-800">
              嗨 {name}，感謝您的註冊！
            </Text>
            <Button
              href={verificationUrl}
              className="bg-brand text-white px-5 py-3 rounded block text-center no-underline box-border"
            >
              驗證電子郵件
            </Button>
          </Container>
        </Body>
      </Tailwind>
    </Html>
  );
}

// 用於測試的預覽屬性
WelcomeEmail.PreviewProps = {
  name: 'John Doe',
  verificationUrl: 'https://example.com/verify/abc123'
} satisfies WelcomeEmailProps;

export { WelcomeEmail };

行為準則

在修改程式碼時，只更新使用者要求的內容，其餘保持不變。
如果使用者要求使用 media query，請告知大多數郵件客戶端不支援，並建議其他方式。
切勿在 TypeScript 程式碼中直接使用範本變數（如 {{name}}）。請直接引用底層屬性。如果使用者明確要求 {{variableName}}，請將 mustache 字串僅放在 PreviewProps 中，絕不放在元件 JSX 中：

const EmailTemplate = (props) => {
  return (
    <h1>Hello, {props.variableName}!</h1>
  );
}

EmailTemplate.PreviewProps = {
  variableName: "{{variableName}}",
};

export default EmailTemplate;

切勿在元件結構中直接使用 {{variableName}} 模式。如果使用者堅持，請說明這會使範本無效。

核心元件

完整元件文件請參閱 references/COMPONENTS.md。

核心結構：

Html - 根包裝器，包含 lang 屬性
Head - meta 元素、樣式、字型
Body - 主要內容包裝器
Container - 最外層置中包裝器（內建 max-width: 37.5em）。每封郵件僅使用一次。
Section - 內部內容區塊（無內建 max-width）。用於在 Container 內分組內容。
Row 與 Column - 多欄佈局
Tailwind - 啟用 Tailwind CSS 工具類別

內容：

Preview - 收件匣預覽文字，永遠放在 <Body> 內的第一個位置
Heading - h1 到 h6 標題
Text - 段落
Button - 樣式化的連結按鈕（務必包含 box-border）
Link - 超連結
Img - 圖片（請參閱下方靜態檔案章節）
Hr - 水平分隔線

特殊用途：

CodeBlock - 語法高亮的程式碼區塊
CodeInline - 行內程式碼
Markdown - 渲染 Markdown
Font - 自訂網頁字型

撰寫程式碼之前

當使用者要求電子郵件範本時，如果對方尚未提供以下資訊，請先提出釐清問題：

品牌顏色 - 詢問主要品牌顏色（十六進位色碼，如 #007bff）
標誌 - 詢問是否有標誌檔案及其格式（僅限 PNG/JPG - 若為 SVG/WEBP 請提出警告）
風格偏好 - 專業、休閒或簡約風格
正式環境 URL - 正式環境中靜態資源的託管位置？

靜態檔案與圖片

目錄結構

本機圖片必須放在 emails 目錄下的 static 資料夾中：

project/
├── emails/
│   ├── welcome.tsx
│   └── static/           <-- 圖片放在這裡
│       └── logo.png

開發與正式環境 URL

使用以下模式讓圖片在開發預覽和正式環境中都能正常運作：

const baseURL = process.env.NODE_ENV === "production"
  ? "https://cdn.example.com"  // 使用者的正式環境 CDN
  : "";

export default function Email() {
  return (
    <Img
      src={`${baseURL}/static/logo.png`}
      alt="Logo"
      width="150"
      height="50"
    />
  );
}

運作方式：

開發環境： baseURL 為空，因此 URL 為 /static/logo.png - 由 React Email 的開發伺服器提供
正式環境： baseURL 為 CDN 網域，因此 URL 為 https://cdn.example.com/static/logo.png

重要： 務必詢問使用者的正式環境託管 URL。請勿硬編碼 localhost:3000。

樣式設定

完整的樣式文件請參閱 references/STYLING.md，包含排版、佈局模式、深色模式與品牌一致性。

關鍵規則

使用 Tailwind 搭配 pixelBasedPreset（郵件客戶端不支援 rem）。從 react-email 匯入 pixelBasedPreset。
切勿使用 flexbox 或 grid — 請使用 Row/Column 元件或表格進行佈局。
避免使用 CSS/Tailwind media query（sm:、md:、lg:、xl:）— 郵件客戶端支援有限。
切勿使用主題選擇器（dark:、light:）— 不支援。
切勿使用 SVG 或 WEBP 圖片 — 請警告使用者可能出現渲染問題。
務必指定邊框類型（border-solid、border-dashed 等）— 郵件客戶端不會繼承邊框類型。
對於單側邊框，請先重設其他邊框（border-none border-l border-solid）。

必要類別

元件	必要類別	原因
`Button`	`box-border`	防止內距超出按鈕寬度
`Hr` / 任何邊框	`border-solid`（或 `border-dashed` 等）	郵件客戶端不會繼承邊框類型
單側邊框	`border-none` + 該側邊框	重設其他側邊的預設邊框

結構注意事項

使用 Tailwind CSS 時，務必將 <Head /> 定義在 <Tailwind> 內部
<Preview> 應永遠是 <Body> 內的第一個元素
只在 PreviewProps 中包含元件實際使用的屬性
對已知尺寸的元素（標誌、圖示）使用固定寬高；對內容圖片使用響應式尺寸（w-full、h-auto）

渲染

轉換為 HTML

import { render } from 'react-email';
import { WelcomeEmail } from './emails/welcome';

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

轉換為純文字

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

發送

React Email 支援透過任何電子郵件服務供應商發送。完整的發送文件（包含 Resend、Nodemailer 和 SendGrid 範例）請參閱 references/SENDING.md。

使用 Resend SDK 的快速範例：

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 <onboarding@resend.dev>',
  to: ['user@example.com'],
  subject: '歡迎加入 Acme',
  react: <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />
});

Resend Node SDK 會自動處理 HTML 和純文字渲染。

CLI 指令

react-email 套件提供可透過 email 指令存取的 CLI：

指令	說明
`email dev --dir <path> --port <port>`	啟動預覽開發伺服器（預設：`./emails`，連接埠 3000）
`email build --dir <path>`	建置預覽應用程式以部署至正式環境
`email start`	執行已建置的預覽應用程式
`email export --outDir <path> --pretty --plainText --dir <path>`	將範本匯出為靜態 HTML 檔案
`email resend setup`	透過 API 金鑰將 CLI 連線至您的 Resend 帳戶
`email resend reset`	移除已儲存的 Resend API 金鑰

國際化

完整的 i18n 文件請參閱 references/I18N.md。React Email 支援三個函式庫：next-intl、react-i18next 和 react-intl。

電子郵件編輯器

React Email 包含一個可嵌入應用程式的視覺化編輯器（@react-email/editor）。它基於 TipTap/ProseMirror 建置，可產生可直接用於電子郵件的 HTML。

完整文件請參閱 references/EDITOR.md，包含：

EmailEditor — 功能完整的元件，包含氣泡選單、斜線指令和主題設定
StarterKit — 35 個以上支援電子郵件的擴充功能（標題、清單、表格、欄位、按鈕等）
Inspector — 用於編輯樣式的上下文側邊欄
EmailTheming — 內建主題（basic、minimal），可自訂 CSS 屬性
composeReactEmail — 將編輯器內容匯出為可直接用於電子郵件的 HTML 和純文字
透過 EmailNode 和 EmailMark 自訂擴充功能

快速範例：

import { EmailEditor, type EmailEditorRef } from '@react-email/editor';
import '@react-email/editor/themes/default.css';
import { useRef } from 'react';

export function MyEditor() {
  const ref = useRef<EmailEditorRef>(null);

  return (
    <EmailEditor
      ref={ref}
      content="<p>開始輸入...</p>"
      theme="basic"
    />
  );
}

常見模式

完整的範例請參閱 references/PATTERNS.md，包含：

密碼重設電子郵件
附產品清單的訂單確認信
含程式碼區塊的通知電子郵件
多欄佈局
團隊邀請電子郵件

電子郵件最佳實務

跨郵件客戶端測試 - Gmail、Outlook、Apple Mail、Yahoo Mail
保持響應式 - 最大寬度約 600px，在行動裝置上測試
使用絕對圖片 URL - 託管在可靠的 CDN 上
撰寫有意義的替代文字 - 為內容圖片描述用途和細節；裝飾性圖片（間距、分隔線、背景裝飾）使用 alt=""。React Email 的 <Img> 預設為 alt=""。
提供純文字版本 - 無障礙功能所需
保持檔案大小在 102KB 以下 - Gmail 會截斷較大的郵件
加入適當的 TypeScript 型別 - 為所有電子郵件屬性定義介面
包含預覽屬性 - 加入 .PreviewProps 以便開發測試
使用驗證過的網域 - 用於正式環境的 from 地址

無障礙功能

React Email 處理結構性的預設值，其餘部分取決於內容。

React Email 免費提供的功能：

<Html> 設定 lang 和 dir（預設值：lang="en" dir="ltr" — 可依語言環境覆寫）
<Img> 預設為 alt=""，因此裝飾性圖片會被螢幕閱讀器略過
<Markdown> 使用 role="presentation" 渲染佈局表格
<Preview> 也會發出 <title> 標籤

執行 npm install react-email@latest 升級即可獲得這些預設值。

您仍需自行處理的部分（內容選擇）：

以單一 <Heading as="h1"> 開頭，依序巢狀嵌套子標題，切勿跳級（非常簡短的 SMS 風格郵件可能完全省略標題）
為有意義的圖片設定描述性的 alt；裝飾性圖片請傳入明確的 alt="" — 切勿省略該屬性
連結圖片永遠不是裝飾性的。 當 <Img> 位於 <Link> 或 <Button> 內部時，alt 必須說明連結的目的地 — 連結圖片使用 alt="" 會使連結沒有可存取的名稱
撰寫能說明目的地的連結文字（<Button>Read the report</Button>，而不是 click here）
達到 4.5:1 的文字對比度（WCAG AA）；在深色模式下預覽
對於手動建立的佈局表格（在 <Markdown> 之外），請加入 role="presentation"
對於非英文電子郵件，請傳入語言環境：<Html lang={locale} dir={isRTL ? 'rtl' : 'ltr'}>（請參閱 I18N.md）

完整的規則集、嚴重性排名和撰寫檢查清單，請參閱 email-best-practices 技能中的無障礙功能參考。

其他資源

您可能也喜歡

fix

247Kfrontend

Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.

react

獲取

vue-patterns

240Kfrontend

Vue.js 3 Composition API patterns, component architecture, reactivity best practices, Pinia state management, Vue Router navigation, and Nuxt SSR patterns. Activates for Vue, Nuxt, Vite, or Pinia projects. Use when building or reviewing Vue 3, Nuxt, or Pinia code — Composition API, reactivity, or router navigation.

affaan-m

獲取

fix

247Kfrontend

當出現 lint 錯誤、格式問題，或要在 commit 程式碼前確保能順利通過 CI 時使用。

facebook

獲取

繼續探索

瀏覽 frontend 熱門 Skills 最近更新