add-to-existing-project

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add Tambo to Existing Project

为现有项目添加Tambo

Detect tech stack and integrate Tambo while preserving existing patterns.

检测技术栈并在保留现有模式的前提下集成Tambo。

Workflow

工作流程

Detect tech stack - Analyze package.json and project structure
Confirm with user - Present findings, ask about preferences
Install dependencies - Add @tambo-ai/react and peer deps
Create provider setup - Adapt to existing patterns
Register first component - Demonstrate with existing component

检测技术栈 - 分析package.json和项目结构
与用户确认 - 展示检测结果，询问用户偏好
安装依赖 - 添加@tambo-ai/react及对等依赖
创建Provider配置 - 适配现有项目模式
注册首个组件 - 结合现有组件进行演示

Step 1: Detect Tech Stack

步骤1：检测技术栈

Check these files to understand the project:

bash

undefined

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

bash

undefined

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

undefined

package.json # 依赖和脚本 tsconfig.json # TypeScript配置 next.config.* # Next.js配置 vite.config.* # Vite配置 tailwind.config.* # Tailwind CSS配置 postcss.config.* # PostCSS配置 src/index.* 或 app/ # 入口文件

undefined

Detection Checklist

检测清单

Technology	Detection
Next.js	`next` in dependencies, `next.config.*` exists
Vite	`vite` in devDependencies, `vite.config.*` exists
Create React App	`react-scripts` in dependencies
TypeScript	`typescript` in deps, `tsconfig.json` exists
Tailwind	`tailwindcss` in deps, config file exists
Plain CSS	No Tailwind, CSS files in src/
Zod	`zod` in dependencies
Other validation	`yup` , `joi` , `superstruct` in deps

技术栈	检测方式
Next.js	依赖中存在 `next` ，且存在 `next.config.*` 文件
Vite	开发依赖中存在 `vite` ，且存在 `vite.config.*` 文件
Create React App	依赖中存在 `react-scripts`
TypeScript	依赖中存在 `typescript` ，且存在 `tsconfig.json` 文件
Tailwind	依赖中存在 `tailwindcss` ，且存在配置文件
纯CSS	无Tailwind，src/目录下有CSS文件
Zod	依赖中存在 `zod`
其他校验库	依赖中存在 `yup` 、 `joi` 、 `superstruct`

Step 2: Confirm with User

步骤2：与用户确认

Present findings and ask:

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?

展示检测结果并询问：

我检测到你的项目使用：
- 框架：Next.js 14（App Router）
- 样式：Tailwind CSS
- 校验库：未使用Zod（需要添加）
- TypeScript：已使用

请问我应该：
1. 按照以上设置安装Tambo？
2. 为Tambo组件使用纯CSS替代Tailwind？
3. 其他操作？

Step 3: Install Dependencies

步骤3：安装依赖

bash

undefined

bash

undefined

Core (always required)

核心依赖（必须安装）

npm install @tambo-ai/react

If no Zod installed

如果未安装Zod

npm install zod

undefined

npm install zod

undefined

Step 4: Create Provider Setup

步骤4：创建Provider配置

Next.js App Router

tsx

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

tsx

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

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

tsx

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

tsx

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

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

Next.js Pages Router

tsx

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

tsx

// 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

tsx

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

tsx

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

Step 5: Create Component Registry

步骤5：创建组件注册表

tsx

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

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

tsx

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

export const components: TamboComponent[] = [
  // 组件将在此处注册
];

Adapting to Existing Patterns

适配现有项目模式

No Tailwind? Use Plain CSS

未使用Tailwind？使用纯CSS

If project uses plain CSS or CSS modules, Tambo components can be styled differently:

tsx

// Skip --yes flag to customize styling during add
npx tambo add message-thread-full

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

tsx

undefined

Select "CSS Modules" or "Plain CSS" when prompted

添加时跳过--yes标志以自定义样式

undefined

npx tambo add message-thread-full

Existing Validation Library?

提示时选择“CSS Modules”或“Plain CSS”

If using Yup/Joi instead of Zod, user can either:

Add Zod just for Tambo schemas (recommended - small addition)
Convert schemas (more work, not recommended)

undefined

Monorepo?

已使用其他校验库？

Run commands from the package that will use Tambo:

bash

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

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

仅为Tambo模式添加Zod（推荐 - 仅需少量改动）
转换现有模式（工作量大，不推荐）

Environment Variables

单体仓库？

npx tambo init --api-key=sk_...

automatically creates

.env.local

with the correct env var for your framework.

If manual setup is needed (monorepo, read-only filesystem), add the appropriate variable:

Framework	Variable
Next.js	`NEXT_PUBLIC_TAMBO_API_KEY`
Vite	`VITE_TAMBO_API_KEY`
CRA	`REACT_APP_TAMBO_API_KEY`

从将使用Tambo的包目录中执行命令：

bash

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

Verification

环境变量

After setup, verify by creating a simple test:

tsx

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

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

npx tambo init --api-key=sk_...

会自动为你的框架创建包含正确环境变量的

.env.local

文件。

如果需要手动配置（如单体仓库、只读文件系统），请添加对应的环境变量：

框架	环境变量
Next.js	`NEXT_PUBLIC_TAMBO_API_KEY`
Vite	`VITE_TAMBO_API_KEY`
CRA	`REACT_APP_TAMBO_API_KEY`

—

验证

—

配置完成后，可通过创建简单测试来验证：

tsx

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

function TestComponent() {
  const { thread, isIdle } = useTambo();
  console.log("Tambo已连接:", isIdle);
  return <div>Tambo配置完成！</div>;
}