# How to Develop Custom Components for Tambo AI: Complete Registry Guide

> Learn to develop custom components for Tambo AI. Create TSX implementations and config files. Distribute easily with npx tambo add for seamless integration.

- Repository: [tambo ai/tambo](https://github.com/tambo-ai/tambo)
- Tags: how-to-guide
- Published: 2026-02-16

---

**To develop custom components for Tambo AI, create a directory in `packages/ui-registry/src/components/` containing a TSX implementation and a [`config.json`](https://github.com/tambo-ai/tambo/blob/main/config.json) manifest, then distribute them via `npx tambo add <component-name>` which automatically handles file copying, path resolution, and dependency installation.**

Tambo AI provides a component registry architecture that powers its CLI tooling, enabling developers to distribute reusable React components across projects. This guide walks you through the complete workflow for developing custom components for Tambo AI within the `tambo-ai/tambo` monorepo, from initial creation in the UI registry to automated installation in consumer applications.

## Understanding the Tambo AI Component Registry Architecture

The component registry is a curated collection of React components stored in `packages/ui-registry/src/components/`. Each component resides in its own directory and includes a [`config.json`](https://github.com/tambo-ai/tambo/blob/main/config.json) manifest that describes its files, dependencies, and metadata. When you run `tambo add <name>`, the CLI validates the component against this registry, resolves the target installation path, and handles all file operations and dependency management automatically.

## Step-by-Step Guide to Developing Custom Components for Tambo AI

### Create the Component Directory Structure

Create a new folder under `packages/ui-registry/src/components/` using kebab-case naming:

```bash
mkdir -p packages/ui-registry/src/components/awesome-button

```

This folder will contain your component implementation, configuration manifest, and any shared utilities.

### Implement the React Component

Create the main component file with a `.tsx` extension. Use standard React patterns and import utilities from the `@/lib/utils` path alias, which the CLI will automatically rewrite for target projects.

```tsx
// packages/ui-registry/src/components/awesome-button/awesome-button.tsx
import { cn } from "@/lib/utils";

export function AwesomeButton({ 
  children,
  onClick 
}: { 
  children: React.ReactNode;
  onClick?: () => void;
}) {
  return (
    <button 
      onClick={onClick}
      className={cn("rounded bg-primary px-4 py-2 text-white hover:bg-primary/90")}
    >
      {children}
    </button>
  );
}

```

### Define the Component Manifest (config.json)

The [`config.json`](https://github.com/tambo-ai/tambo/blob/main/config.json) file is required for the CLI to recognize and install your component. It specifies the component name, description, file list, and NPM dependencies.

```json
{
  "componentName": "AwesomeButton",
  "description": "A primary button component with Tambo styling and hover states",
  "files": [
    {
      "name": "awesome-button.tsx",
      "content": ""
    }
  ],
  "dependencies": ["@tambo-ai/react"],
  "devDependencies": ["clsx", "tailwind-merge"]
}

```

The `files` array lists all assets to copy, while `dependencies` and `devDependencies` trigger automatic installation via the consumer's package manager.

### Add Shared Utilities (Optional)

If your component requires helper functions, create them in a `lib/` subdirectory within your component folder. The CLI detects these utilities and copies them to the project's `lib/` directory, creating the file if it doesn't exist.

```typescript
// packages/ui-registry/src/components/awesome-button/lib/helpers.ts
export function formatButtonLabel(text: string): string {
  return text.trim().toUpperCase();
}

```

## Testing Your Custom Component Locally

Before publishing, verify your component renders correctly using the showcase application included in the monorepo:

```bash
npm run dev:sdk

```

This command launches the development server at `http://localhost:8262`. Navigate to the Components section to visually inspect your new component, test its props, and ensure it integrates properly with the Tambo design system.

## Installing Custom Components in Consumer Projects

### CLI Installation Workflow

Once your component is committed to the registry, install it in any Tambo-enabled project using the CLI:

```bash
npx tambo add awesome-button

```

For custom directory structures, specify a prefix path:

```bash
npx tambo add awesome-button --prefix src/ui

```

### How the CLI Handles Component Installation

The `tambo add` command executes a precise sequence of operations defined in the CLI source code:

1. **Validation**: The `componentExists` function in [`cli/src/commands/add/utils.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/utils.ts) verifies the component name exists in the registry.
2. **Path Resolution**: `getComponentDirectoryPath` and `getLibDirectory` in [`cli/src/commands/shared/path-utils.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/shared/path-utils.ts) determine the destination folders based on project configuration.
3. **File Operations**: The `installComponents` function in [`cli/src/commands/add/component.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/component.ts) copies component files, rewrites import paths for the target project, and creates [`utils.ts`](https://github.com/tambo-ai/tambo/blob/main/utils.ts) in the lib directory if missing.
4. **Dependency Installation**: The CLI detects the package manager via `detectPackageManager` and executes installation commands for all listed `dependencies` and `devDependencies`.

After completion, the component is ready for immediate import and use in your application.

## Complete Development Workflow Example

The following bash script demonstrates the entire process from registry creation to consumer installation:

```bash

# 1. Create component structure in the registry

mkdir -p packages/ui-registry/src/components/awesome-button

# 2. Write component implementation

cat > packages/ui-registry/src/components/awesome-button/awesome-button.tsx <<'EOF'
import { cn } from "@/lib/utils";

export function AwesomeButton({ children }: { children: React.ReactNode }) {
  return (
    <button className={cn("rounded bg-primary px-4 py-2 text-white")}>
      {children}
    </button>
  );
}
EOF

# 3. Create configuration manifest

cat > packages/ui-registry/src/components/awesome-button/config.json <<'EOF'
{
  "componentName": "AwesomeButton",
  "description": "A button with the Tambo style",
  "files": [{ "name": "awesome-button.tsx", "content": "" }],
  "dependencies": ["@tambo-ai/react"],
  "devDependencies": ["clsx", "tailwind-merge"]
}
EOF

# 4. Commit to registry

git add packages/ui-registry/src/components/awesome-button
git commit -m "feat(ui-registry): add AwesomeButton component"

# 5. Install in consumer project

cd apps/web
npx tambo add awesome-button --prefix src/ui

```

This workflow results in:
- [`src/ui/awesome-button.tsx`](https://github.com/tambo-ai/tambo/blob/main/src/ui/awesome-button.tsx) containing the component code
- [`src/lib/utils.ts`](https://github.com/tambo-ai/tambo/blob/main/src/lib/utils.ts) auto-generated with utility functions
- Updated [`package.json`](https://github.com/tambo-ai/tambo/blob/main/package.json) including `@tambo-ai/react`, `clsx`, and `tailwind-merge`

## Summary

Developing custom components for Tambo AI involves creating standardized registry entries that the CLI can distribute across projects. The key steps include:

- Create a directory in `packages/ui-registry/src/components/` containing a TSX implementation and a [`config.json`](https://github.com/tambo-ai/tambo/blob/main/config.json) manifest that declares dependencies and file assets.
- Test components locally using `npm run dev:sdk` to launch the showcase application at `localhost:8262`.
- Distribute components via `npx tambo add <component-name>`, which triggers the CLI workflow in [`cli/src/commands/add/component.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/component.ts) to handle validation, path resolution, file copying, and dependency installation.
- The CLI automatically manages shared utilities by copying files from component `lib/` directories and rewriting import paths for the target project structure.

## Frequently Asked Questions

### What is the purpose of the config.json file in Tambo AI components?

The [`config.json`](https://github.com/tambo-ai/tambo/blob/main/config.json) file serves as the component manifest that the Tambo CLI uses to identify, validate, and install your component. It specifies the `componentName`, `description`, array of `files` to copy, and both `dependencies` and `devDependencies` that the CLI automatically installs in the consumer project via `detectPackageManager` and `execFileSync` in [`cli/src/commands/add/component.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/component.ts).

### How does the Tambo CLI handle import path rewriting when installing components?

When you run `npx tambo add <component>`, the `installComponents` function in [`cli/src/commands/add/component.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/component.ts) analyzes the source files and rewrites import paths to match the target project's structure. For example, imports from `@/lib/utils` are adjusted to point to the correct relative path in the consumer's directory tree, ensuring the component works regardless of whether you use the default `components/` directory or a custom `--prefix` like `src/ui`.

### Can I install Tambo AI components into a custom directory structure?

Yes, the Tambo CLI supports custom installation paths via the `--prefix` flag. When you run `npx tambo add <component> --prefix src/ui`, the `getComponentDirectoryPath` function in [`cli/src/commands/shared/path-utils.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/shared/path-utils.ts) resolves the destination folder relative to your project root. The CLI then copies component files to `src/ui/<component-name>/` and creates or updates [`src/lib/utils.ts`](https://github.com/tambo-ai/tambo/blob/main/src/lib/utils.ts) accordingly, maintaining proper import relationships throughout the custom structure.

### What happens if a component requires additional npm dependencies?

The Tambo CLI automatically handles dependency installation during the `tambo add` process. When you define `dependencies` or `devDependencies` in your component's [`config.json`](https://github.com/tambo-ai/tambo/blob/main/config.json), the `installComponents` function in [`cli/src/commands/add/component.ts`](https://github.com/tambo-ai/tambo/blob/main/cli/src/commands/add/component.ts) uses `detectPackageManager` to identify whether your project uses npm, yarn, or pnpm, then executes the appropriate install command via `execFileSync`. This ensures that components requiring libraries like `@tambo-ai/react`, `clsx`, or `tailwind-merge` work immediately after installation without manual package management.