Turborepo Workflow

Turborepo Workflow

Project Overview

Monorepo managed by pnpm workspaces + Turborepo. Node >= 24, TypeScript 5.

Workspace Layout

The authoritative layout table is AGENTS.md → "Repository layout". A hand-copied tree here would drift (and did) — list the real thing instead:

ls apps packages integrations
pnpm ls -r --depth -1        # every workspace package with its name

Ports worth knowing: builder 3123, realtime 1999.

Common Commands

Development

# Start all apps in dev mode
pnpm dev

# Start specific app
pnpm --filter builder dev
pnpm --filter worker dev

# Start with HTTPS
pnpm --filter builder https

Build & Lint

# Build all packages (respects turbo dependency graph)
pnpm build

# Lint (uses Biome via Ultracite)
pnpm lint
pnpm fix          # auto-fix

# Type checking
pnpm --filter builder check-types

Database

# Full setup (migrate + seed)
pnpm --filter database db:setup

# Migration only
pnpm --filter database db:migrate

# Create new migration
pnpm --filter database make:migration <name>

# Studio (GUI)
pnpm --filter database db:studio

Code Quality

# Check circular dependencies
pnpm check:circular

# Check unused exports (knip)
pnpm check:unused

Package Management

• Use pnpm add <pkg> --filter <workspace> to add dependencies to specific workspace
• Workspace packages use @chatbotx.io/* scope
• Cross-workspace imports must go through a package's exports map: @chatbotx.io/database/client, @chatbotx.io/ui/components/ui/button (the UI package exports ./components/*, ./lib/*, ./hooks/*, … — there is no bare @chatbotx.io/ui/button).
• Package exports are defined in each package.json exports field

Adding a New Workspace Package

When creating a new package (e.g. integrations/<channel>/):

1. Create package.json with "name": "@chatbotx.io/<name>"
2. Add "@chatbotx.io/<name>": "workspace:*" to consumer package.json dependencies
3. Run CI=true pnpm install --no-frozen-lockfile to link the package
   • MUST use CI=true to avoid TTY confirmation prompt in non-interactive shells
   • Without this step, imports of the new package will fail with Cannot find module

Turbo Pipeline

Defined in turbo.json:

• build depends on ^build (builds dependencies first), outputs .next/**, dist/**
• dev, https, packages:dev are persistent (long-running)
• db:migrate, db:setup, db:reset, db:studio are non-cached
• build does NOT type-check the builder: next build runs with typescript.ignoreBuildErrors: true (the in-build tsc pass duplicated check-types and OOMed a 4GB heap). A green build proves nothing about types — always run pnpm --filter builder check-types (or pnpm turbo run check-types). CI enforces this in .github/workflows/ci.yml, and release.yml's check job gates image publishing on the same command set.

Environment

• Root .env file is loaded by apps via dotenv -e ../../.env
• Env validation uses @t3-oss/env-core + Zod in keys.ts files
• SKIP_ENV_CHECK=true to bypass validation during build

Git Hooks

• lefthook manages pre-commit hooks (see lefthook.yml)