# What Is a Monorepo and How Is It Structured in Kaneo?

> Learn what a monorepo is and how Kaneo structures it. Discover its pnpm workspace with TurboRepo, organizing code into apps packages and charts directories.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: deep-dive
- Published: 2026-08-09

---

**A monorepo is a single Git repository containing multiple related projects or packages, and Kaneo implements this pattern using a pnpm-managed workspace with TurboRepo that organizes code into `apps/`, `packages/`, and `charts/` directories.**

A monorepo consolidates distinct software projects into one version-controlled codebase, enabling atomic commits across components and shared build tooling. In the Kaneo project, this architectural approach simplifies dependency management and ensures consistent configuration across the backend API, frontend application, and shared libraries. Understanding what is a monorepo and how Kaneo leverages this structure reveals why the team chose unified tooling over distributed repositories.

## Understanding the Monorepo Pattern

A **monorepo** (short for monolithic repository) keeps the source code of multiple related projects in a single Git repository instead of splitting each component into its own repo. This pattern enables shared tooling, consistent versioning, and easy cross-package imports while eliminating the overhead of cross-repository synchronization.

## Kaneo’s Monorepo Architecture

The Kaneo repository uses a **pnpm-managed monorepo** powered by TurboRepo to coordinate builds and task execution. At the repository root, the [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) file defines workspace boundaries and enforces version constraints across all packages.

### Workspace Configuration

The [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) file declares which directories participate in the workspace and centralizes dependency overrides.

```yaml
packages:
  - "packages/**"
  - "apps/**"
overrides:
  hono: ">=4.12.25"
  valibot: ">=1.4.2"

```

This configuration treats both `apps/**` and `packages/**` as workspace members, while the `overrides` field guarantees consistent versions of **Hono** (`>=4.12.25`) and **Valibot** (`>=1.4.2`) throughout the monorepo.

### Directory Layout

Kaneo organizes code into three primary directories:

```

kaneo/
├── apps/
│   ├── api/          # Backend API (Hono, PostgreSQL, Drizzle ORM)

│   ├── web/          # Frontend app (React, Vite, TanStack)

│   └── docs/         # Documentation site (Mintlify/Next.js)

├── packages/
│   ├── email/        # Email utilities

│   ├── libs/         # Shared library helpers

│   └── typescript-config/  # Central TS config

└── charts/           # Helm charts for Kubernetes deployments

```

The `apps/` folder hosts **first-class applications** that run independently, while `packages/` contains **reusable libraries** that both apps and other packages import. The `charts/` folder co-locates deployment manifests with application code.

## Code Organization and Cross-Package Dependencies

The monorepo structure enables seamless code sharing between the frontend and backend through the `packages/` directory.

### Applications in apps/

The `apps/` directory contains three runnable services:

- **`apps/api/`** – The backend API server built with Hono, PostgreSQL, and Drizzle ORM. The entry point resides in [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts).
- **`apps/web/`** – The React frontend application using Vite and TanStack, bootstrapped in [`apps/web/src/main.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx).
- **`apps/docs/`** – Documentation site powered by Mintlify or Next.js.

Each application maintains its own build configuration while importing shared utilities from sibling packages.

### Shared Libraries in packages/

The `packages/` directory exports reusable code consumed by multiple applications:

- **`packages/email/`** – Email templating and delivery utilities
- **`packages/libs/`** – Core shared helpers exported from [`packages/libs/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/index.ts)
- **`packages/typescript-config/`** – Centralized TypeScript configuration

Both the API and Web apps import the `API_URL` constant from [`packages/libs/src/api-url.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/api-url.ts):

```typescript
// packages/libs/src/api-url.ts
export const API_URL = import.meta.env.VITE_API_URL ?? "http://localhost:1337";

```

This pattern ensures environment-specific configuration remains synchronized across service boundaries.

## Unified Development Workflow

Kaneo leverages shared tooling to streamline the developer experience across all workspace members.

### Centralized Environment Configuration

Rather than maintaining separate `.env` files in each package, Kaneo uses a **single `.env` file at the repository root**. This approach guarantees that environment variables remain synchronized between the API, Web frontend, and shared libraries, preventing configuration drift.

### Task Execution

From the repository root, developers can start all services simultaneously using pnpm workspaces:

```bash

# Start API and Web apps in parallel from the monorepo root

pnpm dev

```

TurboRepo orchestrates these tasks, caching build outputs to prevent redundant computation when package contents remain unchanged.

## Documentation and Source References

The monorepo philosophy and architecture are documented in [`CLAUDE.md`](https://github.com/usekaneo/kaneo/blob/main/CLAUDE.md) at the repository root, which complements the machine-readable configuration in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml). Key source files illustrating this structure include:

- [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) – Workspace declaration and dependency overrides
- [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) – Backend API entry point
- [`apps/web/src/main.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx) – Frontend bootstrap
- [`packages/libs/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/index.ts) – Shared utility exports

## Summary

- A **monorepo** consolidates multiple projects into one Git repository, enabling atomic changes and shared tooling.
- Kaneo uses **pnpm workspaces** with TurboRepo to manage dependencies and build pipelines across `apps/` and `packages/`.
- The `apps/` directory contains runnable services (API, Web, Docs), while `packages/` provides shared libraries like `packages/libs/`.
- **Cross-package imports** allow both frontend and backend to consume utilities from [`packages/libs/src/api-url.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/api-url.ts).
- A **single root-level `.env`** file ensures consistent configuration across all services.
- Infrastructure code lives in `charts/` for version-controlled Kubernetes deployments.

## Frequently Asked Questions

### What is the difference between a monorepo and a polyrepo?

A monorepo stores all related projects in a single repository, while a polyrepo architecture maintains separate repositories for each service. Monorepos facilitate cross-project refactoring and consistent versioning, whereas polyrepos enforce stricter service boundaries but require complex coordination for changes spanning multiple repositories.

### How does Kaneo handle shared dependencies across packages?

Kaneo centralizes dependency management through [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml), which defines workspace globs for `apps/**` and `packages/**`. The configuration includes an `overrides` section that pins versions for critical dependencies like `hono>=4.12.25` and `valibot>=1.4.2`, ensuring all workspace members use identical library versions.

### Can applications in the Kaneo monorepo be deployed independently?

Yes, despite sharing a repository, each application in the `apps/` directory builds into independent artifacts. The API service (`apps/api/`) and Web frontend (`apps/web/`) maintain separate deployment pipelines, allowing teams to release updates to individual services without redeploying the entire monorepo.

### Where is the monorepo configuration documented in Kaneo?

The high-level architecture and workspace philosophy are documented in [`CLAUDE.md`](https://github.com/usekaneo/kaneo/blob/main/CLAUDE.md) at the repository root, while the technical workspace boundaries and dependency overrides are defined in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml). These files collectively specify how pnpm and TurboRepo interpret the repository structure.