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

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 file defines workspace boundaries and enforces version constraints across all packages.

Workspace Configuration

The pnpm-workspace.yaml file declares which directories participate in the workspace and centralizes dependency overrides.

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.
• apps/web/ – The React frontend application using Vite and TanStack, bootstrapped in 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
• packages/typescript-config/ – Centralized TypeScript configuration

Both the API and Web apps import the API_URL constant from packages/libs/src/api-url.ts:

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

# 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 at the repository root, which complements the machine-readable configuration in pnpm-workspace.yaml. Key source files illustrating this structure include:

• pnpm-workspace.yaml – Workspace declaration and dependency overrides
• apps/api/src/index.ts – Backend API entry point
• apps/web/src/main.tsx – Frontend bootstrap
• 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.
• 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, 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 at the repository root, while the technical workspace boundaries and dependency overrides are defined in pnpm-workspace.yaml. These files collectively specify how pnpm and TurboRepo interpret the repository structure.

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