React Email Agent Skill 完全指南让 AI Agent 构建、渲染与发送 HTML 邮件【免费下载链接】react-email Build and send emails using React项目地址: https://gitcode.com/GitHub_Trending/re/react-email导读本文围绕当前仓库中skills/react-email/技能包展开介绍如何让 AI Agent 掌握 React Email 的完整开发能力——从安装脚手架、编写组件化邮件模板到 Tailwind 样式规范、HTML/纯文本渲染、多邮件服务商发送、国际化与可视化编辑器集成。读完本文你将理解该技能包的渐进式披露设计、核心指令SKILL.md与 6 份按需加载的参考文档references/如何协作并能在自己的 Agent 工作流中复用它来稳定产出符合邮件客户端兼容性要求的模板。技能包概览什么是 Agent Skillskills/react-email/README.md开篇就说明了本目录的定位这是一个Agent Skill一种给 AI Agent 注入专业知识与工作流的标准化格式。该技能教会 Agent 五类核心能力使用 React Email 组件构建 HTML 邮件模板通过react-email/editor为 React 应用接入可视化拖拽式邮件编辑器通过 Resend 及其他服务商发送邮件实现多语言国际化支持遵循邮件开发最佳实践。技能元数据见 SKILL.md 的 frontmatter进一步界定了它的触发场景构建 HTML 邮件模板、给应用添加可视化邮件编辑器、把邮件渲染为 HTML、用 Resend 发送邮件覆盖欢迎邮件、密码重置、通知、订单确认、新闻通讯、事务邮件以及可嵌入的编辑器组件等场景。技能包结构与渐进式披露设计目录结构skills/ └── react-email/ ├── SKILL.md # 核心技能指令 350 行 ├── TESTS.md # 技能合规性测试场景 └── references/ ├── COMPONENTS.md # 组件完整参考 ├── EDITOR.md # 可视化邮件编辑器参考 ├── I18N.md # 国际化指南 ├── PATTERNS.md # 常见邮件模式与示例 ├── SENDING.md # 邮件发送指南 └── STYLING.md # 样式与 CSS 参考渐进式披露Progressive Disclosure技能包按三层设计以控制 Agent 的上下文占用元数据约 100 tokenfrontmatter 中的名称与描述用于技能选择核心指令约 3K tokenSKILL.md的完整内容技能激活时加载详细参考按需加载组件文档、国际化指南、模式示例等只在处理具体任务时读取。这种按需加载设计让 Agent 只为当前任务加载必要的内容避免一次性吞入全部文档。这也是为什么SKILL.md被严格控制在 350 行以内而references/则承担深度内容。安装与项目初始化技能包要求 Agent 先完成安装或脚手架搭建SKILL.md 提供了三种方式方式一直接安装npm i react-email方式二脚手架新项目npx create-emaillatest cd react-email-starter npm install npm run devcreate-email脚手架对应仓库中的 packages/create-email支持 npm、yarn、pnpm、bun 任一包管理器只需替换相应命令。开发服务器默认运行在localhost:3000提供emails文件夹内模板的预览界面。方式三接入现有项目安装依赖后在package.json添加脚本{ scripts: { email: email dev --dir emails --port 3000 } }注意两点--dir指向的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 langen Tailwind config{{ presets: [pixelBasedPreset], theme: { extend: { colors: { brand: #007bff, }, }, }, }} Head / Body classNamebg-gray-100 font-sans PreviewWelcome - Verify your email/Preview Container classNamemax-w-xl mx-auto p-5 Heading classNametext-2xl text-gray-800 Welcome! /Heading Text classNametext-base text-gray-800 Hi {name}, thanks for signing up! /Text Button href{verificationUrl} classNamebg-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 };几个值得注意的细节Preview必须位于Body内部第一个元素作为收件箱预览文本Button必须带box-border类防止 padding 撑破按钮宽度.PreviewProps用于本地开发预览时提供测试数据且只应包含组件实际用到的 props所有组件统一从react-email包导入——packages/react-email/src/index.ts 的第 1-2 行export * from react-email/render与export * from ./components/index.js就是这一统一入口的实现组件与render等渲染工具均由主包对外暴露。组件体系三类组件参考references/COMPONENTS.md 给出完整组件清单全部从react-email导入结构组件组件作用与要点Html根包裹组件带lang/dir属性Headmeta、样式、字体等文档头部元素Body邮件内容主体包裹Container最外层水平居中容器内置max-width: 37.5em一封邮件只能使用一次Section内部内容块无内置最大宽度用于在Container内分组Row/Column多列布局Column必须搭配Row使用宽度建议用百分比如w-1/2、w-1/3且合计 100%Tailwind启用 Tailwind 工具类的包裹组件仅接受configprop内容组件组件作用与要点Preview收件箱预览文本保持在 140 字符以内永远是Body第一个元素Headingh1-h6 标题用asprop 指定级别Text段落文本Button样式化为按钮的链接href必填target默认_blank务必带box-borderLink超链接href必填Img图片src必须为绝对 URL默认alt有意义图片需写描述性 altHr水平分隔线必须显式指定边框类型如border-solid专用组件组件作用与要点CodeBlockPrism.js 语法高亮代码块code/language/theme必填应包在带overflow-auto的div中防止 padding 溢出lineNumbers默认 falseCodeInline在所有邮件客户端都可预测渲染的行内代码Markdown将 Markdown 转为邮件模板代码支持markdownCustomStyles与markdownContainerStylesFont自定义 Web 字体支持 woff2推荐、woff、truetype、opentype组件参考中强调只导入实际用到的组件不要引入未使用的Button、Img、Row等。样式规范Tailwind 与邮件客户端限制统一使用 pixelBasedPresetreferences/STYLING.md 反复强调邮件客户端不支持rem单位因此 Tailwind 配置必须引入pixelBasedPreset从react-email导入将基于 rem 的工具类换算为像素。这也是 TESTS.md 中 Test A6、A15 的硬性验收标准。邮件客户端不支持的 CSS 特性特性处理方式SVG/WEBP 图片仅使用 PNG 或 JPEGFlexbox / Grid使用Row/Column组件或表格布局Outlook 使用 Word 渲染引擎不支持 flex/grid媒体查询sm:、md:、lg:、xl:使用移动优先的堆叠布局Gmail 会剥离媒体查询、Outlook 直接忽略主题选择器dark:、light:若需深色主题直接在主题/样式中使用深色值不加前缀rem单位通过pixelBasedPreset转为像素必需工具类组件必需类原因Buttonbox-border防止 padding 溢出按钮宽度Hr/ 任何边框border-solid或border-dashed等邮件客户端不继承边框类型单侧边框border-none 对应侧先重置其他侧默认边框单侧边框的典型写法border-none border-l border-solid border-l-gray-300。结构注意点使用 Tailwind 时Head /必须放在Tailwind内部Preview永远是Body第一个元素已知尺寸元素logo、图标用固定宽高内容图片用响应式尺寸w-full h-auto。品牌一致性STYLING.md 建议为所有模板建立集中的 Tailwind 配置如emails/tailwind.config.ts用satisfies TailwindConfig获得智能提示统一管理品牌色primary/secondary/text/text muted/background/surface模板中只使用语义化类名如bg-brand-primary而不要硬编码色值配色变化时只改配置文件。静态文件与图片处理目录结构本地图片必须放在emails目录内的static文件夹project/ ├── emails/ │ ├── welcome.tsx │ └── static/ -- 图片放这里 │ └── logo.pngDev / Production URL 模式使用NODE_ENV判断的baseURL模式让图片在开发预览与生产环境都能工作const baseURL process.env.NODE_ENV production ? https://cdn.example.com // 用户的生产 CDN : ; export default function Email() { return ( Img src{${baseURL}/static/logo.png} altLogo width150 height50 / ); }工作原理开发时baseURL为空字符串URL 为/static/logo.png由 React Email 开发服务器直接伺服生产时baseURL替换为 CDN 域名。技能包明确禁止硬编码localhost:3000TESTS.md 的 Test C2、D5 专门验证这一点并要求在编码前向用户确认生产托管 URL。渲染为 HTML 与纯文本render函数统一负责把 React 组件渲染为 HTML 与纯文本import { render } from react-email; import { WelcomeEmail } from ./emails/welcome; // 渲染为 HTML const html await render( WelcomeEmail nameJohn verificationUrlhttps://example.com/verify / ); // 渲染为纯文本 const text await render(WelcomeEmail nameJohn verificationUrlhttps://example.com/verify /, { plainText: true });从源码看render的实现位于 packages/render/src/node/render.tsx它动态加载react-dom/server优先使用renderToReadableStream否则回退renderToPipeableStream用ErrorBoundary包裹节点并在出错时立即 reject拿到 HTML 后若options.plainText为真则通过toPlainText或unstableTextConversion对应的转换器产出纯文本。仓库在packages/render/src/node/、edge/、browser/三个环境各有一套render实现如 edge 版并在 node 渲染测试 等用例中验证了plainText: true的纯文本输出路径。发送邮件多服务商方案references/SENDING.md 强调一个前置要求from地址必须使用已验证域名若用户没有已验证域名应引导其向邮件服务商完成验证。Resend推荐Resend Node SDK 可直接接收 React 组件自动处理 HTML 与纯文本渲染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 onboardingresend.dev, to: [userexample.com], subject: Welcome to Acme, react: WelcomeEmail nameJohn verificationUrlhttps://example.com/verify / }); if (error) { console.error(Failed to send:, error); }上传为 Resend 模板也可将邮件上传为 Resend 模板之后在 SDK 中按模板 ID 发送npx react-emaillatest resend setupawait resend.emails.send({ from: Acme onboardingresend.dev, to: [userexample.com], subject: Welcome to Acme, template: { id: 1245-1256-1234-1234, } });其他服务商SENDING.md 给出了三种通用模式——先render出 HTML再交给各服务商 SDKNodemailernodemailer.createTransport(...)后transporter.sendMail({ html })Mailgunmailgun.client({ key })后client.messages.create(domain, { html })SendGridsgMail.setApiKey(...)后sgMail.send({ html })。仓库 examples 目录下还有 AWS SES、Azure Communication、Mailtrap、Postmark、SendGrid、Mailgun、Resend 等十余个可运行的服务商示例可对照参考。CLI 命令react-email包通过email命令提供 CLI命令说明email dev --dir path --port port启动预览开发服务器默认./emails端口 3000email build --dir path构建预览应用以部署到生产email start运行构建后的预览应用email export --outDir path --pretty --plainText --dir path将模板导出为静态 HTML 文件email resend setup通过 API key 将 CLI 连接到 Resend 账户email resend reset移除已存储的 Resend API key国际化i18nreferences/I18N.md 说明 React Email 官方支持三个 i18n 库next-intl适合 Next.js 应用、react-intl / FormatJS适合复数、日期、数字等复杂格式化、react-i18next适合非 Next.js 应用或需要更多控制。以 next-intl 为例核心步骤是创建按语言组织的消息文件messages/en.json、messages/es.json、messages/fr.json在模板中用createTranslator读取当前 locale 的消息export default async function WelcomeEmail({ name, verificationUrl, locale }: WelcomeEmailProps) { const t createTranslator({ messages: await import(../messages/${locale}.json), namespace: welcome-email, locale }); return ( Html lang{locale} {/* ... Preview{t(subject)}/Preview ... */} /Html ); }发送时按用户 locale 传入组件WelcomeEmail nameJean verificationUrl... localefr /。最佳实践还包括locale 设为必填 propHtml lang{locale}RTL 语言[ar, he, fa]自动设置dir{isRTL ? rtl : ltr}提供 fallback 翻译locale 文件加载失败时回退英文各 locale 文件保持键名一致注意翻译邮件主题行用IntlAPI 处理日期/数字/货币格式的一致性。可视化邮件编辑器react-email/editor技能包支持为应用接入可视化编辑器。该编辑器基于 TipTap/ProseMirror 构建产出邮件就绪的 HTML。references/EDITOR.md 详细记录了其能力安装与 CSSnpm install react-email/editor需要React 18与支持 package exports 的打包器Vite、Next.js、Webpack 5 等。引入默认主题import react-email/editor/themes/default.css;也可按需引入styles/bubble-menu.css、styles/slash-command.css、styles/inspector.css。EmailEditor 全功能组件import { EmailEditor, type EmailEditorRef } from react-email/editor; import react-email/editor/themes/default.css; import { useRef } from react; export function MyEditor() { const ref useRefEmailEditorRef(null); return ( EmailEditor ref{ref} contentpStart typing.../p themebasic / ); }EmailEditor内置了 StarterKit、EmailTheming、气泡菜单与斜杠命令。其 props 包括contentHTML 字符串或 TipTap JSON、onChange、onUploadImage、onReady、themebasic | minimal默认basic、editable、placeholder、bubbleMenu、extensions完全覆盖默认扩展与className。EmailEditorRef暴露export()返回{ html, text }、getJSON()、getHTML()与底层editor实例。编辑器架构的六个入口导入路径用途react-email/editorEmailEditor全功能组件react-email/editor/corecomposeReactEmail序列化、EmailNode、EmailMark、事件总线、类型react-email/editor/extensionsStarterKit与 35 邮件感知扩展react-email/editor/uiBubbleMenu、SlashCommand、Inspectorreact-email/editor/pluginsEmailTheming插件react-email/editor/utils属性辅助与样式工具扩展与导出BubbleMenu选中文本时出现的浮动格式工具栏粗体、斜体、下划线、删除线、代码、大写、对齐、节点类型、链接另有LinkDefault、ButtonDefault、ImageDefault上下文菜单可用excludeItems排除条目SlashCommand输入/插入内容块默认命令覆盖 TEXT、H1-H3、列表、引用、代码、BUTTON、DIVIDER、SECTION、两列/三列/四列布局也可import { BUTTON, H1, H2, TEXT }单独挑选Inspector随选区自动切换文档/节点/文本控制的面板Inspector.Root/Breadcrumb/Document/Node/Text需要EmailTheming插件EmailTheming主题在composeReactEmail时解析并内联为style属性内置basic完整排版默认与minimal几乎无样式composeReactEmail低层导出函数遍历文档节点与 mark对每个EmailNode/EmailMark调用renderToReactEmail()应用主题样式后包进基础模板渲染出 HTML 与纯文本自定义扩展用EmailNode.create({ ..., renderToReactEmail({ children, style }) })创建邮件兼容的节点EmailMark用于行内格式。常见邮件模式references/PATTERNS.md 提供了五个可直接参考的完整模板每个都带PreviewProps与 TypeScript 类型定义密码重置邮件重置按钮bg-red-600、过期时间说明、安全提示未请求请忽略此邮件订单确认含商品列表订单号/日期信息栏、逐商品行图片 名称 SKU 数量 小计、小计/运费/税费/总计汇总行、配送地址块——全部用Row/Column实现多列对齐带代码块的通知邮件按严重级别info/warning/error/success着色的状态条与徽章、CodeBlock展示 JSON 日志、可选的操作链接多列新闻通讯头条文章 两列文章卡片 页脚含退订链接与版权年份Row内每列w-1/2团队邀请邮件邀请人信息、角色展示块、接受邀请按钮、过期提醒。这些模式共同示范了技能包的核心规范Tailwind 工具类 pixelBasedPreset、TypeScript 类型、PreviewProps、移动优先响应式布局。邮件最佳实践与无障碍通用最佳实践在 Gmail、Outlook、Apple Mail、Yahoo Mail 等客户端中测试保持响应式主容器最大宽度约 600px并测试移动端图片使用托管在可靠 CDN 的绝对 URL写有意义的 alt 文本装饰性图片间隔符、分隔线、背景装饰显式传alt——React Email 的Img默认即alt提供纯文本版本无障碍必需控制邮件体积在102KB 以内Gmail 会截断超限邮件为所有邮件 props 定义 TypeScript 接口为开发测试添加.PreviewProps生产from地址使用已验证域名。无障碍框架免费提供的部分Html自动设置lang与dir默认langen dirltr可按 locale 覆盖Img默认alt装饰图片会被屏幕阅读器跳过Markdown渲染的布局表格带rolepresentationPreview同时输出title标签。升级到最新版npm install react-emaillatest即可获得上述默认行为。仍需内容层面完成的部分以一个Heading ash1开头次级标题按顺序嵌套、不跳级有意义图片写描述性 alt装饰图片显式alt绝不省略该属性链接图片绝不视为装饰Img位于Link/Button内时alt 必须描述链接去向否则链接将没有可访问名称链接文本要描述目的地如ButtonRead the report/Button而不是 click here文本对比度达到 4.5:1WCAG AA并在深色模式下预览手工编写的布局表格Markdown之外需自行添加rolepresentation非英文邮件传入 localeHtml lang{locale} dir{isRTL ? rtl : ltr}。Agent 行为准则与模板变量处理SKILL.md 规定了 Agent 编码时的行为边界其中最关键的是模板变量的处理绝不能在 TypeScript 代码中直接使用{{name}}这类模板变量而应直接引用底层属性如果用户明确要求{{variableName}}只把 mustache 字符串放进PreviewProps绝不写进组件 JSXconst EmailTemplate (props) { return ( h1Hello, {props.variableName}!/h1 ); } EmailTemplate.PreviewProps { variableName: {{variableName}}, }; export default EmailTemplate;因为{{name}}写在 JSX 中会使模板成为非法 TypeScript/JSX。其他准则包括迭代代码时只改用户要求的部分用户要求媒体查询时提示多数邮件客户端不支持并建议替代方案。编码前的澄清问题当用户请求邮件模板但未提供必要信息时Agent 应先提问再写代码品牌色——主品牌色hex如#007bffLogo——是否有 logo 文件及其格式仅 PNG/JPG若为 SVG/WEBP 需警告风格偏好——专业、休闲还是极简生产 URL——静态资源在生产环境的托管位置。技能合规性测试TESTS.mdskills/react-email/TESTS.md 定义了该技能的验证体系采用 TDD 思路先在不加载技能的情况下运行子 Agent 建立失败基线再加载技能验证是否合规最后做压力测试检验技能在用户施压时是否依然成立。测试覆盖的关键断言包括A1 模板变量{firstName}进 JSX{{firstName}}只进PreviewPropsA2 SVG/WEBP拒绝内联 SVG改用 PNG并说明受影响客户端Gmail、Outlook、Yahoo 等A3/A12 Flexbox/Grid改用Row/Column表格布局不出现display: flex或display: gridA4 媒体查询不出现sm:/md:/lg:/xl:前缀类A5 深色模式不出现dark:前缀类深色需求直接应用深色值A6/A15 pixelBasedPreset必须从react-email导入并放入presets不得从react-email/tailwind等错误路径导入A7 边框类型Hr必须带border-solid等边框类型单侧边框需先border-none重置A8 box-borderButton必须带box-border表格加入后 5 个测试 Agent 全部通过A9 列宽多列布局的Column必须指定宽度且合计 100%A10 Head 位置Head /必须在Tailwind内部A11 CodeBlock 包裹外层需overflow-autodivA13 图片尺寸警告固定尺寸可能失真建议保留宽高比w-full max-w-[500px] h-autoA14 干净导入只导入实际使用的组件B1/B2 用户交互编码前询问品牌色、logo 格式含 SVG/WEBP 警告、风格、生产 URLC1/C2 静态文件图片复制到emails/static/使用baseURL模式而非硬编码 localhostD1-D5 压力测试用户坚持错误模式时逐条解释限制、给出正确替代方案但绝不妥协F1/F2 国际化使用受支持 i18n 库、设置lang/dirG1 纯文本提及纯文本版本与{ plainText: true }H1 体积警告 Gmail 的 102KB 截断限制。TESTS.md 还记录了多轮回归结果例如 A1、A6、A8、A15 的回归均显示WITH skill状态通过证明该技能包对 Agent 行为有可度量的约束效果。结合仓库源码的落地点统一入口packages/react-email/src/index.ts 汇总导出react-email/render与全部组件对应技能包所有导入都从react-email来的规范渲染实现packages/render/src/node/render.tsx 展示render的完整执行路径流式渲染、错误边界、纯文本转换、DOCTYPE 注入同目录的render-node.spec.tsx与edge、browser版本共同验证多环境一致性CLI 与预览packages/react-email/src/cli/目录对应email dev/build/start/export/resend命令的实现编辑器packages/editor/src/下core/、extensions/、ui/、plugins/分别对应 EDITOR.md 描述的六个入口示例模板apps/demo/emails 提供了 Barebone、Matte、Protocol、Arcane、Studio 五套主题与社区场景magic-links、newsletters、notifications、receipts、reset-password 等的真实模板可对照 PATTERNS.md 阅读。结语skills/react-email/是一个设计完整的 Agent 技能包以 350 行内的SKILL.md承载核心指令以 6 份references/文档按需提供深度内容以TESTS.md保障行为可验证。对开发者而言它既是一份可直接复用的 Agent 工作流配置也是一份浓缩了 React Email 最佳实践的权威开发指南——从组件结构、样式约束到渲染、发送、国际化与可视化编辑器覆盖了用 React 构建 HTML 邮件的完整链路。【免费下载链接】react-email Build and send emails using React项目地址: https://gitcode.com/GitHub_Trending/re/react-email创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考