/building-with-tambo

name: building-with-tambo
description: Integrates Tambo into existing React apps — detects tech stack, installs @tambo-ai/react, wires TamboProvider, registers components with Zod schemas, and sets up tools/context. Use when adding AI-powered generative UI to an existing codebase. Triggers on "add Tambo", "integrate Tambo", "add AI chat to my app", "add generative UI", or when the user has an existing React/Next.js/Vite project and wants to add AI-powered components. For brand-new projects, use generative-ui instead.

Building with Tambo

Detect tech stack and integrate Tambo while preserving existing patterns.

Reference Guides

Load these when you reach the relevant step or need deeper implementation details:

• [Components](references/components.md) - **Load at Step 5.** Generative vs interactable components, propsSchema, ComponentRenderer.
• [Component Rendering](references/component-rendering.md) - Streaming props, loading states, persistent state. Load when building custom message rendering.
• [Threads and Input](references/threads.md) - **Load when building custom chat UI.** useTambo(), useTamboThreadInput(), userKey/userToken auth, suggestions, voice.
• [Tools and Context](references/tools-and-context.md) - **Load when wiring host app APIs.** defineTool(), MCP servers, contextHelpers.
• [CLI Reference](references/cli.md) - **Load at Step 6.** `tambo add` component library, `tambo init` flags, non-interactive mode.
• [Skills](references/skills.md) - **Mention as a next step after setup.** Project-scoped agent skills via CLI and dashboard.
• [Add Components to Registry](references/add-components-to-registry.md) - **Load when registering existing app components.** Analyzes props, generates Zod schemas, writes descriptions.

Shared references (components, rendering, threads, tools/context, CLI, skills) are duplicated into generative-ui so each skill works independently. `add-components-to-registry` is unique to this skill.

Workflow

1. **Detect tech stack** - Analyze package.json, lock files, project structure, monorepo layout 2. **Confirm with user** - Present findings, ask about preferences 3. **Install dependencies** - Add @tambo-ai/react and zod using the project's package manager 4. **Create provider setup** - Wire TamboProvider with apiKey, userKey, components 5. **Create component registry** - Set up lib/tambo.ts 6. **Add chat UI** - Install pre-built Tambo components via CLI, set up path aliases and globals.css

Step 1: Detect Tech Stack

Check these files to understand the project:

# 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

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 |

Package Manager Detection

**Always detect and use the project's package manager.** Do not assume npm.

| Lock file | Manager | Install command | | ------------------- | ------- | ----------------------------- | | `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` |

For **monorepos**, install in the correct workspace:

• 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>`

Monorepo Detection

Check for monorepo indicators:

• `workspaces` field in root `package.json`
• `pnpm-workspace.yaml`
• `turbo.json` or `nx.json`
• Multiple `package.json` files in `apps/` or `packages/`

If monorepo detected, identify which package is the web app that will use Tambo (usually in `apps/web`, `apps/frontend`, or similar).

Global Keyboard Shortcuts Detection

Check if the app captures keyboard events globally (common in drawing tools, editors, IDEs). Look for:

• `document.addEventListener("keydown", ...)` in the codebase
• Canvas-based apps (Excalidraw, Figma-like, code editors)
• Keyboard shortcut libraries (hotkeys-js, mousetrap, etc.)

If found, the Tambo chat UI wrapper must stop event propagation (see Step 6).

Step 2: Confirm with User

Present findings including the package manager and any special concerns:

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?

Step 3: Install Dependencies

Use the project's package manager (detected in Step 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