Local Development

Guide to setting up and running the monorepo locally.

Initial Setup

# Clone the repo
git clone <repo-url>
cd emerge-turbo

# Install dependencies and start Redis
pnpm setup:developer

This runs pnpm install and starts a local Redis server.

Environment System

The monorepo uses a profile-based environment system that consolidates scattered .env files into unified configs.

Environment Profiles

Profiles live in config/environments/:

config/environments/
├── secrets/          # Encrypted secrets (git-crypt)
│   ├── local.env
│   ├── staging.env
│   └── production.env
├── base.env          # Shared base config
├── local.env         # Local development overrides
├── staging.env       # Staging overrides
└── production.env    # Production overrides

Building Environment Files

# List available profiles
pnpm env:list

# Build .env files for a profile
pnpm env:build

The env:build command:

1. Reads the profile (local/staging/production)
2. Merges base + profile + secrets
3. Writes consolidated .env files to each package that needs them

Profile Hierarchy

base.env           # Shared defaults
    ↓
{profile}.env      # Profile-specific overrides
    ↓
secrets/{profile}.env  # Secrets (git-crypt encrypted)

Database Credentials

Database and Redis credentials are stored in:

packages/database/.env.{profile}

Each file contains:

• DATABASE_URL - PostgreSQL connection (pooled)
• DIRECT_URL - PostgreSQL direct connection (migrations)
• REDIS_URL - Redis connection string

Development Dashboard

# Start Zellij-based dev dashboard
pnpm env:start

This opens a terminal multiplexer with:

• API server logs
• Worker logs
• Redis monitoring
• File watchers

Running Services

Local Redis

# Start Redis
pnpm dev:redis

# Stop Redis
pnpm dev:redis:stop

Full Stack

# Start everything (Redis + all services)
pnpm dev:all

# Stop everything
pnpm dev:all:stop

Individual Services

# Run turbo dev for all packages
pnpm dev

Or run specific apps via turbo:

turbo run dev --filter=@emp/api
turbo run dev --filter=@emp/monitor

Machine Development

For working on the GPU worker machine:

# Start local ComfyUI dev container
pnpm dev:machine

# View logs
pnpm dev:machine:logs

# Stop
pnpm dev:machine:down

Working with Worktrees

For parallel feature development:

# Create a new worktree
pnpm worktree:create

# Setup environment in worktree
pnpm worktree:setup

See CLAUDE.md for tmux orchestration patterns.

Common Workflows

Adding a New Package

1. Create directory in packages/ or apps/
2. Add package.json with proper name (@emp/package-name)
3. Run pnpm install to link
4. Add to turbo.json if needed

Updating Dependencies

# Update all packages
pnpm update

# Update specific package
pnpm update lodash --filter @emp/core

Cleaning Build Artifacts

# Full clean (removes node_modules too)
pnpm clean

# Just turbo cache
turbo clean

Troubleshooting

Build Failures

# Force rebuild with no cache
pnpm build --force

# Check specific package
turbo run build --filter=@emp/core --force

Type Errors

# Run type checking
pnpm typecheck

# Check specific package
turbo run typecheck --filter=@emp/api

Redis Issues

# Check if Redis is running
redis-cli ping

# Restart Redis
pnpm dev:redis:stop && pnpm dev:redis