Development

Daily development workflows, tools, and best practices

📋 Overview

This section covers everything you need for day-to-day development with Izri, from setting up your local environment to debugging complex issues. Whether you're fixing bugs, adding features, or optimizing performance, you'll find the guidance you need here.

🎯 What You'll Learn

• ✅ How to set up your development environment
• ✅ Managing environment variables and configuration
• ✅ Running and managing services
• ✅ Database operations and migrations
• ✅ Debugging techniques and tools
• ✅ Testing strategies and execution
• ✅ Code quality and linting

📚 Documentation Pages

Local Setup

Complete development environment configuration

Topics covered:

• IDE setup (VS Code recommended)
• Extensions and plugins
• Git configuration
• Shell setup and aliases
• Performance optimization
• Recommended tools

Environment Variables

Managing configuration across services

Topics covered:

• Environment file structure
• Required vs optional variables
• Service-specific configuration
• Secrets management
• Development vs production configs
• Environment variable reference

Environment Management

Automated environment variable management system

Topics covered:

• Centralized .env.shared configuration
• Auto-generation of project-specific .env files
• TypeScript configuration with type safety
• Validation and watch mode
• CI/CD integration

Utility Scripts

Automation scripts and development tools

Topics covered:

• Available utility scripts
• Creating new scripts
• TypeScript script templates
• Best practices and patterns
• Common script examples
• Debugging scripts

Running Services

Starting, stopping, and managing development services

Topics covered:

• Starting all services
• Running individual services
• Service dependencies
• Port management
• Logs and output
• Restart and reload strategies
• Process management

Database Management

Working with PostgreSQL and Drizzle ORM

Topics covered:

• Schema development
• Migration workflow
• Seeding and test data
• Drizzle Studio usage
• Database inspection
• Backup and restore
• Query optimization
• Troubleshooting connections

Debugging

Techniques and tools for troubleshooting

Topics covered:

• Frontend debugging (React DevTools, Vite inspect)
• Backend debugging (Node.js inspector, logs)
• Database debugging (query logs, Drizzle Studio)
• Network debugging (tRPC traces, HTTP inspector)
• Performance profiling
• Common issues and solutions

Testing

Testing strategies and running tests

Topics covered:

• Test structure and organization
• Unit testing
• Integration testing
• E2E testing (planned)
• Test data management
• Running tests
• Coverage reports
• CI/CD integration

🚀 Quick Reference

Daily Commands

# Start everything
pnpm dev

# Start individual services
pnpm dev:web        # Frontend only
pnpm dev:api        # Backend only
pnpm dev:packages   # All packages (including AI service)

# Infrastructure
pnpm dev:docker     # Start PostgreSQL & Redis
pnpm docker:down    # Stop Docker services
pnpm docker:logs    # View Docker logs

# Database
pnpm db:studio      # Open Drizzle Studio
pnpm db:generate    # Generate migrations
pnpm db:migrate     # Apply migrations
pnpm db:seed        # Seed test data

# Environment
pnpm env:generate   # Generate .env files from .env.shared
pnpm env:check      # Check if .env files are up to date
pnpm env:watch      # Watch and auto-regenerate .env files

# Code quality
pnpm lint           # Run linting
pnpm type:check     # TypeScript check
pnpm format:all     # Format code
pnpm test           # Run tests

# Building
pnpm build          # Build all packages
pnpm clean          # Clean build artifacts

Service Ports

Environment Files

Note: Never edit generated .env files directly. Always update .env.shared and run pnpm env:generate.

🔧 Development Workflow

Typical Development Day

# 1. Start your day - pull latest changes
git pull origin main

# 2. Install any new dependencies
pnpm install

# 3. Apply any new migrations
pnpm db:migrate

# 4. Start infrastructure
pnpm dev:docker

# 5. Start all services
pnpm dev

# 6. Open your editor and start coding
code .

# 7. Make changes, test, commit, push
git add .
git commit -m "feat: add new feature"
git push

