Skip to main content

Development Guide

Prerequisites​

  • Node.js 20+
  • pnpm 9.x
  • Git

Setup​

git clone https://github.com/catesandrew/work-loom.git
cd work-loom
pnpm install
pnpm build

Development commands​

# Build all packages and apps
pnpm build

# Start dev servers (API + web)
pnpm dev

# Run all tests
pnpm test

# Type check
pnpm typecheck

# Clean build artifacts
pnpm clean

Running individual packages​

# Build a specific package
pnpm --filter @workloom/types build

# Test a specific package
pnpm --filter @workloom/registry test

# Dev mode for the API server
pnpm --filter @workloom/api dev

# Dev mode for the web app
pnpm --filter @workloom/web dev

# Build the docs site
pnpm --filter @workloom/docs build

# Dev mode for docs
pnpm --filter @workloom/docs start

Testing​

All packages use Vitest. Tests live alongside source code in __tests__/ directories or in test/ directories.

# Run all tests
pnpm test

# Run tests for one package
pnpm --filter @workloom/renderer-claude test

# Watch mode
pnpm --filter @workloom/registry exec vitest --watch

Build order​

Turborepo handles build ordering automatically. The dependency graph is:

types → manifest → workspace
types → storage → registry
types → renderer-core → renderer-claude
types → renderer-core → renderer-codex
types → renderer-core → renderer-copilot
types → renderer-core → renderer-gemini
types → auth
types → drift
types → sync (depends on renderer-core)

environment (standalone — no internal deps)
config (standalone — dotenv loading)
fetch-client (standalone — native fetch wrapper)
react-query (standalone — TanStack wrapper)
database (depends on types)
workloom-api (depends on fetch-client, react-query)

api depends on: auth, database, registry, workspace, renderer-claude, renderer-codex, renderer-copilot, renderer-gemini, config, environment
cli depends on: auth, manifest, registry, workspace, renderer-claude, renderer-codex, renderer-copilot, renderer-gemini, drift, sync
web depends on: react-query, workloom-api, fetch-client, environment
docs depends on: (standalone)

Adding a new package​

  1. Create directory under packages/
  2. Add package.json with @workloom/ scope
  3. Add tsconfig.json extending root config
  4. Add src/index.ts with exports
  5. Run pnpm install to link the workspace
  6. Add build/test scripts
  7. Reference from consuming packages

Code style​

  • TypeScript strict mode
  • No any types
  • Prefer interfaces over type aliases for object shapes
  • Zod for runtime validation at boundaries
  • Vitest for tests