generative-ui

ジェネレーティブ UI

Tambo でジェネレーティブ UI アプリを構築しましょう。自然言語から、リッチでインタラクティブな React コンポーネントを作成できます。

リファレンスガイド

ブートストラップの手順を超える、詳しい実装方法が必要な場合は、以下を読み込んでください。

• コンポーネント - カスタムコンポーネントの作成時に読み込んでください。 ジェネレーティブとインタラクタブルの違い、propsSchema、ComponentRenderer。
• コンポーネントのレンダリング - ストリーミング props、ローディング状態、永続状態。レンダリングをカスタマイズする場合に読み込んでください。
• スレッドと入力 - カスタムチャット UI の構築時に読み込んでください。 useTambo()、useTamboThreadInput()、userKey/userToken 認証、提案、音声。
• ツールとコンテキスト - ツールや MCP を追加する場合に読み込んでください。 defineTool()、MCP サーバー、contextHelpers。
• CLI リファレンス - tambo add コンポーネントを使う場合に読み込んでください。 コンポーネントライブラリ、非対話型フラグ、終了コード。
• スキル - セットアップ後の次のステップとして案内してください。 CLI とダッシュボードを使った、プロジェクト単位のエージェントスキル。

これらの共通リファレンスは、各スキルを単独で使えるように、building-with-tambo から複製されています。

1 プロンプトでのフロー

目標は、1 つのプロンプトでユーザーがゼロの状態からアプリを実行できるようにすることです。AskUserQuestion を使って、複数の質問を最初にまとめて行い、その後は中断せずにすべて実行してください。

ステップ 1：機密情報以外の希望をすべて確認する（AskUserQuestion を 1 回だけ呼び出す）

AskUserQuestion を使い、1 回の呼び出しで最大 3 つの質問をしてください。認証は後のステップで CLI が処理します。

質問 1：何を作りたいですか？

ユーザーに、どのようなアプリを作成するか尋ねてください。回答をもとに、作成するスターターコンポーネントを決定します。例：「ダッシュボード」「チャットボット」「データ可視化ツール」「タスク管理ツール」。ユーザーが最初のメッセージですでに希望を伝えている場合は、この質問を省略してください。

質問 2：フレームワーク

選択肢：

• Next.js（推奨）- App Router を備えたフルスタック React
• Vite - 高速で軽量な React セットアップ

質問 3：アプリ名

ユーザーにプロジェクトディレクトリの名前を選んでもらいます。デフォルトの候補は、作りたいものから考えてください（例：「my-dashboard」「my-chatbot」）。kebab-case（英字、数字、ハイフンのみ）を使います。「Sales Dashboard」のようなスラッグ形式でない名前をユーザーが指定した場合は、代わりに sales-dashboard を提案してください。

ユーザーがすでに回答を伝えている質問は省略してください。 たとえば、「analytics という名前の Next.js ダッシュボードアプリを作って」と言われた場合、フレームワーク、アプリの内容、名前はすでに分かっています。

ステップ 2：すべてを実行する（途中で止めない）

これらの手順を、ステップの間に確認を求めず、順番にすべて実行してください。コマンドが失敗した場合はフローを中断し、エラーを提示して、次にどうするかをユーザーに尋ねてください。後続の手順には進まないでください。

すべてのテンプレート（standard、vite、analytics、expo）には、チャット UI、TamboProvider の配線、コンポーネントレジストリ、スターターコンポーネントがすでに含まれています。チャット UI の追加やアプリの配線は不要です。スキャフォールドを作成し、API キーを設定して、サーバーを起動するだけです。

2a. プロジェクトをスキャフォールドする

Next.js（推奨）の場合：

npx tambo create-app <app-name> --template=standard --skip-tambo-init
cd <app-name>

Vite の場合：

npx tambo create-app <app-name> --template=vite --skip-tambo-init
cd <app-name>

--skip-tambo-init を使用してください。create-app は通常、対話形式で tambo init を実行しようとしますが、コーディングエージェントのような非対話型環境では動作しないためです。認証は次のステップで行います。

2b. Tambo の認証と初期化

npx tambo init --project-name=<app-name>

