# Local Development Setup

> Complete guide to setting up your development environment for Izri

## 📋 Overview

This guide walks you through setting up your IDE, tools, and development workflow for productive work on Izri. After completing this guide, you'll have a fully configured development environment with intelligent code completion, debugging, and testing capabilities.

## 🎯 What You'll Set Up

- ✅ IDE (VS Code recommended)
- ✅ Editor extensions and plugins
- ✅ Code formatting and linting
- ✅ TypeScript configuration
- ✅ Debugging configurations
- ✅ Git hooks (optional)
- ✅ Productivity tools

## 💻 IDE Setup: Visual Studio Code

### Why VS Code?

VS Code is recommended for Izri development because:

- Excellent TypeScript support
- Rich React ecosystem
- Built-in terminal and debugger
- Monorepo support
- Large extension marketplace

**Other Options**: WebStorm, Cursor, Zed also work well.

### Installation

**macOS**:

```bash
brew install --cask visual-studio-code
```

**Linux**:

```bash
# Ubuntu/Debian
sudo snap install --classic code

# Or download from: https://code.visualstudio.com/
```

**Windows**:

- Download from [code.visualstudio.com](https://code.visualstudio.com/)

### Opening the Project

```bash
# Navigate to project
cd /path/to/izri

# Open in VS Code
code .

# Or open the workspace file (recommended)
code izri.code-workspace
```

**Using the workspace file** ensures all settings and folder configurations are loaded correctly.

## 🔌 Essential Extensions

Install these extensions for the best development experience:

### Required Extensions

**TypeScript & JavaScript**:

```
Name: TypeScript Vue Plugin (Volar)
ID: Vue.vscode-typescript-vue-plugin
```

**React**:

```
Name: ES7+ React/Redux/React-Native snippets
ID: dsznajder.es7-react-js-snippets
```

**Tailwind CSS**:

```
Name: Tailwind CSS IntelliSense
ID: bradlc.vscode-tailwindcss
```

**ESLint**:

```
Name: ESLint
ID: dbaeumer.vscode-eslint
```

**Biome** (for formatting):

```
Name: Biome
ID: biomejs.biome
```

### Highly Recommended

**Path Autocomplete**:

```
Name: Path Intellisense
ID: christian-kohler.path-intellisense
```

**Better Comments**:

```
Name: Better Comments
ID: aaron-bond.better-comments
```

**Error Lens** (inline errors):

```
Name: Error Lens
ID: usernamehw.errorlens
```

**Import Cost** (see bundle impact):

```
Name: Import Cost
ID: wix.vscode-import-cost
```

**Git Lens**:

```
Name: GitLens
ID: eamodio.gitlens
```

**Docker**:

```
Name: Docker
ID: ms-azuretools.vscode-docker
```

**Database Client**:

```
Name: Database Client
ID: cweijan.vscode-database-client2
```

### Install All at Once

Copy this command to install all essential extensions:

```bash
code --install-extension Vue.vscode-typescript-vue-plugin \
     --install-extension dsznajder.es7-react-js-snippets \
     --install-extension bradlc.vscode-tailwindcss \
     --install-extension dbaeumer.vscode-eslint \
     --install-extension biomejs.biome \
     --install-extension christian-kohler.path-intellisense \
     --install-extension aaron-bond.better-comments \
     --install-extension usernamehw.errorlens \
     --install-extension wix.vscode-import-cost \
     --install-extension eamodio.gitlens \
     --install-extension ms-azuretools.vscode-docker \
     --install-extension cweijan.vscode-database-client2
```

## ⚙️ VS Code Configuration

The project includes workspace settings in `izri.code-workspace`. Here are the key configurations:

### Workspace Settings

Create or verify `.vscode/settings.json`:

```json
{
  // Editor
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "editor.codeActionsOnSave": {
    "quickfix.biome": "explicit",
    "source.organizeImports.biome": "explicit"
  },
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.rulers": [80, 120],

  // TypeScript
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true,
  "typescript.preferences.importModuleSpecifier": "relative",
  
  // JavaScript/TypeScript
  "[javascript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescript]": {
    "editor.defaultFormatter": "biomejs.biome"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "biomejs.biome"
  },

  // JSON
  "[json]": {
    "editor.defaultFormatter": "biomejs.biome"
  },

  // Files
  "files.exclude": {
    "**/.turbo": true,
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true,
    "**/.next": true
  },
  
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/.git/subtree-cache/**": true,
    "**/node_modules/*/**": true,
    "**/.turbo/**": true
  },

  // Search
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true,
    "**/.turbo": true,
    "**/pnpm-lock.yaml": true
  },

  // ESLint
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // Tailwind
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],

  // Terminal
  "terminal.integrated.defaultProfile.osx": "zsh",
  "terminal.integrated.fontSize": 13,
  
  // Git
  "git.autofetch": true,
  "git.confirmSync": false
}
```

### Recommended Keybindings

Add to `.vscode/keybindings.json`:

```json
[
  // Quick file navigation
  {
    "key": "cmd+p",
    "command": "workbench.action.quickOpen"
  },
  // Search in project
  {
    "key": "cmd+shift+f",
    "command": "workbench.action.findInFiles"
  },
  // Format document
  {
    "key": "cmd+shift+p",
    "command": "editor.action.formatDocument"
  }
]
```

## 📁 Workspace Structure

The workspace file (`izri.code-workspace`) organizes folders for easy navigation:

```json
{
  "folders": [
    {
      "name": "🏠 Root",
      "path": "."
    },
    {
      "name": "🌐 Web App",
      "path": "apps/web"
    },
    {
      "name": "🔌 API Server",
      "path": "apps/api"
    },
    {
      "name": "📦 Packages",
      "path": "packages"
    },
    {
      "name": "📚 Documentation",
      "path": "docs"
    }
  ],
  "settings": {
    // Workspace-level settings
  }
}
```

## 🔧 Code Formatting Setup

### Biome Configuration

The project uses **Biome** for fast, consistent formatting. Configuration is in `biome.json`:

```json
{
  "$schema": "https://biomejs.dev/schemas/1.5.3/schema.json",
  "organizeImports": {
    "enabled": true
  },
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true
    }
  },
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80
  }
}
```

### Format on Save

Ensure VS Code settings have:

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome"
}
```

### Manual Formatting

```bash
# Format entire project
pnpm format:code

