add-to-existing-project

将 Tambo 添加到现有项目

检测技术栈并集成 Tambo，同时保留现有模式。

工作流

1. 检测技术栈 - 分析 package.json 和项目结构
2. 与用户确认 - 展示检测结果并询问偏好
3. 安装依赖 - 添加 @tambo-ai/react 和同级依赖
4. 创建 Provider 设置 - 适配现有模式
5. 注册第一个组件 - 使用现有组件进行演示

步骤 1：检测技术栈

检查以下文件以了解项目：

# Key files to read
package.json           # Dependencies and scripts
tsconfig.json          # TypeScript config
next.config.*          # Next.js
vite.config.*          # Vite
tailwind.config.*      # Tailwind CSS
postcss.config.*       # PostCSS
src/index.* or app/    # Entry points

检测清单

技术	检测方式
Next.js	依赖中包含 next，且存在 next.config.*
Vite	devDependencies 中包含 vite，且存在 vite.config.*
Create React App	依赖中包含 react-scripts
TypeScript	依赖中包含 typescript，且存在 tsconfig.json
Tailwind	依赖中包含 tailwindcss，且存在配置文件
纯 CSS	不使用 Tailwind，src/ 中存在 CSS 文件
Zod	依赖中包含 zod
其他验证库	deps 中包含 yup、joi、superstruct

步骤 2：与用户确认

展示检测结果并询问：

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

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

步骤 3：安装依赖

# Core (always required)
npm install @tambo-ai/react

# If no Zod installed
npm install zod

步骤 4：创建 Provider 设置

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}
      components={components}
    >
      {children}
    </TamboProvider>
  );
}

// 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}
      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}
    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
];

适配现有模式

没有 Tailwind？使用纯 CSS

如果项目使用纯 CSS 或 CSS 模块，可以采用其他方式为 Tambo 组件设置样式：

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

已有验证库？

如果使用 Yup/Joi 而非 Zod，用户可以选择：

1. 仅为 Tambo Schema 添加 Zod（推荐，改动很小）
2. 转换 Schema（工作量较大，不推荐）

Monorepo？

从将使用 Tambo 的 package 中运行命令：

cd packages/web
npx tambo init --api-key=sk_...

环境变量

npx tambo init --api-key=sk_... 会自动创建 .env.local，并根据你的框架配置正确的环境变量。

如果需要手动设置（例如 Monorepo、文件系统只读），请添加相应变量：

框架	变量
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>;
}