Skip to main content

ADR-002 — Repo layout: pnpm workspace monorepo

canonical · tech-lead · updated 2026-06-28 · source

  • Status: Accepted
  • Date: 2026-05-20
  • Owner: Tech Lead
  • Related issue: #6 (repo scaffold + ADRs)

Context​

  • We ship two runtimes (desktop Tauri app + Node backend) that share types, validators, and constants.
  • Solo / tiny team — overhead of multi-repo (cross-repo PRs, version drift, CI duplication) is not worth it.
  • Desktop client and API will move together for the entire MVP roadmap (P1 → P3).
  • TypeScript path resolution + Tailwind v4 + Tauri v2 all play well with workspaces.

Decision​

  • Adopt a pnpm workspace monorepo rooted at this repo.
  • File tree:
.
├── apps/
│   ├── desktop/          # Tauri v2 + React 19 + Vite + Tailwind v4
│   │   ├── src/
│   │   ├── src-tauri/
│   │   ├── index.html
│   │   └── package.json  # @tedos/desktop
│   └── api/              # Fastify + Drizzle
│       ├── src/
│       └── package.json  # @tedos/api
├── packages/
│   └── shared/           # types, validators, constants
│       ├── src/
│       └── package.json  # @tedos/shared
├── pnpm-workspace.yaml
├── tsconfig.base.json
└── package.json          # root scripts
  • Package names use the @tedos/* scope ("Tu Empresa Digital OS").
  • @tedos/shared is consumed via workspace protocol ("workspace:*").
  • TS path alias @tedos/shared → packages/shared/src resolved by tsconfig.base.json.

Out of scope here: publishing strategy (we do not publish to npm), Turborepo / Nx (not added for MVP).

Consequences​

Positive

  • One install, one lockfile, one CI graph.
  • Atomic PRs touching desktop + api + shared types.
  • pnpm symlinks keep node_modules small and fast.
  • Easy to add apps/marketing (landing) or apps/admin later.

Negative / trade-offs

  • All contributors must use pnpm (not npm/yarn) — enforced via packageManager field + .npmrc.
  • Workspace tooling adds a small learning curve (pnpm -F @tedos/api dev vs cd apps/api && npm dev).
  • No build orchestrator yet — pnpm -r is fine until parallelism / caching matters; revisit with Turborepo at P2.

Follow-ups required

  • Migrate existing src/ → apps/desktop/src/ and existing src-tauri/ → apps/desktop/src-tauri/ (this issue).
  • CI workflow (DevOps) must use pnpm install --frozen-lockfile and matrix by workspace.

Alternatives considered​

OptionWhy not
Single package, no workspacesBackend code would force install of Vite, Tauri, React in production server image. Shared types would need npm publishing or git submodule.
Multiple repos (-desktop, -api, -shared)Cross-repo PRs and version drift kill solo velocity. Wrong tool until we have a team.
Nx / Turborepo from day 1Premature — pnpm -r is enough until we have ≥4 packages or slow CI.
npm workspacesSlower install, no pnpm -F filtering, worse hoisting; pnpm is now the default choice for TS monorepos.
Bun workspacesBun's workspace resolution still has edge cases with native modules; not worth the risk.

References​

  • knowledge/tedos-implementation-plan.md — phasing requires shared types between desktop and api.
  • pnpm workspaces: https://pnpm.io/workspaces
  • ADR-001 (backend stack) — co-deployed package needs.