xtablo-source/DEVELOPMENT.md

# Development Guide

This monorepo uses [Turborepo](https://turbo.build/) to manage builds, development, and testing across multiple packages and applications.

## Repository Structure

```
xtablo-source/
├── apps/
│   ├── main/          # Main application (@xtablo/main)
│   └── external/      # External application (@xtablo/external)
├── packages/
│   ├── shared/        # Shared utilities and logic (@xtablo/shared)
│   └── ui/            # UI component library (@xtablo/ui)
```

## Prerequisites

- Node.js >= 18
- pnpm >= 10.19.0

## Getting Started

```bash
# Install dependencies
pnpm install

# Start development (packages are source-only, no build needed)
pnpm dev
```

## Available Commands

### Building

```bash
# Build all apps (packages are source-only, consumed directly by bundlers)
pnpm build

# Build only apps (main, external)
pnpm build:apps

# Build main app for specific environments
pnpm build:staging    # Build for staging
pnpm build:prod       # Build for production
```

**Note:** The `@xtablo/shared` and `@xtablo/ui` packages are source-only packages. They export TypeScript source files directly and are consumed by app bundlers (Vite) without a separate build step. This is faster and simpler for development.

**Environment Builds:** The main app supports environment-specific builds (`staging`, `production`) that are properly cached by Turborepo based on environment-specific inputs (`.env.staging`, `.env.production`, etc.).

### Development

```bash
# Run all apps in development mode
pnpm dev

# Run specific app
pnpm dev:main      # Main app only
pnpm dev:external  # External app only
```

**Note:** Since packages are source-only, there's no need to run them in watch mode. Changes to package files are instantly picked up by the app's bundler (Vite) through hot module replacement.

### Testing

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests for specific package
cd apps/main && pnpm test
cd apps/main && pnpm test:watch
cd apps/main && pnpm test:coverage
```

### Linting & Formatting

```bash
# Check all packages
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code
pnpm format

# Type checking
pnpm typecheck
```

### Cleaning

```bash
# Clean all build artifacts
pnpm clean

# Clean specific app
cd apps/main && pnpm clean
```

## Turborepo Features

### Smart Caching

Turborepo caches build outputs and skips unnecessary work:

- Build outputs are cached based on input files
- If nothing changed, builds are instant
- Cache is shared across the team (when configured)

### Parallel Execution

Tasks run in parallel when possible:

```bash
# Runs lint on all packages simultaneously
pnpm lint
```

### Task Dependencies

Turborepo automatically handles task dependencies:

- `build` depends on `^build` (builds dependencies first, though packages are source-only)
- Tasks run in topological order based on package dependencies

### Filtering

Run commands for specific packages:

```bash
# Build only main app and its dependencies
turbo build --filter=@xtablo/main

# Build only packages
turbo build --filter='./packages/*'

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

### Package-Level Configuration

Packages can have their own `turbo.json` file to define custom tasks or override root configuration:

**Example:** `apps/main/turbo.json` defines environment-specific builds:

- `build:staging` - Builds for staging with `.env.staging`
- `build:prod` - Builds for production with `.env.production`

Each task:

- Extends the root config with `"extends": ["//"]`
- Defines specific inputs (including environment files)
- Configures caching with appropriate outputs
- Can pass environment variables to the build process

## Package Development Workflow

### 1. Working on Packages

Since packages are source-only, just run your app and edit package files directly:

```bash
# Just run your app - changes to packages are instantly reflected
pnpm dev:main

# Or run all apps
pnpm dev
```

The app's bundler (Vite) will automatically detect changes in `packages/shared` and `packages/ui` and hot-reload them.

### 2. Adding a New Package

1. Create the package in `packages/`
2. For source-only packages (like shared/ui), add these scripts to `package.json`:
   ```json
   {
     "scripts": {
       "lint": "biome check .",
       "lint:fix": "biome check --write .",
       "format": "biome format --write .",
       "typecheck": "tsc --noEmit"
     }
   }
   ```
3. Set up exports in `package.json`:
   ```json
   {
     "main": "./src/index.ts",
     "types": "./src/index.ts",
     "exports": {
       ".": "./src/index.ts"
     }
   }
   ```
4. Add to workspace in `pnpm-workspace.yaml` (if not already included by glob)
5. Run `pnpm install` to link the package

### 3. Testing Changes Across Packages

When making changes that affect multiple packages:

```bash
# Type check everything
pnpm typecheck

# Run all tests
pnpm test

# Lint everything
pnpm lint
```

## Performance Tips

1. **Source-Only Packages**: Packages consume TypeScript directly for instant feedback
2. **Selective Builds**: Use filters to build only the apps you need
3. **Clean When Stuck**: Run `pnpm clean` if you encounter weird caching issues
4. **Hot Module Replacement**: Vite provides instant updates when editing package files

## Troubleshooting

### Build Errors

If you encounter build errors:

```bash
# Clean everything and rebuild
pnpm clean
pnpm install
pnpm build
```

### Type Errors in Apps

If apps show type errors for packages:

```bash
# Check TypeScript configuration in packages
cd packages/shared && pnpm typecheck
cd packages/ui && pnpm typecheck

# Restart your IDE's TypeScript server
# In VS Code: Cmd+Shift+P > "TypeScript: Restart TS Server"
```

### Cache Issues

If builds seem stale:

```bash
# Clear Turbo cache
rm -rf node_modules/.cache/turbo

# Clean and rebuild
pnpm clean
pnpm build
```

## CI/CD Considerations

### Basic Pipeline

For CI/CD pipelines:

```bash
# Install dependencies
pnpm install --frozen-lockfile

# Build everything
pnpm build

# Run all checks
pnpm lint
pnpm typecheck
pnpm test
```

### Environment-Specific Deployments

**Staging Pipeline:**

```bash
# Install dependencies
pnpm install --frozen-lockfile

# Build for staging
pnpm build:staging

# Deploy (example with wrangler)
cd apps/main && pnpm deploy:staging
```

**Production Pipeline:**

```bash
# Install dependencies
pnpm install --frozen-lockfile

# Run all checks
pnpm lint
pnpm typecheck
pnpm test

# Build for production
pnpm build:prod

# Deploy (example with wrangler)
cd apps/main && pnpm deploy:prod
```

**Benefits:**

- Turborepo caches builds per environment
- Environment-specific `.env` files are tracked as inputs
- Builds are only re-run when relevant files change

## Additional Resources

- [Turborepo Documentation](https://turbo.build/repo/docs)
- [pnpm Workspaces](https://pnpm.io/workspaces)
- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)