xtablo-source/docs/TURBO_CHEATSHEET.md

# Turborepo Quick Reference

## 🚀 Quick Start

```bash
pnpm install           # Install dependencies
pnpm dev               # Start development (packages are source-only)
```

## 📦 Package Commands

| Command             | Description                               |
| ------------------- | ----------------------------------------- |
| `pnpm build`        | Build all apps (packages are source-only) |
| `pnpm build:apps`   | Build only apps                           |
| `pnpm dev`          | Start all apps in dev mode                |
| `pnpm dev:main`     | Start main app only                       |
| `pnpm dev:external` | Start external app only                   |
| `pnpm test`         | Run all tests                             |
| `pnpm test:watch`   | Run tests in watch mode                   |
| `pnpm lint`         | Lint all packages                         |
| `pnpm lint:fix`     | Fix linting issues                        |
| `pnpm format`       | Format all code                           |
| `pnpm typecheck`    | Type check everything                     |
| `pnpm clean`        | Clean build artifacts                     |

## 🎯 Turbo Filters

```bash
# Build specific package
turbo build --filter=@xtablo/main
turbo build --filter=@xtablo/shared

# Build all packages in a directory
turbo build --filter='./packages/*'
turbo build --filter='./apps/*'

# Build everything except one package
turbo build --filter='!@xtablo/external'

# Build a package and its dependencies
turbo build --filter=@xtablo/main...

# Build a package and its dependents
turbo build --filter=...@xtablo/shared
```

## 🔧 Package Development

### Work on packages + app

Packages are source-only (no build step), so just run your app:

```bash
# Just run your app - package changes are instantly reflected via HMR
pnpm dev:main

# Edit packages/shared or packages/ui - changes hot-reload automatically
```

### Add dependency to a package

```bash
# Add external dependency
pnpm --filter @xtablo/main add react-query

# Add workspace dependency
pnpm --filter @xtablo/main add @xtablo/shared@workspace:*

# Add dev dependency
pnpm --filter @xtablo/shared add -D typescript
```

## 🧹 Cleanup

```bash
# Clean everything
pnpm clean

# Clean Turbo cache
rm -rf node_modules/.cache/turbo

# Nuclear option (rebuild from scratch)
pnpm clean && pnpm install && pnpm build
```

## 📊 Performance

```bash
# Run with timing
turbo build --summarize

# Run without cache
turbo build --force

# Dry run (see what would run)
turbo build --dry-run
```

## 🐛 Troubleshooting

### "Module not found" errors

```bash
pnpm install         # Reinstall dependencies
pnpm typecheck       # Check for type errors
```

### Type errors in apps

```bash
cd packages/shared && pnpm typecheck
cd packages/ui && pnpm typecheck
# Restart your IDE's TypeScript server
```

### Stale cache

```bash
rm -rf node_modules/.cache/turbo
pnpm clean
pnpm build
```

### Everything broken

```bash
pnpm clean
rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm build
```

## 📝 Common Workflows

### Start new feature

```bash
pnpm dev:main        # Start your app (packages are source-only)
```

### Test changes across packages

```bash
pnpm build           # Build everything
pnpm typecheck       # Check types
pnpm test           # Run tests
pnpm lint           # Check linting
```

### Before committing

```bash
pnpm lint:fix        # Fix linting
pnpm format          # Format code
pnpm typecheck       # Check types
pnpm test           # Run tests
```

## 🏗️ Project Structure

```
xtablo-source/
├── apps/
│   ├── main/        (@xtablo/main) - Main application
│   └── external/    (@xtablo/external) - External booking widget
├── packages/
│   ├── shared/      (@xtablo/shared) - Source-only: utilities, hooks, types
│   └── ui/          (@xtablo/ui) - Source-only: UI components
└── turbo.json       (Turbo configuration)
```

**Note:** Packages are source-only (export TypeScript directly). Apps consume them via Vite bundler.

## 🔗 Useful Links

- [Full Development Guide](./DEVELOPMENT.md)
- [Turborepo Docs](https://turbo.build/repo/docs)
- [pnpm Workspaces](https://pnpm.io/workspaces)