react-email

# @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 | Function | Purpose | |----------|---------| | `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 | Export | Purpose | |--------|---------| | `defineRegistry` | Create type-safe component registry from catalog | | `Renderer` | Render spec in browser (e.g. preview); use with `JSONUIProvider` for state/actions | | `createRenderer` | Standalone renderer component with state/actions/validation | | `renderToHtml` | Server: spec to HTML string | | `renderToPlainText` | Server: spec to plain-text string | | `schema` | Email element schema | | `standardComponents` | Pre-built component implementations | | `standardComponentDefinitions` | Catalog definitions (Zod props) | ## Sub-path Exports | Path | Purpose | |------|---------| | `@json-render/react-email` | Full package | | `@json-render/react-email/server` | Schema and catalog only (no React) | | `@json-render/react-email/catalog` | Standard component definitions and types | | `@json-render/react-email/render` | Render 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 | Component | Description | |-----------|-------------| | `Html` | Root wrapper (lang, dir). Children: Head, Body. | | `Head` | Email head section. | | `Body` | Body wrapper; use `style` for background. | ### Layout | Component | Description | |-----------|-------------| | `Container` | Constrain width (e.g. max-width 600px). | | `Section` | Group content; table-based for compatibility. | | `Row` | Horizontal row. | | `Column` | Column in a Row; set width via style. | ### Content | Component | Description | |-----------|-------------| | `Heading` | Heading text (as: h1–h6). | | `Text` | Body text. | | `Link` | Hyperlink (text, href). | | `Button` | CTA link styled as button (text, href). | | `Image` | Image from URL (src, alt, width, height). | | `Hr` | Horizontal rule. | ### Utility | Component | Description | |-----------|-------------| | `Preview` | Inbox preview text (inside Html). | | `Markdown` | Markdown 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.