# Format and fix imports
pnpm format:imports

# Format everything
pnpm format:all
```

## 🔍 Linting Setup

### ESLint Configuration

The project uses ESLint for additional TypeScript/React checks.

**Check for issues**:

```bash
# Lint all packages
pnpm lint

# Lint specific app
cd apps/web
pnpm lint
```

### Auto-fix on Save

VS Code can auto-fix ESLint issues:

```json
{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}
```

## 🎨 Tailwind CSS IntelliSense

### Setup

The Tailwind extension provides autocomplete for CSS classes.

**Configuration** (already in workspace settings):

```json
{
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}
```

This enables IntelliSense for:

- Regular `className` props
- `cva()` class variance authority
- `cn()` utility function

### Usage

Start typing class names in JSX:

```tsx
<div className="flex items-|" />
         Autocomplete triggers here ↑
```

## 📊 Database Client Setup

### Using Database Client Extension

1. **Install Extension**: `cweijan.vscode-database-client2`

2. **Add Connection**:
   - Click database icon in sidebar
   - Click "+" to add connection
   - Select "PostgreSQL"

3. **Connection Details**:

   ```
   Host: localhost
   Port: 5433
   Database: izri_dev
   Username: postgres
   Password: postgres
   ```

4. **Save Connection**

Now you can:

- Browse tables and schemas
- Run SQL queries
- View table data
- Export results

### Alternative: Using Drizzle Studio

```bash
# Start Drizzle Studio (better for schema visualization)
pnpm db:studio
```

Opens at `https://local.drizzle.studio`

## 🔬 TypeScript Configuration

