# How Dependencies Are Managed in the usekaneo/kaneo Project: A Deep Dive

> Discover how usekaneo/kaneo manages dependencies in its pnpm monorepo with Turborepo. Learn about workspace protocols and version overrides for efficient development.

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

---

**The usekaneo/kaneo project uses a pnpm-based monorepo architecture with workspace protocols, root-level version overrides, and Turborepo orchestration to centralize dependency management while keeping packages isolated.**

Dependency management in modern monorepos requires careful coordination between shared tooling and package-specific needs. In the Kaneo codebase, every layer—from workspace topology to lockfile generation—serves a specific purpose in maintaining reproducible builds and consistent versions across apps and packages.

## Workspace Topology and Configuration

The foundation of Kaneo's **dependency management** strategy starts with explicit workspace declaration.

In [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml), the monorepo defines its two primary container directories:

```yaml
packages:
  - "packages/**"
  - "apps/**"

```

This configuration tells pnpm which folders participate in the workspace graph, enabling cross-package references and unified installation.

## Root-Level Dependency Control

The root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) serves as the central command center for tooling and version enforcement.

### Global Dev Dependencies and Tooling

Running `pnpm install` from the repository root installs shared development tools used across all workspaces:

- **Biome** for linting and formatting
- **Turborepo** for build orchestration
- **Husky** for git hooks
- **TypeScript** and related tooling

These tools are available to every workspace without duplicating declarations.

### Version Pinning with pnpm.overrides

The most critical feature for dependency stability appears in the `pnpm.overrides` block:

```json
{
  "pnpm": {
    "overrides": {
      "hono": "4.6.16",
      "better-auth": "1.0.22",
      "@aws-sdk/client-s3": "3.726.0",
      "zod": "3.22.4"
    }
  }
}

```

This override mechanism forces exact versions for **transitive dependencies** regardless of what individual packages request. As implemented in usekaneo/kaneo, this eliminates version conflicts when multiple workspaces depend on the same library with different semver ranges.

## Per-Package Dependency Declarations

Each application and shared package maintains its own [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) for runtime dependencies specific to its domain.

### Workspace Protocol for Internal Dependencies

Internal code sharing uses pnpm's **workspace protocol** rather than registry versions:

```json
{
  "dependencies": {
    "@kaneo/email": "workspace:*",
    "@kaneo/permissions": "workspace:*",
    "@kaneo/clickhouse": "workspace:*",
    "@kaneo/db": "workspace:*"
  }
}

```

In [`apps/api/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/api/package.json), these `workspace:*` references create symlinks to local packages instead of fetching from npm. This enables instant code sharing without publish cycles and guarantees that all apps use the same implementation of shared utilities.

### External Dependencies in Apps

Third-party libraries are declared where they're consumed. For example, the API app lists:

```json
{
  "dependencies": {
    "hono": "^4.6.16",
    "better-auth": "^1.0.22",
    "zod": "^3.22.4"
  }
}

```

The caret ranges here are constrained by root-level `pnpm.overrides`, ensuring the actual installed version matches across all workspaces.

## Installation and Linking Workflow

The pnpm installation process handles both external fetching and internal linking:

```bash

# Install all dependencies across workspaces

pnpm install

```

During installation, pnpm:

1. Resolves the workspace graph from [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml)
2. Fetches external packages to the global content-addressable store
3. Creates hard links or symlinks from node_modules to the store
4. Establishes `workspace:*` symlinks between local packages

Because pnpm deduplicates packages in its global store, disk usage remains efficient even with dozens of workspace dependencies.

## Practical Dependency Operations

### Adding a Third-Party Library to a Single App

Target dependency changes to specific workspaces:

```bash
cd apps/web
pnpm add @tanstack/react-query@5.101.2

```

This updates only [`apps/web/package.json`](https://github.com/usekaneo/kaneo/blob/main/apps/web/package.json) without affecting other workspaces.

### Creating and Linking a New Internal Package

```bash

# 1. Create the package

mkdir packages/utils
cd packages/utils
pnpm init -y

# 2. Consume it from another workspace

# Edit apps/api/package.json to add:

#   "@kaneo/utils": "workspace:*"

# 3. Establish the link

pnpm install

```

Using the linked package in code requires no special syntax:

```typescript
// apps/api/src/formatters.ts
import { formatDate } from "@kaneo/utils";

export function getFormattedNow(): string {
  return formatDate(new Date());
}

```

## Lockfile and Reproducibility

The [`pnpm-lock.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-lock.yaml) file at repository root records exact resolved versions for every dependency across all workspaces. Combined with `pnpm.overrides`, this lockfile guarantees that:

- Every developer installs identical dependency trees
- CI/CD builds match local development
- Transitive dependencies remain locked to audited versions

## Turborepo Integration for Monorepo Tasks

Dependency management connects directly to task execution through Turborepo. The root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) defines orchestration commands:

```bash

# Run dev servers for all apps in dependency order

turbo dev

# Build all packages and apps with proper topological sorting

turbo build

# Run linting across workspaces

turbo lint

```

Turborepo reads workspace dependencies from [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) files to determine execution order, ensuring packages build before apps that depend on them.

## Summary

- **Workspace definition** in [`pnpm-workspace.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-workspace.yaml) establishes which directories participate in the monorepo
- **Root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json)** centralizes dev tooling and enforces version consistency through `pnpm.overrides`
- **Workspace protocol** (`workspace:*`) enables efficient internal code sharing without registry publication
- **Per-package [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) files** declare domain-specific runtime dependencies
- **Global pnpm store** with hard links minimizes disk usage across workspaces
- **Lockfile and overrides** together guarantee reproducible builds

## Frequently Asked Questions

### What is the workspace protocol in pnpm and why does Kaneo use it?

The **workspace protocol** (`workspace:*`) tells pnpm to resolve a package name as a local workspace member rather than fetching from npm. Kaneo uses this for all internal packages (`@kaneo/email`, `@kaneo/permissions`, etc.) to enable instant code sharing, eliminate version drift between packages, and avoid unnecessary publish cycles during development.

### How does Kaneo prevent version conflicts for shared dependencies?

Kaneo uses the **`pnpm.overrides`** field in the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) to force exact versions for critical packages like `hono`, `better-auth`, and `zod`. This override applies globally, ensuring that even if different workspaces specify different semver ranges, all resolve to the same pinned version recorded in [`pnpm-lock.yaml`](https://github.com/usekaneo/kaneo/blob/main/pnpm-lock.yaml).

### Where should new dependencies be installed in the Kaneo monorepo?

Install third-party libraries in the specific `apps/` or `packages/` directory where they're consumed using `pnpm add`. For shared tooling used across all workspaces, add to the root [`package.json`](https://github.com/usekaneo/kaneo/blob/main/package.json) as a dev dependency. Internal packages that multiple apps need should be created under `packages/` and referenced via `workspace:*` protocol.

### Can I use different versions of the same library in different Kaneo apps?

While technically possible by omitting the override, Kaneo's `pnpm.overrides` explicitly prevents this for core dependencies. The project prioritizes version consistency over flexibility to reduce bundle complexity, simplify debugging, and ensure compatibility across the entire system.