# Turborepo Workflow

> Manage turborepo monorepo development workflow including dev servers, builds, linting, and package management. Use when running dev, build, lint, deploy, or managing workspace packages in this pnpm + turbo monorepo.

- Skill: `chatbotxio/turborepo-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chatbotxio/turborepo-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chatbotxio/turborepo-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: chatbotxio (https://skillmd.com/u/chatbotxio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chatbotxio/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:

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`)