building-with-tambo

Tambo を使った開発

技術スタックを検出し、既存のパターンを維持しながら Tambo を統合します。

リファレンスガイド

該当する手順に進んだときや、実装の詳細を確認する必要があるときに読み込んでください。

• コンポーネント - ステップ 5 で読み込みます。 生成型コンポーネントと対話型コンポーネント、propsSchema、ComponentRenderer。
• コンポーネントのレンダリング - ストリーミング props、読み込み状態、永続化された状態。カスタムメッセージのレンダリングを構築するときに読み込みます。
• スレッドと入力 - カスタムチャット UI を構築するときに読み込みます。 useTambo()、useTamboThreadInput()、userKey/userToken 認証、提案、音声。
• ツールとコンテキスト - ホストアプリの API を接続するときに読み込みます。 defineTool()、MCP サーバー、contextHelpers。
• CLI リファレンス - ステップ 6 で読み込みます。 コンポーネントライブラリの tambo add、tambo init のフラグ、非対話型モード。
• スキル - セットアップ後の次のステップとして紹介してください。 CLI とダッシュボードを使った、プロジェクト単位のエージェントスキル。
• レジストリへのコンポーネントの追加 - 既存のアプリコンポーネントを登録するときに読み込みます。 props を解析し、Zod スキーマを生成して、説明を記述します。

共通のリファレンス（components、rendering、threads、tools/context、CLI、skills）は、各スキルを単独で利用できるよう、generative-ui に複製されています。add-components-to-registry はこのスキル固有のリファレンスです。

ワークフロー

1. 技術スタックを検出する - package.json、ロックファイル、プロジェクト構成、モノレポの構成を分析します
2. ユーザーに確認する - 検出結果を提示し、希望を尋ねます
3. 依存関係をインストールする - プロジェクトのパッケージマネージャーを使って @tambo-ai/react と zod を追加します
4. プロバイダーを設定する - apiKey、userKey、components を指定して TamboProvider を接続します
5. コンポーネントレジストリを作成する - lib/tambo.ts を設定します
6. チャット UI を追加する - CLI でビルド済みの Tambo コンポーネントをインストールし、パスエイリアスと globals.css を設定します

ステップ 1：技術スタックを検出する

プロジェクトを把握するため、次のファイルを確認します。

# Key files to read
package.json           # Dependencies, scripts, AND package manager
tsconfig.json          # TypeScript config, path aliases
next.config.*          # Next.js
vite.config.*          # Vite
tailwind.config.*      # Tailwind CSS
postcss.config.*       # PostCSS
src/index.* or app/    # Entry points
yarn.lock / pnpm-lock.yaml / package-lock.json  # Which package manager

検出チェックリスト

技術	検出方法
Next.js	依存関係に next があり、next.config.* が存在する
Vite	devDependencies に vite があり、vite.config.* が存在する
Create React App	依存関係に react-scripts がある
TypeScript	deps に typescript があり、tsconfig.json が存在する
Tailwind	deps に tailwindcss があり、設定ファイルが存在する
Plain CSS	Tailwind がなく、src/ に CSS ファイルがある
Zod	依存関係に zod がある
その他のバリデーション	deps に yup、joi、superstruct がある

パッケージマネージャーの検出

必ずプロジェクトのパッケージマネージャーを検出して使用してください。 npm だと決めつけないでください。

ロックファイル	マネージャー	インストールコマンド
package-lock.json	npm	npm install @tambo-ai/react
yarn.lock	Yarn	yarn add @tambo-ai/react
pnpm-lock.yaml	pnpm	pnpm add @tambo-ai/react

モノレポでは、適切なワークスペースにインストールします。

• Yarn: yarn workspace <app-name> add @tambo-ai/react
• pnpm: pnpm --filter <app-name> add @tambo-ai/react
• npm: npm install @tambo-ai/react -w <app-name>

モノレポの検出

モノレポを示す次の項目を確認します。

• ルートの package.json にある workspaces フィールド
• pnpm-workspace.yaml
• turbo.json または nx.json
• apps/ または packages/ 内に複数の package.json がある

モノレポが検出された場合は、Tambo を使用する Web アプリのパッケージを特定します（通常は apps/web、apps/frontend、または類似の場所にあります）。

グローバルキーボードショートカットの検出

アプリがキーボードイベントをグローバルにキャプチャしているかどうかを確認します（描画ツール、エディタ、IDE でよく見られます）。次の点を探します：

• コードベース内の document.addEventListener("keydown", ...)
• Canvas ベースのアプリ（Excalidraw、Figma ライクなもの、コードエディタ）
• キーボードショートカットライブラリ（hotkeys-js、mousetrap など）

見つかった場合、Tambo チャット UI のラッパーはイベントの伝播を停止する必要があります（ステップ 6 を参照）。

ステップ 2: ユーザーへの確認

パッケージマネージャーや特別な懸念事項を含む調査結果を提示します：

I detected your project uses:
- Framework: Next.js 14 (App Router)
- Package manager: Yarn
- Styling: Tailwind CSS
- Validation: No Zod (will need to add)
- TypeScript: Yes
- Monorepo: No
- Global keyboard shortcuts: No

