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

To develop custom components for Tambo AI, create a directory in packages/ui-registry/src/components/ containing a TSX implementation and a 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 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:

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.

// 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 file is required for the CLI to recognize and install your component. It specifies the component name, description, file list, and NPM dependencies.

{
  "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.

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

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:

npx tambo add awesome-button

For custom directory structures, specify a prefix path:

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 verifies the component name exists in the registry.
2. Path Resolution: getComponentDirectoryPath and getLibDirectory in 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 copies component files, rewrites import paths for the target project, and creates 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:

# 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 containing the component code
• src/lib/utils.ts auto-generated with utility functions
• Updated 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 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 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 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.

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 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 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 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, the installComponents function in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}