### Workspace TypeScript

Ensure VS Code uses the workspace TypeScript:

1. Open any `.ts` or `.tsx` file
2. Click TypeScript version in status bar (bottom right)
3. Select "Use Workspace Version"

Should show: `TypeScript 5.3.x`

### Type Checking

```bash
# Check types across all workspaces
pnpm type:check

# Check only apps
pnpm type:check:apps

# Check only packages
pnpm type:check:packages
```

### Auto-Imports

VS Code can auto-import types and functions:

```typescript
// Type "useQuery" then select the import
import { useQuery } from '@tanstack/react-query'
```

**Configure import style**:

```json
{
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.preferences.quoteStyle": "single"
}
```

## 🏗️ Monorepo Navigation

### Quick File Switching

**Keyboard shortcuts**:

- `Cmd+P` (Mac) / `Ctrl+P` (Win/Linux): Quick file search
- Type `@` to see symbols in current file
- Type `#` to see symbols in workspace

**Search in specific folder**:

```
# Search only in web app
apps/web/ <search term>

# Search in packages
packages/ <search term>
```

### Multi-Root Workspace

The workspace file creates a multi-root setup:

- Each folder appears as a separate root
- Navigate between apps/packages easily
- Run commands per-folder

**Run tasks per folder**:

1. Open integrated terminal
2. Click folder dropdown (top right of terminal)
3. Select which folder context to run in

## 🎯 Snippets and Shortcuts

### React Component Snippet

Type `rfc` + Tab:

```typescript
import React from 'react'

export default function ComponentName() {
  return (
    <div>
      
    </div>
  )
}
```

### tRPC Procedure Snippet

Create `.vscode/snippets.code-snippets`:

```json
{
  "tRPC Query": {
    "prefix": "trpcquery",
    "body": [
      "${1:name}: publicProcedure",
      "  .input(z.object({",
      "    ${2:field}: z.string()",
      "  }))",
      "  .query(async ({ ctx, input }) => {",
      "    ${3:// Implementation}",
      "  })"
    ]
  }
}
```

## 🐛 Debugging Setup

Debugging is covered in detail in [`debugging.md`](./debugging.md), but here's the basic `.vscode/launch.json`:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Web App",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["dev:web"],
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "Debug API Server",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "pnpm",
      "runtimeArgs": ["dev:api"],
      "cwd": "${workspaceFolder}",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}
```

See [Debugging Guide](./debugging.md) for complete setup.

## 🪝 Git Hooks (Optional)

### Setup Husky

Install pre-commit hooks to ensure code quality:

```bash
# Install husky
pnpm add -D husky

# Initialize
pnpm exec husky init

# Add pre-commit hook
echo "pnpm lint && pnpm type:check" > .husky/pre-commit
```

### What Runs on Commit

- ✅ Linting (ESLint + Biome)
- ✅ Type checking (TypeScript)
- ✅ Format checking

**Skip hooks** (when needed):

```bash
git commit --no-verify -m "WIP: experiment"
```

## 🚀 Performance Tips

### Speed Up Development

**1. Use Turbo Cache**:

Turbo caches build outputs. First build is slow, subsequent builds are fast.

```bash
# Clear cache if issues
rm -rf .turbo
pnpm build
```

**2. Exclude Folders from Indexing**:

Prevent VS Code from indexing unnecessary files:

```json
{
  "files.watcherExclude": {
    "**/node_modules/*/**": true,
    "**/.turbo/**": true
  }
}
```

**3. Increase Node Memory** (for large builds):

```bash
# Add to ~/.zshrc or ~/.bashrc
export NODE_OPTIONS="--max-old-space-size=4096"
```

**4. Use pnpm Efficiently**:

```bash
# Install in specific workspace
pnpm add <package> --filter @izri/web

