vercel-labs/json-render

react-email

React Email renderer for json-render that turns JSON specs into HTML or plain-text emails using @react-email/components and @react-email/render.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/vercel-labs/json-render --skill react-email

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

@json-render/react-email

React Email renderer that converts JSON specs into HTML or plain-text email output.

Quick Start

typescript
import { renderToHtml } from "@json-render/react-email";
import { schema, standardComponentDefinitions } from "@json-render/react-email";
import { defineCatalog } from "@json-render/core";

const catalog = defineCatalog(schema, {
  components: standardComponentDefinitions,
});

const spec = {
  root: "html-1",
  elements: {
    "html-1": { type: "Html", props: { lang: "en", dir: "ltr" }, children: ["head-1", "body-1"] },
    "head-1": { type: "Head", props: {}, children: [] },
    "body-1": {
      type: "Body",
      props: { style: { backgroundColor: "#f6f9fc" } },
      children: ["container-1"],
    },
    "container-1": {
      type: "Container",
      props: { style: { maxWidth: "600px", margin: "0 auto", padding: "20px" } },
      children: ["heading-1", "text-1"],
    },
    "heading-1": { type: "Heading", props: { text: "Welcome" }, children: [] },
    "text-1": { type: "Text", props: { text: "Thanks for signing up." }, children: [] },
  },
};

const html = await renderToHtml(spec);

Spec Structure (Element Tree)

Same flat element tree as @json-render/react: root key plus elements map. Root must be Html; children of Html should be Head and Body. Use Container (e.g. max-width 600px) inside Body for client-safe layout.

Creating a Catalog and Registry

typescript
import { defineCatalog } from "@json-render/core";
import { schema, defineRegistry, renderToHtml } from "@json-render/react-email";
import { standardComponentDefinitions } from "@json-render/react-email/catalog";
import { Container, Heading, Text } from "@react-email/components";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    ...standardComponentDefinitions,
    Alert: {
      props: z.object({
        message: z.string(),
        variant: z.enum(["info", "success", "warning"]).nullable(),
      }),
      slots: [],
      description: "A highlighted message block",
    },
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Alert: ({ props }) => (
      <Container style={{ padding: 16, backgroundColor: "#eff6ff", borderRadius: 8 }}>
        <Text style={{ margin: 0 }}>{props.message}</Text>
      </Container>
    ),
  },
});

const html = await renderToHtml(spec, { registry });

Server-Side Render APIs

FunctionPurpose
renderToHtml(spec, options?)Render spec to HTML email string
renderToPlainText(spec, options?)Render spec to plain-text email string

RenderOptions: registry, includeStandard (default true), state (for $state / $cond).

Visibility and State

Supports visible conditions, $state, $cond, repeat (repeat.statePath), nested repeat paths with { "$item": "field" }, and the same expression syntax as @json-render/react. Use state in RenderOptions when rendering server-side so expressions resolve.

Server-Safe Import

Import schema and catalog without React or @react-email/components:

typescript
import { schema, standardComponentDefinitions } from "@json-render/react-email/server";

Key Exports

ExportPurpose
defineRegistryCreate type-safe component registry from catalog
RendererRender spec in browser (e.g. preview); use with JSONUIProvider for state/actions
createRendererStandalone renderer component with state/actions/validation
renderToHtmlServer: spec to HTML string
renderToPlainTextServer: spec to plain-text string
schemaEmail element schema
standardComponentsPre-built component implementations
standardComponentDefinitionsCatalog definitions (Zod props)

Sub-path Exports

PathPurpose
@json-render/react-emailFull package
@json-render/react-email/serverSchema and catalog only (no React)
@json-render/react-email/catalogStandard component definitions and types
@json-render/react-email/renderRender functions only

Standard Components

All components accept a style prop (object) for inline styles. Use inline styles for email client compatibility; avoid external CSS.

Document structure

ComponentDescription
HtmlRoot wrapper (lang, dir). Children: Head, Body.
HeadEmail head section.
BodyBody wrapper; use style for background.

Layout

ComponentDescription
ContainerConstrain width (e.g. max-width 600px).
SectionGroup content; table-based for compatibility.
RowHorizontal row.
ColumnColumn in a Row; set width via style.

Content

ComponentDescription
HeadingHeading text (as: h1–h6).
TextBody text.
LinkHyperlink (text, href).
ButtonCTA link styled as button (text, href).
ImageImage from URL (src, alt, width, height).
HrHorizontal rule.

Utility

ComponentDescription
PreviewInbox preview text (inside Html).
MarkdownMarkdown content as email-safe HTML.

Email Best Practices

  • Keep width constrained (e.g. Container max-width 600px).
  • Use inline styles or React Email's style props; many clients strip <style> blocks.
  • Prefer table-based layout (Section, Row, Column) for broad client support.
  • Use absolute URLs for images; many clients block relative or cid: references in some contexts.
  • Test in multiple clients (Gmail, Outlook, Apple Mail); use a preview tool or Litmus-like service when possible.

按任务相关推荐

来自同一仓库

更多 Skills

全部 Skills