generative-ui

What this skill does

# Generative UI

Build generative UI apps with Tambo — create rich, interactive React components from natural language.

## Reference Guides

Load these when you need deeper implementation details beyond the bootstrap flow:

- [Components](references/components.md) - **Load when creating custom components.** Generative vs interactable, propsSchema, ComponentRenderer.
- [Component Rendering](references/component-rendering.md) - Streaming props, loading states, persistent state. Load when customizing 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 adding tools or MCP.** defineTool(), MCP servers, contextHelpers.
- [CLI Reference](references/cli.md) - **Load for `tambo add` components.** Component library, non-interactive flags, exit codes.
- [Skills](references/skills.md) - **Mention as a next step after setup.** Project-scoped agent skills via CLI and dashboard.

These shared references are duplicated from building-with-tambo so each skill works independently.

## One-Prompt Flow

The goal is to get the user from zero to a running app in a single prompt. Ask all questions upfront using AskUserQuestion with multiple questions, then execute everything without stopping.

### Step 1: Gather All Non-Sensitive Preferences (Single AskUserQuestion Call)

Use AskUserQuestion with up to 3 questions in ONE call. Authentication is handled by the CLI in a later step.

**Question 1: What do you want to build?**

Ask the user what kind of app they're building. This drives which starter components to create. Examples: "a dashboard", "a chatbot", "a data visualization tool", "a task manager". If the user already said what they want in their initial message, skip this question.

**Question 2: Framework**

Options:

- Next.js (Recommended) - Full-stack React with App Router
- Vite - Fast, lightweight React setup

**Question 3: App name**

Let the user pick a name for their project directory. Default suggestion: derive from what they want to build (e.g., "my-dashboard", "my-chatbot"). Use kebab-case (letters, numbers, hyphens only). If the user gives a non-slug name like "Sales Dashboard", propose `sales-dashboard` instead.

**Skip questions when the user already told you the answer.** If they said "build me a Next.js dashboard app called analytics", you already know the framework, the app idea, and the name.

### Step 2: Execute Everything (No Stopping)

Run all of these sequentially without asking for confirmation between steps. If any command fails, stop the flow, surface the error, and ask the user how to proceed — do not continue to later steps.

All templates (`standard`, `vite`, `analytics`, `expo`) come with chat UI, TamboProvider wiring, component registry, and starter components already included. You do NOT need to add chat UI or wire up the app — just scaffold, configure the API key, add custom components, and start the server.

#### 2a. Scaffold the project

For Next.js (recommended):

```bash
npx tambo create-app <app-name> --template=standard --skip-tambo-init
cd <app-name>
```

For Vite:

```bash
npx tambo create-app <app-name> --template=vite --skip-tambo-init
cd <app-name>
```

Use `--skip-tambo-init` since `create-app` normally tries to run `tambo init` interactively, which won't work in non-interactive environments like coding agents. We handle authentication in the next step.

#### 2b. Authenticate and initialize Tambo

```bash
npx tambo init --project-name=<app-name>
```

This opens the browser for authentication and polls until the user completes auth (up to 15 minutes). Use a long timeout (at least 15 minutes) when running this command. Once auth completes, the CLI creates the project and writes the API key to `.env.local` with the correct env var for the framework (`NEXT_PUBLIC_TAMBO_API_KEY`, `VITE_TAMBO_API_KEY`, etc.).

**IMPORTANT:** Do NOT ask the user to paste an API key manually. Always use the CLI auth flow.

#### 2c. Create custom starter components

The template includes basic components, but add 1-2 components tailored to what the user wants to build. Don't use generic examples:

- **Dashboard app** → `StatsCard`, `DataTable`
- **Chatbot** → `BotResponse` with markdown support
- **Data visualization** → `Chart` with configurable data
- **Task manager** → `TaskCard`, `TaskBoard`
- **Generic / unclear** → `ContentCard`

Each component needs:

1. A Zod schema with `.describe()` on every field
2. The React component itself
3. Registration in the existing component registry (`lib/tambo.ts` — add to the existing `components` array, don't replace it)

**Schema constraints — Tambo will reject invalid schemas at runtime:**

- **No `z.record()`** — Record types (objects with dynamic keys) are not supported anywhere in the schema, including nested inside arrays or objects. Use `z.object()` with explicit named keys instead.
- **No `z.map()` or `z.set()`** — Use arrays and objects instead.
- For tabular data like rows, use `z.array(z.object({ col1: z.string(), col2: z.number() }))` with explicit column keys — NOT `z.array(z.record(z.string(), z.unknown()))`.

**React best practices for generated components:**

- Always add unique `key` props when rendering lists (`.map()`). Use a unique field from the data (like `id`) — not the array index.
- Include an `id` field (e.g., `z.string().describe("Unique identifier")`) in schemas for array items so there's always a stable key available.

Example:

```tsx
// src/components/StatsCard.tsx
import { z } from "zod/v4";

export const StatsCardSchema = z.object({
  title: z.string().describe("Metric name"),
  value: z.number().describe("Current value"),
  change: z.number().optional().describe("Percent change from previous period"),
  trend: z.enum(["up", "down", "flat"]).optional().describe("Trend direction"),
});

type StatsCardProps = z.infer<typeof StatsCardSchema>;

export function StatsCard({
  title,
  value,
  change,
  trend = "flat",
}: StatsCardProps) {
  // ... implementation with Tailwind styling
}
```

Then add to the existing registry in `lib/tambo.ts`:

```tsx
// Add to the existing components array — don't replace what's already there
// Next.js: import { StatsCard, StatsCardSchema } from "@/components/StatsCard";
// Vite: import { StatsCard, StatsCardSchema } from "../components/StatsCard";
import { StatsCard, StatsCardSchema } from "@/components/StatsCard";

// ... existing components ...
{
  name: "StatsCard",
  component: StatsCard,
  description: "Displays a metric with value and trend. Use when user asks about stats, metrics, or KPIs.",
  propsSchema: StatsCardSchema,
},
```

#### 2d. Start the dev server

Only start the dev server after all code changes (scaffolding, init, component creation, registry updates) are complete.

```bash
npm run dev
```

Run this in the background so the user can see their app immediately.

### Step 3: Summary

After everything is running, give a brief summary:

- What was set up
- What components were created and what they do
- The URL where the app is running (typically `http://localhost:3000` for Next.js, `http://localhost:5173` for Vite)
- If auth was skipped: remind them once to run `npx tambo init` to authenticate
- A suggestion for what to try first (e.g., "Try asking it to show you a stats card for monthly revenue")

## Technology Stacks Reference

### Recommended Stack (Default)

```
Next.js 14+ (App Router)
├── TypeScript
├── Tailwind CSS
├── Zod (for schemas)
└── @tambo-ai/react
```

```bash
npx tambo create-app my-app --template=standard
```

### Vite Stack

```
Vite + React
├── TypeScript
├── Tailwind CSS
├── Zod
└── @tambo-ai/react
```

### Minimal Stack (No Tailwind)

```
Vite + React
├── TypeScript
├── Plain CSS
├── Zod
└── @tambo-ai/react
```

## Component Registry Pattern

Every generative component must be registered:

```tsx
import { TamboCompo