Dependency Management

Overview#

The Oshun monorepo uses pnpm 10+ with the catalog: feature for centralized version management. This ensures consistent dependency versions across all projects and simplifies upgrades.

pnpm Catalog#

What is the Catalog?#

The catalog is defined in pnpm-workspace.yaml and provides a single source of truth for dependency versions. Instead of specifying versions in each package.json, projects reference the catalog:

// package.json
{
  "dependencies": {
    "hono": "catalog:",
    "zod": "catalog:",
    "ioredis": "catalog:"
  }
}

The actual versions are resolved from the catalog: section of pnpm-workspace.yaml:

catalog:
  hono: ^4.0.0
  zod: ^3.23.0
  ioredis: ^5.3.2

Benefits#

1. Single version per dependency - No version conflicts across projects
2. Easy upgrades - Change the version once in the catalog
3. Lockfile consistency - pnpm-lock.yaml stays clean
4. IDE support - pnpm resolves catalog references transparently

Common Catalog Entries#

Below are key dependencies managed through the catalog. See pnpm-workspace.yaml for the complete list.

Frameworks:

Database:

AI/ML:

Validation & Types:

Testing:

Observability:

AWS SDK:

Workspace Dependencies#

For internal monorepo dependencies, use the workspace:* protocol:

{
  "dependencies": {
    "@oshun/database": "workspace:*",
    "@oshun/logger": "workspace:*"
  }
}

This always resolves to the local workspace version, ensuring you never accidentally pull a published version.

Adding a New Dependency#

To a single project#

pnpm add <package> --filter <project-name>

To the catalog#

1. Add the version to pnpm-workspace.yaml:

   yamlCopy

   catalog:
     new-package: ^1.0.0
   

2. Reference it in your package.json:

   jsonCopy

   {
     "dependencies": {
       "new-package": "catalog:"
     }
   }
   

3. Run pnpm install to update the lockfile.

To shared (root devDependencies)#

For tools used across the monorepo (e.g., typescript, eslint):

pnpm add -D -w <package>

Upgrading Dependencies#

Upgrade a catalog entry#

1. Update the version in pnpm-workspace.yaml
2. Run pnpm install
3. Run pnpm nx affected --target=build to verify
4. Run pnpm nx affected --target=test to verify

Audit for vulnerabilities#

pnpm audit

Path Aliases#

TypeScript path aliases are defined in tsconfig.base.json at the monorepo root. These map @oshun/* and @{domain}/* imports to source directories:

{
  "compilerOptions": {
    "paths": {
      "@oshun/database": ["libs/shared/database/src/index.ts"],
      "@oshun/logger": ["libs/shared/logger/src/index.ts"],
      "@iris/conversation-core": ["libs/iris/conversation-core/src/index.ts"]
    }
  }
}

These same aliases are replicated in the Vitest base configuration for test resolution. See Testing Strategy for details.

Workspace Configuration#

The pnpm-workspace.yaml packages section defines which directories are pnpm workspace packages:

packages:
  - apps/{domain}/* # All apps per domain
  - libs/shared/* # Shared foundation
  - libs/{domain}/* # Domain-specific libs
  - libs/contracts # Cross-domain contracts
  - libs/proto # Protocol Buffers
  - libs/openapi # OpenAPI specs
  - tools/* # Build tools

Further Reading#

• Getting Started - Initial setup with pnpm install
• Adding a New Library - Creating new packages
• Architecture - Monorepo structure