Skip to content
Keepin' Tracks Dev

ADR-001: Use Bun workspaces

ADR-001: Use Bun workspaces for the monorepo

Section titled “ADR-001: Use Bun workspaces for the monorepo”
  • Status: Accepted
  • Date: 2026-05-28
  • Deciders: Keepin’ Tracks engineering
  • Supersedes: —
  • Superseded by: —

Context

Section titled “Context”

Keepin’ Tracks is a Turborepo monorepo with multiple apps (marketing, personal-*, business-*, docs) and shared packages. We need a fast, consistent package manager for local development and CI.

Node.js with npm, pnpm, or Yarn are all viable. Bun provides native workspace support, fast installs, and a single runtime/toolchain for scripts.

Decision

Section titled “Decision”

Use Bun workspaces with a root package.json workspaces field and Turborepo for task orchestration.

  • Install: bun install
  • Run tasks: bun dev, bun --filter <app> dev
  • CI and local dev use the same commands

Consequences

Section titled “Consequences”

Positive

Section titled “Positive”
  • Fast installs and script execution
  • One toolchain (Bun) for package management and running scripts
  • Aligns with Phase 0 foundation goals in ARCHITECTURE.md

Negative

Section titled “Negative”
  • Team members must install Bun
  • Some Node-only tooling may need compatibility checks

Follow-ups

Section titled “Follow-ups”
  • Pin Bun version in packageManager field when CI is added
  • Document Bun setup in developer onboarding

References

Section titled “References”