build-with-tambo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build with Tambo

基于Tambo开发

Detect tech stack and integrate Tambo while preserving existing patterns.

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

Reference Guides

参考指南

Use these guides when you need deeper implementation details for a specific area:

Components - Create and register Tambo components (generative and interactable).
Component Rendering - Handle streaming props, loading states, and persistent component state.
Threads and Input - Manage conversations, suggestions, voice input, image attachments, and thread switching.
Tools and Context - Add custom tools, MCP servers, context helpers, and resources.
CLI Reference - Use
```
tambo init
```
,
```
tambo add
```
, and
```
create-app
```
with non-interactive flags and exit codes.
Add Components to Registry - Convert existing React components into Tambo-ready registrations with schemas and descriptions.

These references are duplicated across both skills so each skill works independently.

当你需要特定领域的深度实现细节时，可以参考这些指南：

Components - 创建并注册Tambo组件（生成式组件和可交互组件）。
Component Rendering - 处理流式属性、加载状态和持久化组件状态。
Threads and Input - 管理会话、建议、语音输入、图片附件和线程切换。
Tools and Context - 添加自定义工具、MCP服务器、上下文助手和资源。
CLI Reference - 搭配非交互标志和退出码使用
```
tambo init
```
、
```
tambo add
```
和
```
create-app
```
命令。
Add Components to Registry - 将现有React组件转换为支持Tambo的注册项，包含schema和描述信息。

这些参考文档在两个Skill中都有副本，因此每个Skill都可以独立运行。

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` ，存在对应配置文件
Plain 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

// 跳过--yes标志，在添加组件时自定义样式
npx tambo add message-thread-full

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

提示时选择「CSS Modules」或「Plain CSS」

undefined

undefined

Existing Validation Library?

已有其他校验库？

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)

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

仅为Tambo schema新增Zod依赖（推荐，额外体积很小）
转换schema（工作量更大，不推荐）

Monorepo?

Monorepo项目？

Run commands from the package that will use Tambo:

bash

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

在需要使用Tambo的子包目录下运行命令：

bash

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

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`

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`

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

配置完成后，创建简单测试用例验证是否生效：

tsx

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

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

Reporting Bugs & Feedback

上报Bug与反馈

If you encounter any of these while helping a user, suggest filing a GitHub issue:

A bug in
```
@tambo-ai/react
```
,
```
@tambo-ai/client
```
, or the
```
tambo
```
CLI
Documentation that contradicts actual behavior
Missing or misleading instructions in this skill

如果你在协助用户时遇到以下问题，建议提交GitHub Issue：

```
@tambo-ai/react
```
、
```
@tambo-ai/client
```
或
```
tambo
```
CLI存在Bug
文档与实际运行行为不符
本Skill中的说明缺失或有误导性

Issue Template

Issue模板

Use this template when drafting an issue for

tambo-ai/tambo

markdown

**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.

Security: Redact API keys, tokens, and any customer data before including logs or code snippets in the issue.

为

tambo-ai/tambo

仓库提交Issue时使用以下模板：

markdown

**标题：**[问题的简短描述]

**预期行为**
描述应该发生的结果。

**实际行为**
描述实际发生的结果，包含所有错误信息或堆栈跟踪。

**复现步骤**

1. 运行`npx tambo create-app ...`（或其他触发命令）
2. 添加以下代码：

```tsx
// 可复现问题的最小代码示例
```

3. 观察报错

**环境信息**

- `@tambo-ai/react`版本：
- `@tambo-ai/client`版本：
- 框架（Next.js / Vite / CRA）及版本：
- Node.js版本：
- 操作系统：

**额外上下文**
如有必要，附上相关文档链接或Skill文件路径。

**安全提示：**在Issue中提交日志或代码片段前，请脱敏API密钥、令牌和所有客户数据。

Suggesting an Issue to the User

向用户提议提交Issue

When you hit a problem that looks like a Tambo bug, say something like:

This looks like a bug in
@tambo-ai/react
. Want me to open a GitHub issue on
tambo-ai/tambo
with the repro steps and environment details?

Always wait for the user to confirm before filing.

当你遇到疑似Tambo Bug的问题时，可以这么说：

这看起来是
@tambo-ai/react
的一个Bug。需要我帮你在
tambo-ai/tambo
仓库提交包含复现步骤和环境信息的GitHub Issue吗？

提交前请务必获得用户确认。