Deps

Dependency Management Rules

Bun Catalog — Promotion Policy

A package version belongs in the root package.json "catalog" section only if it is a runtime/peer dependency used in 2 or more workspaces (apps/* or packages/*).

Promote to catalog when:

• The same package appears as a dependency or peerDependency in ≥ 2 apps/* or packages/* package.json files.
• Reference it as "catalog:" in each workspace that uses it.

Do NOT put in catalog:

• A package used in only one app or package — keep the explicit version there.
• Dev tooling (typescript, vitest, wrangler, drizzle-kit, auth, @biomejs/biome, @cloudflare/workers-types) — these live in root devDependencies directly so all workspaces inherit them via Bun workspace resolution.

Current catalog entries (update this list when adding/removing):

• better-auth — @packages/auth, @apps/web, @packages/db (seed script password hashing)
• drizzle-orm — @packages/db, @packages/auth, @packages/service, @apps/web
• zod — @packages/db, @packages/auth, @packages/service, @apps/web, @packages/contract
• @tigorhutasuhut/telemetry-js — @packages/service, @apps/web

Single-workspace packages (not in catalog — used by exactly one workspace):

• @orpc/contract — @packages/contract only
• @orpc/server, @orpc/openapi — @apps/web only

Global Tooling — Root Only

The following are installed only in root devDependencies. Never add them to individual workspace package.json files:

• typescript — tsc available everywhere via Bun workspace bin resolution
• vitest — test runner
• wrangler — CF Workers deploy/dev
• drizzle-kit — DB migrations
• auth — Better Auth CLI (auth generate / migrate); installed locally because the isolated npx/bunx form can’t resolve the workspace’s better-auth (see schema.md)
• @biomejs/biome — lint + format
• @cloudflare/workers-types — CF Workers type declarations

Adding a New Dependency

1. Identify which workspace(s) need it.
2. If 1 workspace: add with explicit version to that workspace’s package.json.
3. If 2+ workspaces: add to root catalog, reference as "catalog:" in each workspace, update the catalog entries list above.
4. Run bun install from repo root.