Tambo AI Monorepo Structure: How Packages Are Organized in the Turborepo

The Tambo AI monorepo uses a Turborepo architecture to separate the React SDK, CLI tooling, cloud platform, and shared utilities into distinct workspaces under packages/ and apps/ directories.

The tambo-ai/tambo repository organizes its codebase as a modular monorepo that enables parallel development of the React SDK, command-line interface, documentation site, and hosted cloud services. This Tambo AI monorepo structure ensures that shared logic remains centralized while allowing each workspace to maintain independent release cycles and dependencies.

Core Directory Layout in the Tambo AI Monorepo

The repository root contains eight primary directories that separate concerns between publishable SDKs, internal applications, and shared infrastructure.

SDK and Developer Tools

The top-level folders for client-facing tools include:

• react-sdk/ – Contains the main React SDK (@tambo-ai/react) with core hooks, providers, and UI utilities. Entry point: [react-sdk/src/index.ts](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts).
• cli/ – Houses the command-line interface for project scaffolding and component generation. Key registry files live in cli/src/registry/.
• create-tambo-app/ – A project bootstrapper that generates new Tambo applications from templates.
• showcase/ – A Next.js demo application that renders every SDK component and serves as a live documentation playground.
• docs/ – The documentation site (@tambo-ai/docs) built with Fumadocs, containing guides and API references.

Cloud Platform Applications

The apps/ directory contains the hosted Tambo Cloud platform:

• apps/web/ – The Next.js frontend for the cloud platform. Top-level layout: [apps/web/src/pages/_app.tsx](https://github.com/tambo-ai/tambo/blob/main/apps/web/src/pages/_app.tsx).
• apps/api/ – The NestJS API server handling backend logic. Entry module: [apps/api/src/app.module.ts](https://github.com/tambo-ai/tambo/blob/main/apps/api/src/app.module.ts).

Shared Internal Packages

The packages/ directory contains libraries shared across workspaces:

• packages/core/ – Pure utilities for validation, cryptography, and threading. Exports: [packages/core/src/index.ts](https://github.com/tambo-ai/tambo/blob/main/packages/core/src/index.ts).
• packages/backend/ – LLM and agent-side helpers with streaming utilities.
• packages/db/ – Drizzle ORM schema, migrations, and database helpers. Schema definition: [packages/db/src/schema.ts](https://github.com/tambo-ai/tambo/blob/main/packages/db/src/schema.ts).
• packages/eslint-config/, packages/typescript-config/, packages/vite-config/ – Shared tooling configurations ensuring consistent linting and build setups. Base ESLint rules: packages/eslint-config/base.mjs.

How Packages Relate and Share Code

The Tambo AI monorepo structure enforces relationships through workspace-level imports and shared configuration files.

Workspace-Level Imports

Packages under packages/ expose exports via workspace "*" versioning. This allows other workspaces to import them using scoped names like @tambo-ai/core or @tambo-ai/db without publishing to npm during development.

Shared Configuration

ESLint, Prettier, TypeScript, and Vite configurations live in dedicated packages/*-config directories. Each package references these from its own tsconfig.json or vite.config.ts, guaranteeing uniform developer experience across the repository.

Component Synchronization

The CLI maintains a component registry in cli/src/registry/. During the build process, these components are automatically copied into showcase/src/components/tambo/ and docs/src/components/. This single-source-of-truth model ensures that UI examples remain synchronized across the demo site and documentation.

Cloud and SDK Parity

The cloud platform (apps/web and apps/api) consumes the same core utilities (packages/core) and database schema (packages/db) that the React SDK relies on. This shared foundation allows feature parity between the hosted product and the open-source SDK.

Typical Development Workflow

Developers interact with the Tambo AI monorepo structure through specific workspace commands and cross-package dependencies.

1. Add a new UI component – Edit the definition in cli/src/registry/, then run the CLI generation script. The component automatically appears in both showcase and docs.

2. Create a new backend service – Place reusable logic in packages/backend, then import it from the NestJS services in apps/api/src/.

3. Extend the SDK – Add a hook or provider inside react-sdk/src/, then expose it via the package entry point at react-sdk/src/index.ts.

4. Run targeted development servers – Use npm run dev:sdk to start the SDK watch mode alongside the showcase, or npm run dev:cloud to launch the cloud UI and API together.

Key Source Files and Entry Points

Understanding the Tambo AI monorepo structure requires familiarity with these critical files:

File	Role
[packages/core/src/index.ts](https://github.com/tambo-ai/tambo/blob/main/packages/core/src/index.ts)	Core pure utilities entry point
[packages/db/src/schema.ts](https://github.com/tambo-ai/tambo/blob/main/packages/db/src/schema.ts)	Drizzle ORM schema definitions
[react-sdk/src/index.ts](https://github.com/tambo-ai/tambo/blob/main/react-sdk/src/index.ts)	React SDK public exports
cli/src/registry/	Component registry source files
[apps/api/src/app.module.ts](https://github.com/tambo-ai/tambo/blob/main/apps/api/src/app.module.ts)	NestJS API application root module
[apps/web/src/pages/_app.tsx](https://github.com/tambo-ai/tambo/blob/main/apps/web/src/pages/_app.tsx)	Cloud platform Next.js application wrapper
packages/eslint-config/base.mjs	Shared ESLint configuration base
[AGENTS.md](https://github.com/tambo-ai/tambo/blob/main/AGENTS.md)	Contributor guide outlining monorepo philosophy and standards

Summary

The Tambo AI monorepo structure organizes the codebase into a Turborepo workspace that balances separation of concerns with shared infrastructure:

• Top-level directories isolate the React SDK (react-sdk/), CLI tooling (cli/), demo showcase (showcase/), documentation (docs/), and cloud platform (apps/).
• Shared packages under packages/ centralize core utilities, database schemas, backend helpers, and tooling configurations to ensure consistency.
• Workspace imports use scoped package names (e.g., @tambo-ai/core) with "*" versioning to enable cross-package dependencies without external publishing.
• Automated synchronization keeps UI components aligned between the CLI registry, showcase, and documentation sites.

Frequently Asked Questions

What is the difference between the apps/ and packages/ directories in the Tambo AI monorepo?

The apps/ directory contains deployable applications, specifically the Tambo Cloud platform with its Next.js frontend (apps/web) and NestJS API server (apps/api). The packages/ directory contains shared libraries that are imported by these applications and other workspaces, such as core utilities (packages/core), database schemas (packages/db), and configuration presets (packages/eslint-config).

How does the React SDK relate to the other packages in the repository?

The react-sdk/ directory is treated as a first-class workspace alongside packages/, containing the main @tambo-ai/react package. It imports shared utilities from packages/core and packages/backend while exposing its own hooks and providers through react-sdk/src/index.ts. This structure allows the SDK to leverage centralized logic while maintaining independent versioning and release cycles.

Where are shared ESLint and TypeScript configurations defined?

Shared tooling configurations reside in dedicated packages under the packages/ directory. ESLint rules are defined in packages/eslint-config/base.mjs, TypeScript configurations in packages/typescript-config/, and Vite settings in packages/vite-config/. Each workspace references these via relative paths in their local configuration files, ensuring consistent linting and build behavior across the entire monorepo.

What is the purpose of the cli/src/registry/ directory?

The cli/src/registry/ directory serves as the single source of truth for UI components that are distributed via the Tambo CLI. When components are generated or updated here, automated scripts synchronize them to both the showcase/src/components/tambo/ and docs/src/components/ directories. This ensures that the demo showcase and documentation site always display the latest component implementations without manual copying.

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