# Don't run from root unnecessarily
cd apps/web
pnpm dev  # Faster than pnpm dev:web from root
```

## 📝 Code Quality Tools

### Inline Checks

**Error Lens** extension shows errors inline:

```typescript
const x: string = 123  // ❌ Type 'number' is not assignable to type 'string'
```

**Import Cost** shows bundle size:

```typescript
import lodash from 'lodash'  // 💰 72.5kB (gzipped: 25.4kB)
```

### Pre-Push Checklist

Before pushing code:

```bash
# 1. Format
pnpm format:all

# 2. Lint
pnpm lint

# 3. Type check
pnpm type:check

# 4. Build verification
pnpm build
```

Or use a combined script (add to root `package.json`):

```json
{
  "scripts": {
    "precommit": "pnpm format:all && pnpm lint && pnpm type:check"
  }
}
```

## 🔗 Terminal Setup

### Integrated Terminal

**Split terminals** for parallel work:

```
Terminal 1: pnpm dev:web
Terminal 2: pnpm dev:api
Terminal 3: Git commands
Terminal 4: Database studio
```

**Quick terminal shortcuts**:

- `Ctrl+` ` `: Toggle terminal
- `Cmd+Shift+5`: Create new terminal
- `Cmd+\`: Split terminal

### External Terminal (Optional)

Some developers prefer external terminals:

**macOS**: iTerm2 with tmux
**Linux**: Terminator or Tilix
**Windows**: Windows Terminal

## 🎓 Learning Resources

### VS Code

- [VS Code Tips](https://code.visualstudio.com/docs/getstarted/tips-and-tricks)
- [Keyboard Shortcuts PDF](https://code.visualstudio.com/shortcuts/keyboard-shortcuts-macos.pdf)

### TypeScript in VS Code

- [TypeScript Tutorial](https://code.visualstudio.com/docs/typescript/typescript-tutorial)
- [React with TypeScript](https://react-typescript-cheatsheet.netlify.app/)

## 🐛 Troubleshooting

### VS Code Issues

**Problem**: TypeScript errors not showing

**Solution**:

```bash
# Restart TS server
Cmd+Shift+P → "TypeScript: Restart TS Server"

# Clear VS Code cache
rm -rf ~/.vscode
```

**Problem**: Slow IntelliSense

**Solution**:

```json
{
  "typescript.tsserver.maxTsServerMemory": 4096,
  "typescript.disableAutomaticTypeAcquisition": true
}
```

**Problem**: Import auto-completion not working

**Solution**:

- Ensure `tsconfig.json` has correct `paths`
- Restart VS Code
- Run `pnpm install` to update `.pnpm` structure

### Extension Issues

**Problem**: Biome not formatting

**Solution**:

```bash
# Check Biome is installed
pnpm list @biomejs/biome

# Reinstall if needed
pnpm add -D @biomejs/biome

# Restart VS Code
```

### Workspace Issues

**Problem**: Wrong folder context

**Solution**:

- Always open `izri.code-workspace` file
- Don't open individual folders directly

## ✅ Verification Checklist

After setup, verify everything works:

- [ ] VS Code opens workspace correctly
- [ ] TypeScript IntelliSense working
- [ ] Format on save working (Biome)
- [ ] ESLint showing errors
- [ ] Tailwind autocomplete working
- [ ] Database client can connect
- [ ] Debugging configuration present
- [ ] Terminal shortcuts working
- [ ] Git integration working

## 📚 Next Steps

Now that your environment is set up:

1. **Learn the workflow**: [Running Services](./running-services.md)
2. **Debug issues**: [Debugging Guide](./debugging.md)
3. **Write tests**: [Testing Guide](./testing.md)
4. **Explore codebase**: [Monorepo Structure](../architecture/monorepo-structure.md)

## 🔗 Related Documentation

- [Prerequisites](../getting-started/prerequisites.md) - Required software
- [Installation](../getting-started/installation.md) - Project setup
- [Development Workflow](./README.md) - Daily development
- [Debugging](./debugging.md) - Debugging techniques
- [Environment Variables](./environment-variables.md) - Configuration

---

**Questions?** Check [GitHub Discussions](../../README.md) or ask the team!