# 8. End your day - stop services
# Ctrl+C to stop pnpm dev
pnpm docker:down

Feature Development Workflow

graph TD
    A[Create Feature Branch] --> B[Make Changes]
    B --> C{Need DB Changes?}
    C -->|Yes| D[Update Schema]
    C -->|No| E[Write Code]
    D --> F[Generate Migration]
    F --> E
    E --> G[Test Locally]
    G --> H{Tests Pass?}
    H -->|No| B
    H -->|Yes| I[Commit Changes]
    I --> J[Push Branch]
    J --> K[Create PR]

Database Change Workflow

# 1. Update schema
# Edit packages/database/src/schema.ts

# 2. Generate migration
pnpm db:generate

# 3. Review generated SQL
# Check packages/database/migrations/

# 4. Apply migration locally
pnpm db:migrate

# 5. Test the changes
pnpm db:studio  # Verify schema

# 6. Update seed script if needed
# Edit packages/database/src/seed.ts

# 7. Test seeding
pnpm db:seed

# 8. Commit migration files
git add packages/database/migrations/
git commit -m "feat: add new table"

🐛 Common Development Tasks

Adding a New Package Dependency

# Add to specific workspace package
pnpm --filter @izri/web add react-query

# Add to all packages
pnpm add -w some-shared-tool

# Add as dev dependency
pnpm --filter @izri/api add -D @types/node

Creating a New Workspace Package

# 1. Create package directory
mkdir packages/my-new-package

# 2. Create package.json
cd packages/my-new-package
pnpm init

# 3. Update package.json with workspace config
# Add "name": "@izri/my-new-package"

# 4. Create src/ and tsconfig.json

# 5. Add to pnpm-workspace.yaml (if needed)

# 6. Install from root
cd ../..
pnpm install

Clearing Cache and Rebuilding

# Nuclear option - complete clean
pnpm clean
rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install
pnpm build

# Turbo cache clean
rm -rf .turbo

# pnpm store clean
pnpm store prune

# Docker volume clean
pnpm docker:down -v

🎯 IDE Setup

VS Code (Recommended)

Required Extensions:

• ESLint
• Prettier - Code formatter
• TypeScript and JavaScript Language Features
• Tailwind CSS IntelliSense

Recommended Extensions:

• Docker
• Database Client JDBC
• GitLens
• Error Lens
• Auto Rename Tag
• Path Intellisense

Settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

📊 Performance Tips

Build Performance

# Use Turbo caching
pnpm build  # First build: ~20s
pnpm build  # Cached build: <5s

# Build only what changed
pnpm build --filter=@izri/web

# Skip type checking for faster builds (dev only)
# Edit tsconfig.json: "skipLibCheck": true

Development Server Performance

# Use pnpm workspace links
# Already configured in package.json

# Enable SWC/ESBuild if available
# Already using Vite with ESBuild

# Reduce file watching
# Add to .gitignore: node_modules, .turbo, dist, lib

🔗 Related Documentation

• Getting Started: Installation Guide
• Architecture: System Overview
• Frontend: Frontend Development
• Backend: Backend Development

🆘 Troubleshooting

Services Won't Start

1. Check if ports are available: lsof -ti:5173
2. Ensure Docker is running: docker ps
3. Check environment variables: cat .env
4. Review logs for errors: pnpm docker:logs

Build Errors

1. Clean and rebuild: pnpm clean && pnpm install && pnpm build
2. Check Node version: node --version (should be 18+)
3. Check pnpm version: pnpm --version (should be 8+)
4. Clear Turbo cache: rm -rf .turbo

Database Connection Issues

1. Ensure PostgreSQL is running: docker ps | grep postgres
2. Check DATABASE_URL in .env
3. Restart Docker: pnpm docker:down && pnpm dev:docker
4. Check migrations: pnpm db:migrate

Ready to dive deep? Start with Local Setup →