Development Setup

Get your development environment ready for contributing to KiraPilot.

Prerequisites

Before you begin, ensure you have the following installed on your system:

Required Software

• Node.js 18+: Download from nodejs.org
• Rust (latest stable): Install via rustup.rs
• Git: Download from git-scm.com

Platform-Specific Requirements

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install Homebrew (optional but recommended)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Windows

• Install Visual Studio Build Tools
• Ensure Windows SDK is installed

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install build-essential curl wget file libssl-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Installation

1. Clone the Repository

git clone https://github.com/vietanhdev/kirapilot-app.git
cd kirapilot-app

2. Install Dependencies

# Install Node.js dependencies
npm install

# Install Rust dependencies (handled automatically by Tauri)
# This will be done when you first run the Tauri dev command

3. Set Up Development Database

The application uses SQLite with automatic migrations. The database will be created automatically when you first run the application.

# The database file will be created at:
# - macOS: ~/Library/Application Support/com.kirapilot.app/kirapilot.db
# - Windows: %APPDATA%/com.kirapilot.app/kirapilot.db
# - Linux: ~/.local/share/com.kirapilot.app/kirapilot.db

4. Start the Development Server

# Start the Tauri development server
npm run tauri dev

# Or start just the frontend (for UI development)
npm run dev

Development Workflow

Daily Development

1. Pull latest changes:

   git pull origin main
   npm install  # In case dependencies changed

2. Start development server:

   npm run tauri dev

3. Run tests (in a separate terminal):

   npm test

Code Quality Checks

Before committing, always run:

# Type checking
npm run type-check

# Linting
npm run lint

# Formatting check
npm run format:check

# Run all tests
npm test

# Build to ensure everything compiles
npm run build

Git Hooks

The project uses Husky for Git hooks:

• Pre-commit: Runs lint-staged to format and lint staged files
• Commit-msg: Validates commit message format

Available Scripts

# Development
npm run dev              # Start Vite dev server
npm run tauri:dev        # Start Tauri app in dev mode

# Building
npm run build            # Build frontend (tsc + vite build)
npm run tauri:build      # Build Tauri application
npm run build:all        # Run type-check, lint, test, and build
npm run release:prepare  # Prepare complete release build

# Cross-platform building
npm run build:macos      # Build for macOS (universal binary)
npm run build:windows    # Build for Windows x64
npm run build:linux      # Build for Linux x64
npm run build:linux-arm64 # Build for Linux ARM64
npm run build:all-platforms # Build for all platforms

# Testing
npm test                 # Run Jest tests
npm run test:watch       # Jest in watch mode
npm run test:coverage    # Generate coverage report

# Code Quality
npm run lint             # ESLint check
npm run lint:fix         # ESLint auto-fix
npm run format           # Prettier format
npm run format:check     # Prettier check
npm run type-check       # TypeScript check without emit

# Version Management
npm run sync-version     # Sync version across files
npm run version:patch    # Bump patch version
npm run version:minor    # Bump minor version
npm run version:major    # Bump major version

# Internationalization
npm run i18n:validate    # Validate translation files
npm run i18n:check       # Check translation consistency

# Documentation
npm run docs:start       # Start documentation server
npm run docs:build       # Build documentation
npm run docs:serve       # Serve built documentation

# AI Testing
npm run test_llm         # Test local LLM integration
npm run test_llm_integration # Test LLM integration

IDE Setup

VS Code (Recommended)

Install the following extensions:

• Rust Analyzer: Rust language support
• Tauri: Tauri-specific features
• ES7+ React/Redux/React-Native snippets: React snippets
• TypeScript Importer: Auto import for TypeScript
• Prettier: Code formatting
• ESLint: Linting support

Recommended VS Code Settings

Create .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "rust-analyzer.checkOnSave.command": "clippy"
}

Troubleshooting

Common Issues

Rust Compilation Errors

# Update Rust toolchain
rustup update

# Clear Rust cache
cargo clean

Node.js Module Issues

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Database Issues

# Reset development database
rm -f src-tauri/kirapilot.db
# Restart the app to recreate with fresh migrations

Build Failures

# Clean all build artifacts
npm run clean  # If available
rm -rf dist/
rm -rf src-tauri/target/
npm run build

Getting Help

• Check the FAQ for common questions
• Review troubleshooting guide
• Open an issue on GitHub for bugs
• Join our Discord community for development discussions

Next Steps

Once your environment is set up:

1. Read the Architecture Overview
2. Understand the Project Structure
3. Review the Contributing Guidelines
4. Explore the Database Documentation