Should I:
1. Install Tambo with these settings?
2. Use plain CSS instead of Tailwind for Tambo components?
3. Something else?

ステップ 3: 依存関係のインストール

プロジェクトのパッケージマネージャーを使用します（ステップ 1 で検出）：

# npm
npm install @tambo-ai/react
npm install zod  # if no Zod installed

# yarn
yarn add @tambo-ai/react
yarn add zod

# pnpm
pnpm add @tambo-ai/react
pnpm add zod

# Monorepo (install in the correct workspace)
yarn workspace <app-name> add @tambo-ai/react zod
pnpm --filter <app-name> add @tambo-ai/react zod
npm install @tambo-ai/react zod -w <app-name>

ステップ 4: プロバイダーのセットアップを作成

Next.js App Router

// app/providers.tsx
"use client";
import { TamboProvider } from "@tambo-ai/react";
import { components } from "@/lib/tambo";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
      userKey="default-user"
      components={components}
    >
      {children}
    </TamboProvider>
  );
}

重要: 認証には userKey が必須です。これがないと、実行時に「authentication is not ready」というエラーでメッセージ送信が失敗します。注意: userKey は TypeScript ではオプションとして型付けられている（userKey?: string）ため、コンパイラはこれを検出できません — 失敗は純粋に実行時のものです。本番環境では、実際のユーザー識別子（例: セッション ID、認証システムのユーザー ID）を使用してください。開発/デモでは、"default-user" のような静的な文字列で動作します。

// app/layout.tsx
import { Providers } from "./providers";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Next.js Pages Router

// pages/_app.tsx
import { TamboProvider } from "@tambo-ai/react";
import { components } from "@/lib/tambo";

export default function App({ Component, pageProps }) {
  return (
    <TamboProvider
      apiKey={process.env.NEXT_PUBLIC_TAMBO_API_KEY}
      userKey="default-user"
      components={components}
    >
      <Component {...pageProps} />
    </TamboProvider>
  );
}

Vite / CRA

// src/main.tsx
import { TamboProvider } from "@tambo-ai/react";
import { components } from "./lib/tambo";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <TamboProvider
    apiKey={import.meta.env.VITE_TAMBO_API_KEY}
    userKey="default-user"
    components={components}
  >
    <App />
  </TamboProvider>,
);

ステップ 5: コンポーネントレジストリを作成

// lib/tambo.ts (or src/lib/tambo.ts)
import { TamboComponent } from "@tambo-ai/react";

export const components: TamboComponent[] = [
  // Components will be registered here
];

ステップ 6: チャット UI を追加

アプリに適したチャットレイアウトを選択します：

コンポーネント	最適な用途	レンダリング方法
message-thread-collapsible	既存の UI の上にオーバーレイする場合（描画ツール、シンプルなアプリ）	固定位置のフローティングパネル、右下隅、開閉を切り替え
message-thread-panel	サイドバーレイアウトのアプリ（ダッシュボード、管理パネル、SaaS アプリ）	スレッド履歴付きのサイドパネル、サイズ変更可能
message-thread-full	専用のチャットページまたは全画面のチャット体験	すべての機能を備えた全高スレッド

アプリのレイアウトに基づいて選択します。サイドバーやダッシュボードのレイアウトがある場合は panel を使用します。チャットが既存のコンテンツの上に浮かぶ場合は collapsible を使用します。ページ全体がチャットの場合は full を使用します。

npx tambo add message-thread-panel --yes
# Or: npx tambo add message-thread-collapsible --yes
# Or: npx tambo add message-thread-full --yes

# With other package managers:
# yarn dlx tambo add <component> --yes
# pnpm dlx tambo add <component> --yes

tambo add の後、セットアップを完了します：

1. CSS セットアップ — tambo add は Tailwind ディレクティブと CSS 変数をプロジェクトの CSS エントリファイルに追加します。変更されるファイルはフレームワークによって異なります：

   • Next.js: app/globals.css（または src/app/globals.css） — デフォルトでレイアウトにすでにインポートされています。
   • Vite: src/index.css（または index.css） — デフォルトで main.tsx にすでにインポートされています。

   エントリファイルがすでに CSS ファイルをインポートしている場合、tambo add はそのファイルをそのまま変更します。新しいインポートは不要です。

