monorepo-ops

Monorepo Operations — Yosemite Crew

Description

Use this skill for any task involving monorepo-level operations: running scripts, adding dependencies, managing shared packages, understanding workspace relationships, or cross-app work.

TRIGGER: tasks spanning multiple apps, dependency changes, turbo commands, pnpm workspace operations, or shared package changes.

---

Workspace Layout

apps/
  frontend/       frontend
  backend/        backend
  desktop/        @yosemite-crew/desktop
  mobileAppYC/    mobileAppYC
  dev-docs/       dev-docs
packages/
  auth/           @yosemite-crew/auth
  database/       @yosemite-crew/database
  design-tokens/  @yosemite-crew/design-tokens (DEAD - never built, zero consumers; live tokens: apps/frontend/src/app/globals.css)
  fhir/           @yosemite-crew/fhir
  fhirtypes/      @yosemite-crew/fhirtypes
  lib/            @yosemite-crew/lib
  types/          @yosemite-crew/types

Tooling: pnpm workspaces + Turbo. Package manager: [email protected].

---

Project Architecture Reference

For architecture decisions, technical narratives, or product-engineering context, read .claude/skills/monorepo-ops/project-baseline.md.

Running Commands

Always use --filter to scope to the relevant workspace. Never run commands at root without --filter unless intentionally affecting all packages.

When the touched workspace is apps/frontend, apply Sonar rules from .claude/skills/frontend-sonar/SKILL.md and run the mandatory frontend check order (tsc -> lint -> targeted tests).

# Dev
pnpm --filter frontend dev
pnpm --filter backend dev

# Build
pnpm --filter frontend build
pnpm turbo build --filter=frontend...   # build frontend + its deps

# Lint
pnpm --filter frontend run lint
pnpm --filter backend run lint

# Type check
pnpm --filter frontend run type-check
# or from within the app:
npx tsc --noemit

# Tests (targeted)
pnpm --filter frontend run test -- --testPathPatterns="ComponentName"
pnpm --filter mobileAppYC run test -- --testPathPatterns="ScreenName"

---

Adding Dependencies

# Add to a specific app
pnpm --filter frontend add <package>
pnpm --filter backend add <package>
pnpm --filter mobileAppYC add <package>

# Add as devDependency
pnpm --filter frontend add -D <package>

# Add to a shared package
pnpm --filter @yosemite-crew/types add <package>

# Add root devDependency (tooling only)
pnpm add -D -w <package>

---

Shared Packages

Two packages deserve special care: @yosemite-crew/database holds the Prisma schema, migrations, and generated client (the schema source of truth), and @yosemite-crew/auth holds the SuperTokens session helpers used by the backend.

When changing packages/types or packages/fhirtypes:

1. Update the type definitions.
2. Build the package you changed: pnpm --filter @yosemite-crew/types build or pnpm --filter @yosemite-crew/fhirtypes build (both have a build script).
3. All consumers (frontend, backend, mobile) pick up changes automatically via workspace links.
4. Run type-check in each affected app.

---

Build Pipeline (Turbo)

turbo.json defines the task graph. Tasks run in dependency order automatically.

pnpm turbo build           # builds all apps in correct order
pnpm turbo build --filter=frontend...  # builds frontend + its dependencies

---

Pre-commit Hooks

Husky + commitlint are configured. Pre-commit runs a staged-secret scan + lint-staged (eslint --fix, prettier, secretlint on staged files); the full monorepo lint + type-check run at pre-push. Commit messages must follow conventional commits:

<type>(<scope>): <subject>
Types: feat | fix | chore | refactor | test | docs | style | perf | ci

Scope allowlist is defined centrally in root AGENTS.md and enforced by commitlint.config.cjs.

Never skip hooks with --no-verify.

---

Secrets Check

secretlint runs on commit. Never commit .env files, API keys, tokens, or private keys.

pnpm run check:secrets   # manual check

---

Gotchas

• pnpm install at the root installs all workspaces. Never run npm install or yarn — pnpm only.
• Hoisting: some packages are hoisted to root node_modules, others are not. If you see resolution errors, check pnpm-workspace.yaml.
• Lock file: always commit pnpm-lock.yaml changes. Never ignore it.
• If turbo cache causes stale output: pnpm turbo build --force to bypass cache.