react-email

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"
  }
}

メールフォルダーへのパスが、プロジェクトのベースディレクトリからの相対パスになっていることを確認してください。また、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>Welcome - Verify your email</Preview>
          <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 box-border"
            >
              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 };

動作に関するガイドライン

• コードを反復して編集する際は、ユーザーが求めた箇所のみを更新してください。それ以外はそのまま維持してください。
• ユーザーがメディアクエリの使用を求めた場合は、ほとんどのメールクライアントがメディアクエリをサポートしていないことを伝え、別の方法を提案してください。
• TypeScript コード内でテンプレート変数（{{name}} など）を直接使用しないでください。代わりに、基となるプロパティを直接参照してください。ユーザーが明示的に {{variableName}} を求めた場合は、コンポーネント JSX ではなく PreviewProps にのみマスタッシュ文字列を配置してください。

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

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

export default EmailTemplate;

• コンポーネントの構造内に {{variableName}} のパターンを直接記述しないでください。ユーザーが強く求める場合は、そのようにするとテンプレートが無効になることを説明してください。

必須コンポーネント

コンポーネントの完全なドキュメントについては、references/COMPONENTS.md を参照してください。

基本構造：

• Html - lang 属性を持つルートラッパー
• Head - メタ要素、スタイル、フォント
• Body - メインコンテンツのラッパー
• Container - 最外側の中央揃えラッパー（max-width: 37.5em が組み込み済み）。メールごとに 1 回だけ使用してください。
• 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 - カスタム Web フォント

コードを書く前に

ユーザーからメールテンプレートの作成を依頼された際、以下の情報が提示されていない場合は、まず確認の質問をしてください。

1. ブランドカラー - ブランドのメインカラーを尋ねてください（#007bff のような 16 進数コード）
2. ロゴ - ロゴファイルの有無と形式を尋ねてください（PNG/JPG のみ。SVG/WEBP の場合は注意を促してください）
3. スタイルの好み - プロフェッショナル、カジュアル、ミニマルのいずれか
4. 本番 URL - 本番環境で静的アセットをホストする場所

静的ファイルと画像

ディレクトリ構成

ローカル画像は、メールディレクトリ内の static フォルダーに配置する必要があります。

project/
├── emails/
│   ├── welcome.tsx
│   └── static/           <-- Images go here
│       └── logo.png

開発環境と本番環境の URL

開発プレビューと本番環境の両方で動作する画像には、次のパターンを使用してください。

const baseURL = process.env.NODE_ENV === "production"
  ? "https://cdn.example.com"  // User's production 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 に対応していません）。pixelBasedPreset は react-email からインポートしてください。
• フレックスボックスやグリッドは使用せず、レイアウトには Row／Column コンポーネントまたはテーブルを使用してください。
• CSS／Tailwind のメディアクエリ（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 を使用する場合は、必ず <Tailwind> の内側に <Head /> を定義してください
• <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 <[email protected]>',
  to: ['[email protected]'],
  subject: 'Welcome to 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 の 3 つのライブラリに対応しています。

メールエディター

React Email には、アプリに埋め込めるビジュアルエディター（@react-email/editor）が含まれています。TipTap／ProseMirror をベースに構築されており、メールに適した HTML を生成します。

以下を含む詳しいドキュメントは、references/EDITOR.md を参照してください。

• EmailEditor — バブルメニュー、スラッシュコマンド、テーマ機能を備えた、必要な機能が揃ったコンポーネント
• StarterKit — メールに対応した 35 以上の拡張機能（見出し、リスト、テーブル、カラム、ボタンなど）
• Inspector — スタイルを編集するためのコンテキスト対応サイドバー
• EmailTheming — CSS プロパティをカスタマイズできる組み込みテーマ（basic、minimal）
• 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>Start typing...</p>"
      theme="basic"
    />
  );
}

よく使われるパターン

パスワードリセットメール、商品リスト付きの注文確認メール、コードブロック付きの通知メール、複数カラムのレイアウト、チーム招待メールなどの例については、references/PATTERNS.md を参照してください。

メールのベストプラクティス

1. 複数のメールクライアントでテストする - Gmail、Outlook、Apple Mail、Yahoo Mail
2. レスポンシブにする - 最大幅を約600pxに設定し、モバイルでテストします
3. 画像には絶対URLを使用する - 信頼できるCDNでホストします
4. 意味のある代替テキストを書く - コンテンツ画像には目的と詳細を説明する代替テキストを指定し、装飾画像（スペーサー、区切り線、背景の装飾）には alt="" を使用します。React Email の <Img> はデフォルトで alt="" になります。
5. プレーンテキスト版を用意する - アクセシビリティのために必須です
6. ファイルサイズを102KB未満に抑える - それより大きいメールはGmailで途中までしか表示されません
7. 適切なTypeScript型を追加する - すべてのメールプロパティにインターフェースを定義します
8. プレビュー用プロパティを含める - 開発時のテスト用に .PreviewProps を追加します
9. 検証済みのドメインを使用する - 本番環境の 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"> を1つだけ配置し、サブ見出しは順序どおりに入れ子にします。レベルを飛ばさないでください（ごく短いSMS形式のメールでは、見出し全体を省略してもかまいません）
• 意味のある画像には内容を説明する alt を設定し、装飾画像には明示的に alt="" を指定します。属性を省略しないでください
• リンク画像は装飾画像ではありません。 <Img> が <Link> または <Button> の内側にある場合、alt にはリンク先を説明する内容を指定する必要があります。リンク画像に alt="" を指定すると、リンクにアクセシブルな名前が付かなくなります
• リンク先がわかるリンクテキストを書きます（<Button>レポートを読む</Button> とし、「ここをクリック」は使いません）
• テキストのコントラスト比を4.5:1にします（WCAG AA）。ダークモードでもプレビューします
• <Markdown> の外で手作業で作成するレイアウト用テーブルには、role="presentation" を追加します
• 英語以外のメールでは、ロケールを渡します：<Html lang={locale} dir={isRTL ? 'rtl' : 'ltr'}>（I18N.md を参照）

ルール全体、重要度のランク付け、作成チェックリストについては、email-best-practices スキルのアクセシビリティリファレンスを参照してください。

その他のリソース

• React Email ドキュメント
• React Email GitHub
• Resend ドキュメント
• メールクライアントのCSSサポート
• コンポーネントリファレンス：references/COMPONENTS.md
• スタイルガイド：references/STYLING.md
• メールエディター：references/EDITOR.md
• 送信ガイド：references/SENDING.md
• 国際化ガイド：references/I18N.md
• よくあるパターン：references/PATTERNS.md