ブラウザーが開いて認証が行われ、ユーザーが認証を完了するまで（最長 15 分）ポーリングします。このコマンドの実行時は、長いタイムアウト（15 分以上）を設定してください。認証が完了すると、CLI がプロジェクトを作成し、フレームワークに適した環境変数（NEXT_PUBLIC_TAMBO_API_KEY、VITE_TAMBO_API_KEY など）を使って、.env.local に API キーを書き込みます。

重要： ユーザーに API キーを手動で貼り付けるよう求めてはいけません。必ず CLI の認証フローを使用してください。

2c. カスタムのスターターコンポーネントを作成する

テンプレートには基本的なコンポーネントが含まれていますが、ユーザーが作りたいものに合わせて1～2個のコンポーネントを追加してください。汎用的な例は使わないでください。

• ダッシュボードアプリ → StatsCard、DataTable
• チャットボット → Markdown に対応した BotResponse
• データビジュアライゼーション → データを設定できる Chart
• タスクマネージャー → TaskCard、TaskBoard
• 汎用／不明確 → ContentCard

各コンポーネントには、次のものが必要です。

1. すべてのフィールドに .describe() を指定した Zod スキーマ
2. React コンポーネント本体
3. 既存のコンポーネントレジストリへの登録（lib/tambo.ts — 既存の components 配列に追加し、置き換えないでください）

スキーマの制約 — Tambo は実行時に無効なスキーマを拒否します。

• z.record() は使用しないでください — 動的なキーを持つオブジェクト型は、配列やオブジェクト内にネストされている場合も含め、スキーマのどこでもサポートされていません。代わりに、明示的な名前付きキーを持つ z.object() を使用してください。
• z.map() や z.set() は使用しないでください — 代わりに配列やオブジェクトを使用してください。
• 行などの表形式データには、明示的な列キーを指定した z.array(z.object({ col1: z.string(), col2: z.number() })) を使用してください。z.array(z.record(z.string(), z.unknown())) は使用しないでください。

生成コンポーネントの React ベストプラクティス：

• リスト（.map()）をレンダリングする際は、必ず一意の key プロパティを追加してください。配列のインデックスではなく、データ内の一意なフィールド（id など）を使用してください。
• 配列の各要素のスキーマには id フィールド（例：z.string().describe("Unique identifier")）を含め、常に安定したキーを使えるようにしてください。

例：

// src/components/StatsCard.tsx
import { z } from "zod/v4";

export const StatsCardSchema = z.object({
  title: z.string().describe("Metric name"),
  value: z.number().describe("Current value"),
  change: z.number().optional().describe("Percent change from previous period"),
  trend: z.enum(["up", "down", "flat"]).optional().describe("Trend direction"),
});

type StatsCardProps = z.infer<typeof StatsCardSchema>;

export function StatsCard({
  title,
  value,
  change,
  trend = "flat",
}: StatsCardProps) {
  // ... implementation with Tailwind styling
}

次に、lib/tambo.ts の既存のレジストリに追加します。

// Add to the existing components array — don't replace what's already there
// Next.js: import { StatsCard, StatsCardSchema } from "@/components/StatsCard";
// Vite: import { StatsCard, StatsCardSchema } from "../components/StatsCard";
import { StatsCard, StatsCardSchema } from "@/components/StatsCard";

// ... existing components ...
{
  name: "StatsCard",
  component: StatsCard,
  description: "Displays a metric with value and trend. Use when user asks about stats, metrics, or KPIs.",
  propsSchema: StatsCardSchema,
},

2d. 開発サーバーを起動する

すべてのコード変更（スキャフォールディング、初期化、コンポーネントの作成、レジストリの更新）が完了してから、開発サーバーを起動してください。

npm run dev

ユーザーがすぐにアプリを確認できるよう、バックグラウンドで実行してください。

ステップ 3：概要

すべてが起動したら、簡潔な概要を伝えてください。

• 設定した内容
• 作成したコンポーネントとその機能
• アプリの実行 URL（Next.js では通常 http://localhost:3000、Vite では http://localhost:5173）
• 認証をスキップした場合は、認証するために npx tambo init を実行するよう、一度だけ案内してください
• 最初に試す内容の提案（例：「月間売上の統計カードを表示するよう頼んでみてください」）

テクノロジースタックのリファレンス

推奨スタック（デフォルト）

