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

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, the monorepo defines its two primary container directories:

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

{
  "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 for runtime dependencies specific to its domain.

Workspace Protocol for Internal Dependencies

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

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

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

{
  "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:

# Install all dependencies across workspaces

pnpm install

During installation, pnpm:

1. Resolves the workspace graph from 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:

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

This updates only apps/web/package.json without affecting other workspaces.

Creating and Linking a New Internal Package

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

// 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 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 defines orchestration commands:

# 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 files to determine execution order, ensuring packages build before apps that depend on them.

Summary

• Workspace definition in pnpm-workspace.yaml establishes which directories participate in the monorepo
• Root 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 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 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.

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 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.

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