Contributing

​

Quick Links

• Repository: github.com/tambo-ai/tambo
• Issues: github.com/tambo-ai/tambo/issues
• Discord: discord.gg/dJNvPEHth6
• Docs: docs.tambo.co

​

Development Setup

​

Prerequisites

• Node.js >= 22
• npm >= 11
• Docker (for database)
• Git

# Install mise
curl https://mise.run | sh

# Install required tools
mise install

​

Clone and Install

git clone https://github.com/tambo-ai/tambo.git
cd tambo
npm install

​

Set Up Environment

# Copy environment templates
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env.local
cp packages/db/.env.example packages/db/.env

​

Start Database

​

Option A: Supabase (Recommended)

# Start Supabase (includes PostgreSQL)
npx supabase start

# DATABASE_URL already configured in .env.example:
# postgresql://postgres:postgres@127.0.0.1:54322/postgres

​

Option B: Docker PostgreSQL

# One-time setup
./scripts/cloud/tambo-setup.sh

# Start PostgreSQL
docker compose --env-file docker.env up postgres -d

# Update DATABASE_URL in all .env files:
# postgresql://postgres:postgres@localhost:5433/tambo

​

Initialize Database

npm run db:migrate -w packages/db

​

Start Development Servers

# For Tambo Cloud (web + API)
npm run dev:cloud
# Web: http://localhost:8260
# API: http://localhost:8261

# For React SDK (showcase + docs)
npm run dev

# For React SDK development with watch mode
npm run dev:sdk

​

Get a Local API Key

1. Start dev servers: npm run dev:cloud
2. Visit http://localhost:8260 and sign in
3. Create a project and generate an API key
4. Add to apps/web/.env.local:
   NEXT_PUBLIC_TAMBO_API_KEY=your_key
   
5. Verify: http://localhost:8260/internal/smoketest

​

Development Workflow

​

Branch Naming

git checkout -b alecf/add-dark-mode
git checkout -b jane/fix-login-bug

​

Making Changes

1. Write tests for new functionality
2. Run quality checks before committing:

npm run lint
npm run check-types
npm test

3. Follow code style:
   • TypeScript strict mode
   • Functional components (React)
   • No any types
   • Descriptive variable names

​

Commit Messages

<type>(scope): <description>

feat(api): add transcript export
fix(web): prevent duplicate project creation
chore(db): reorganize migration files

​

Pull Request Process

1. Push your branch:

git push origin <your-branch>

2. Open PR on GitHub with:
   • Clear title following conventional commits
   • Description of changes
   • Link to related issue (if any)
   • Screenshots/videos for UI changes
3. PR Requirements:
   • All tests pass
   • No TypeScript errors
   • Code reviewed by maintainer
   • Documentation updated (if needed)
4. Link Issues:

Fixes #123 (GitHub issue)
Fixes TAM-123 (Linear issue)

​

Repository Structure

​

Framework Packages

• react-sdk/ - React SDK (@tambo-ai/react)
• packages/client/ - Framework-agnostic client
• cli/ - Command-line interface
• showcase/ - Demo application (port 8262)
• docs/ - Documentation site (port 8263)
• create-tambo-app/ - App bootstrapper

​

Tambo Cloud Platform

• apps/web/ - Next.js UI (port 8260)
• apps/api/ - NestJS API (port 8261)
• packages/db/ - Drizzle schema + migrations
• packages/core/ - Shared utilities
• packages/backend/ - LLM/agent helpers

​

Testing

​

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run specific package tests
npm test -w react-sdk
npm test -w cli

​

Writing Tests

• Unit tests: Test individual functions/components
• Integration tests: Test component interactions
• E2E tests: Test full user flows

import { render, screen } from "@testing-library/react";
import { MyComponent } from "./MyComponent";

describe("MyComponent", () => {
  it("renders correctly", () => {
    render(<MyComponent />);
    expect(screen.getByText("Hello")).toBeInTheDocument();
  });
});

​

Documentation

​

Writing Docs

# Start docs dev server
npm run dev -w docs

​

Doc Guidelines

• Use MDX format
• Include code examples
• Keep examples concise
• Test code examples work
• Add frontmatter metadata:

---
title: Page Title
description: Brief description
---

# Content here

​

Component Library

​

Adding Components

1. Create component directory:
   packages/ui-registry/src/components/my-component/
   
2. Add component files:
   my-component/
   ├── config.json
   ├── my-component.tsx
   └── README.md
   
3. Configure config.json:

{
  "name": "my-component",
  "type": "component",
  "description": "Component description",
  "dependencies": ["@tambo-ai/react"],
  "files": ["my-component.tsx"]
}

4. Export from package.json:

{
  "exports": {
    "./my-component": "./src/components/my-component/index.ts"
  }
}

5. Rebuild CLI:

npm run build -w cli

6. Test installation:

tambo add my-component

​

Code Style

​

TypeScript

• Enable strict mode
• No any types - use unknown if needed
• Prefer interface for object shapes
• Use const for immutable values
• Avoid let when possible

​

React

• Functional components only
• Use hooks for state management
• Memoize expensive computations
• Keep components focused and small
• Use TypeScript for prop types

​

Naming

• Files: kebab-case (my-component.tsx)
• Components: PascalCase (MyComponent)
• Hooks: camelCase (useTambo)
• Variables: camelCase (userName)
• Constants: UPPER_SNAKE_CASE (API_URL)

​

Formatting

npm run format

​

Getting Help

​

Ask Questions

• Discord: discord.gg/dJNvPEHth6
• Discussions: GitHub Discussions

​

Report Issues

1. Search existing issues first
2. Use issue templates
3. Include:
   • Clear description
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details
   • Code examples

​

Suggest Features

1. Open a discussion first
2. Describe the use case
3. Explain why it’s valuable
4. Consider implementation approach

​

Code of Conduct

​

License

• Core SDK: MIT License
• API: Apache 2.0 License

​

Related Resources

• Development Setup Details
• Architecture Guide
• Migration Guide
• Troubleshooting