2. パスエイリアス — Tambo コンポーネントは @/ インポートを使用します。プロジェクトの tsconfig の paths にすでに @/* があるか確認します。create-next-app で作成された多くの Next.js プロジェクトにはこれがありますが、すべてではありません（例: Cal.com は代わりに ~/* と @components/* を使用しています）。

   @/* がない場合は、アプリの tsconfig（tsconfig.app.json がある場合はそれ、なければ tsconfig.json）に追加します：

   {
     "compilerOptions": {
       "paths": {
         "@/*": ["./src/*"]
       }
     }
   }
   

   プロジェクトに src/ ディレクトリがなく、コンポーネントがプロジェクトルートに配置される場合は、["./src/*"] の代わりに ["./*"] を使用します。tambo add がコンポーネントをどこに配置したかを確認して、正しいパスを判断します。

   Vite プロジェクトの場合は、vite.config.ts にもエイリアスを追加します：

   // vite.config.ts
   import path from "path";
   
   export default defineConfig({
     resolve: {
       alias: {
         "@": path.resolve(__dirname, "src"),
       },
     },
   });
   

キーボードイベントの分離

グローバルキーボードショートカットを持つアプリ（描画ツール、エディタ、ターミナルライクなアプリ）にとって重要です。これがないと、Tambo チャット入力でのタイピングがホストアプリのショートカットをトリガーします。

Tambo チャット UI をキーボードイベントの伝播を停止する div でラップします：

<div
  onKeyDown={(e) => e.stopPropagation()}
  onKeyUp={(e) => e.stopPropagation()}
>
  {/* Use whichever component you installed */}
  <MessageThreadCollapsible />{" "}
  {/* or <MessageThreadPanel /> or <MessageThreadFull /> */}
</div>

全画面アプリの Z-Index

全画面キャンバスやオーバーレイを使うアプリでは、Tambo チャットより前面に表示されることがあります。MessageThreadCollapsible コンポーネントは position: fixed を使用しますが、ホストアプリのキャンバスのスタッキングコンテキストのほうが高い場合があります。すべてより前面に表示される固定コンテナで囲みます。

<div
  style={{ position: "fixed", inset: 0, zIndex: 9999, pointerEvents: "none" }}
>
  <div style={{ pointerEvents: "auto" }}>
    {/* Use whichever component you installed */}
    <MessageThreadCollapsible />{" "}
    {/* or <MessageThreadPanel /> or <MessageThreadFull /> */}
  </div>
</div>

外側の div によってキャンバスより上位のスタッキングコンテキストが作られ、pointerEvents: none/auto によってチャットパネルだけがクリック可能になり、画面の残りの部分ではクリックがキャンバスに透過します。

キーボード操作の分離と z-index は、1 つのラッパーにまとめられます。

既存のパターンへの適応

Tailwind がない場合：プレーン CSS を使用する

プロジェクトで Tailwind を使用していない場合、tambo add は既存のスタイルと並行して PostCSS 経由で Tailwind v4 をインストールします。これは追加されるだけで、既存の CSS／SCSS に影響はありません。Tambo コンポーネントでは Tailwind を使用しますが、アプリの残りの部分では引き続き既存のスタイルが使用されます。

Tailwind を一切使いたくない場合は、次のようにします。

# Skip --yes flag to customize styling during add
npx tambo add message-thread-full
# Select "CSS Modules" or "Plain CSS" when prompted

既存のバリデーションライブラリを使用している場合

Zod の代わりに Yup／Joi を使用している場合、次のいずれかを選べます。

1. Tambo のスキーマ専用に Zod を追加する（推奨。追加は最小限です）
2. スキーマを変換する（手間がかかるため、非推奨です）

モノレポの場合

モノレポのルートではなく、ウェブアプリのパッケージからコマンドを実行します。

ウェブアプリのディレクトリから npx tambo init --project-name=<app-name> を実行します。認証のためにブラウザーが開き、ユーザーが認証を完了するまでポーリングします（最長 15 分）。長めのタイムアウトを設定してください。認証が完了すると、CLI がプロジェクトを作成し、API キーを .env.local に書き込みます。

モノレポでの注意点：

• 環境変数：tambo init は現在のディレクトリに .env.local を作成します。Vite は envDir から環境変数を読み込みます（vite.config.* を確認してください）。環境変数ファイルが Vite の読み込み先にあることを確認してください。
• 依存関係のホイスト：一部のパッケージマネージャーは、依存関係をモノレポのルートにホイストします。Vite が Tambo の依存関係を解決できない場合は、ルートレベルにもインストールしてください（例：yarn add -W @tambo-ai/react）。
• パスエイリアス：Vite は vite.config.* のあるディレクトリを基準に解決します。@/ エイリアスが、モノレポのルートではなく、ワークスペース内の正しい src/ ディレクトリを参照していることを確認してください。

環境変数

npx tambo init --project-name=<name> を実行するとブラウザーが開き、ユーザーが認証を完了するまでポーリングします（最長 15 分）。長めのタイムアウトを設定してください。認証が完了すると、プロジェクトを作成して .env.local に書き込みます。

手動での設定が必要な場合（モノレポ、読み取り専用ファイルシステムなど）は、該当する変数を追加します。

フレームワーク	変数
Next.js	NEXT_PUBLIC_TAMBO_API_KEY
Vite	VITE_TAMBO_API_KEY
CRA	REACT_APP_TAMBO_API_KEY

検証

セットアップ後、簡単なテストを作成して確認します。

import { useTambo } from "@tambo-ai/react";

function TestComponent() {
  const { thread, isIdle } = useTambo();
  console.log("Tambo connected:", isIdle);
  return <div>Tambo is set up!</div>;
}

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

ユーザーをサポートする際に次のいずれかに遭遇した場合は、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 を作成しましょうか？

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