@json-render/react-email

JSON スペックを HTML またはプレーンテキストのメール出力に変換する React Email レンダラー。

クイックスタート

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);

スペック構造（エレメントツリー）

@json-render/react と同じフラットエレメントツリー：root キーと elements マップ。ルートは Html である必要があり、Html の子は Head と Body である必要があります。Body 内で Container（例：max-width 600px）を使用して、クライアント互換のレイアウトを実現します。

カタログとレジストリの作成

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 });

サーバーサイド レンダー API

関数	用途
renderToHtml(spec, options?)	スペックを HTML メール文字列にレンダー
renderToPlainText(spec, options?)	スペックをプレーンテキストメール文字列にレンダー

RenderOptions: registry、includeStandard（デフォルト true）、state（$state / $cond 用）。

表示と状態

visible 条件、$state、$cond、リピート（repeat.statePath）、および @json-render/react と同じ式構文をサポートしています。サーバーサイドでレンダーするときは、式が解決されるように RenderOptions で state を使用してください。

サーバーセーフインポート

React や @react-email/components なしでスキーマとカタログをインポート：

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

主要なエクスポート

エクスポート	用途
defineRegistry	カタログからタイプセーフなコンポーネントレジストリを作成
Renderer	ブラウザでスペックをレンダー（例：プレビュー）；JSONUIProvider で状態/アクションを使用
createRenderer	状態/アクション/検証を備えたスタンドアロンレンダラーコンポーネント
renderToHtml	サーバー：スペックから HTML 文字列へ
renderToPlainText	サーバー：スペックからプレーンテキスト文字列へ
schema	メールエレメントスキーマ
standardComponents	事前構築されたコンポーネント実装
standardComponentDefinitions	カタログ定義（Zod props）

サブパスエクスポート

パス	用途
@json-render/react-email	フルパッケージ
@json-render/react-email/server	スキーマとカタログのみ（React なし）
@json-render/react-email/catalog	標準コンポーネント定義と型
@json-render/react-email/render	レンダー関数のみ

標準コンポーネント

すべてのコンポーネントは style プロップ（オブジェクト）を使用インラインスタイルをサポートしています。メールクライアント互換性のためインラインスタイルを使用し、外部 CSS を避けてください。

ドキュメント構造

コンポーネント	説明
Html	ルートラッパー（lang、dir）。子要素：Head、Body。
Head	メールヘッドセクション。
Body	ボディラッパー；背景を style で設定。

レイアウト

コンポーネント	説明
Container	幅を制限（例：max-width 600px）。
Section	コンテンツをグループ化；互換性のためテーブルベース。
Row	水平行。
Column	Row 内の列；幅は style で設定。

コンテンツ

コンポーネント	説明
Heading	見出しテキスト（as: h1–h6）。
Text	本文テキスト。
Link	ハイパーリンク（text、href）。
Button	CTA リンク（ボタンスタイル）（text、href）。
Image	URL からの画像（src、alt、width、height）。
Hr	水平線。

ユーティリティ

コンポーネント	説明
Preview	インボックスプレビューテキスト（Html 内）。
Markdown	Markdown コンテンツをメール対応 HTML として。

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

• 幅を制限したまま保つ（例：Container max-width 600px）。
• インラインスタイルまたは React Email のスタイルプロップを使用；多くのクライアントが <style> ブロックを削除します。
• 幅広いクライアント対応のためテーブルベースレイアウト（Section、Row、Column）を優先。
• 画像には絶対 URL を使用；多くのクライアントが特定の状況で相対 URL または cid: 参照をブロックします。
• 複数のクライアント（Gmail、Outlook、Apple Mail）でテスト；可能であればプレビューツールまたは Litmus のようなサービスを使用してください。