Next.js 14+ (App Router)
├── TypeScript
├── Tailwind CSS
├── Zod (for schemas)
└── @tambo-ai/react

npx tambo create-app my-app --template=standard

Vite スタック

Vite + React
├── TypeScript
├── Tailwind CSS
├── Zod
└── @tambo-ai/react

最小構成スタック（Tailwind なし）

Vite + React
├── TypeScript
├── Plain CSS
├── Zod
└── @tambo-ai/react

コンポーネントレジストリのパターン

すべての生成コンポーネントを登録する必要があります。

import { TamboComponent } from "@tambo-ai/react";
import { ComponentName, ComponentNameSchema } from "@/components/ComponentName";

export const components: TamboComponent[] = [
  {
    name: "ComponentName",
    component: ComponentName,
    description: "What it does. When to use it.",
    propsSchema: ComponentNameSchema,
  },
];

主なルール：

• propsSchema：すべてのフィールドに .describe() を指定した Zod オブジェクトです。AI が渡す値を判断するために使用されます。
• description：このコンポーネントを使うタイミングを AI に伝えます。具体的なトリガーフレーズを指定してください。
• ストリーミング：プロパティは段階的に届くため、未定義の値を適切に処理してください（オプションのフィールドやデフォルト値を使用）。

チャット UI の追加（任意）

テンプレートにはすでにチャット UI が含まれています。テンプレートに用意されているもの以外に追加の UI プリミティブが必要な場合にのみ、次を追加してください。

npx tambo add message-thread-full --yes    # Complete chat interface
npx tambo add control-bar --yes            # Controls and actions
npx tambo add thread-history --yes         # Conversation history sidebar

サポート対象のテクノロジー

テクノロジー	サポートレベル	備考
Next.js 14+	フル対応	推奨。App Router を優先
Vite	フル対応	SPA に最適
Create React App	部分対応	動作しますが、CRA は非推奨です
Remix	部分対応	クライアントコンポーネントで動作します
TypeScript	フル対応	強く推奨します
JavaScript	フル対応	動作しますが、型安全性は低くなります
Tailwind CSS	フル対応	CLI コンポーネントのデフォルトです
Plain CSS	フル対応	コンポーネントのスタイルを独自に設定する必要があります
CSS Modules	フル対応	サポートされています
Zod	必須	すべてのスキーマで使用します

動作確認

以下の手順で、アプリが動作することをユーザーに確認してもらいます。

1. ブラウザーでアプリの URL を開く
2. 登録済みコンポーネントのいずれかを呼び出すプロンプトを入力する（例：「月次売上の統計カードを表示して」）
3. AI が生成した props を使ってコンポーネントがレンダリングされることを確認する

動作しない場合：

• レジストリにコンポーネントが含まれているか確認する
• 説明がプロンプトと一致しているか確認する
• 開発サーバーのコンソールにエラーがないか確認する

バグとフィードバックの報告

ユーザーをサポートする際に以下のいずれかに遭遇した場合は、GitHub issue の提出を提案してください。

• @tambo-ai/react、@tambo-ai/client、または tambo CLI のバグ
• 実際の動作と矛盾するドキュメント
• このスキルの説明が不足している、または誤解を招く

Issue テンプレート

tambo-ai/tambo の issue を作成する際は、次のテンプレートを使用してください。

**Title:** [Short description of the problem]

**Expected behavior**
What should happen.

**Actual behavior**
What happens instead, including any error messages or stack traces.

**Repro steps**

1. Run `npx tambo create-app ...` (or whatever command)
2. Add this code:

```tsx
// minimal code that reproduces the issue
```

3. Observe the error

**Environment**

- `@tambo-ai/react` version:
- `@tambo-ai/client` version:
- Framework (Next.js / Vite / CRA) and version:
- Node.js version:
- OS:

**Additional context**
Link to relevant docs or skill file path if applicable.

セキュリティ： issue にログやコードスニペットを含める前に、API キー、トークン、顧客データをすべて削除してください。

ユーザーへの Issue の提案

Tambo のバグと思われる問題が発生した場合は、次のように伝えてください。

これは @tambo-ai/react のバグのようです。再現手順と環境の詳細を添えて、tambo-ai/tambo に GitHub issue を作成しましょうか？

提出する前に、必ずユーザーの確認を待ってください。