Docs /development/local-setup

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:

brew install --cask visual-studio-code

Linux:

# Ubuntu/Debian
sudo snap install --classic code

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

Windows:

Opening the Project

# 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:

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:

{
  // 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:

[
  // 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:

{
  "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:

{
  "$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:

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

Manual Formatting

# 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:

# Lint all packages
pnpm lint

# Lint specific app
cd apps/web
pnpm lint

Auto-fix on Save

VS Code can auto-fix ESLint issues:

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

🎨 Tailwind CSS IntelliSense

Setup

The Tailwind extension provides autocomplete for CSS classes.

Configuration (already in workspace settings):

{
  "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:

<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

# 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

# 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:

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

Configure import style:

{
  "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:

import React from 'react'

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

tRPC Procedure Snippet

Create .vscode/snippets.code-snippets:

{
  "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, but here's the basic .vscode/launch.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 for complete setup.

🪝 Git Hooks (Optional)

Setup Husky

Install pre-commit hooks to ensure code quality:

# 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):

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.

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

2. Exclude Folders from Indexing:

Prevent VS Code from indexing unnecessary files:

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

3. Increase Node Memory (for large builds):

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

4. Use pnpm Efficiently:

# 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:

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

Import Cost shows bundle size:

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

Pre-Push Checklist

Before pushing code:

# 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):

{
  "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

TypeScript in VS Code

🐛 Troubleshooting

VS Code Issues

Problem: TypeScript errors not showing

Solution:

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

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

Problem: Slow IntelliSense

Solution:

{
  "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:

# 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
  2. Debug issues: Debugging Guide
  3. Write tests: Testing Guide
  4. Explore codebase: Monorepo Structure

🔗 Related Documentation

Questions? Check GitHub Discussions or ask the team!

Reading this with an agent? /docs/development/local-setup.md serves the raw markdown.

All docs