Development Setup

Learn how to set up your development environment to build TalkCody from source, contribute code, or customize the application.

Prerequisites

System Requirements

Operating System:

macOS 11.0+ (Big Sur or later)
Windows 10 1809+ or Windows 11
Linux (Ubuntu 20.04+, Debian 11+, Fedora 35+)

Hardware:

8GB RAM minimum (16GB recommended)
2GB free disk space
Multi-core processor

Required Software

Node.js and Bun

# Install Node.js 20+ (via nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Install Bun
curl -fsSL https://bun.sh/install | bash

Rust

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version
cargo --version

Git

# macOS (via Homebrew)
brew install git

# Windows (via Chocolatey)
choco install git

# Linux (Ubuntu/Debian)
sudo apt install git

Platform-Specific Requirements

macOS:

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

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

Windows:

# Install Visual Studio Build Tools
# Download from: https://visualstudio.microsoft.com/downloads/
# Select: Desktop development with C++

# Install WebView2 (usually pre-installed on Windows 11)
# Download if needed: https://developer.microsoft.com/microsoft-edge/webview2/

Linux:

# Ubuntu/Debian
sudo apt update
sudo apt install libwebkit2gtk-4.1-dev \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

# Fedora
sudo dnf install webkit2gtk4.1-devel \
  openssl-devel \
  curl \
  wget \
  file \
  gtk3-devel \
  libappindicator-gtk3-devel \
  librsvg2-devel

# Arch Linux
sudo pacman -S webkit2gtk \
  base-devel \
  curl \
  wget \
  file \
  openssl \
  gtk3 \
  libappindicator-gtk3 \
  librsvg

Getting Started

Clone the Repository

# Clone via HTTPS
git clone https://github.com/yourusername/talkcody.git

# Or via SSH
git clone git@github.com:yourusername/talkcody.git

# Navigate to directory
cd talkcody

Install Dependencies

# Install frontend dependencies
bun install

# Install Rust dependencies (automatic during first build)
cd src-tauri
cargo fetch
cd ..

First-time setup may take 5-10 minutes as dependencies are downloaded and compiled.

Set Up Environment

Create a .env file for development:

# Copy example environment file
cp .env.example .env

# Edit with your preferences
# Add any API keys for testing (optional)

Example .env:

# Development settings
NODE_ENV=development
VITE_APP_NAME=TalkCody
VITE_APP_VERSION=1.0.0

# Optional: API keys for testing
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...

Run Development Server

# Start Tauri development server
bun run tauri dev

# Or using npm/pnpm
npm run tauri dev
pnpm run tauri dev

This will:

Start the Vite dev server
Compile Rust code
Launch the application window
Enable hot-reload for frontend changes

Development Workflow

Project Structure

talkcody/
├── src/                    # React frontend source
│   ├── components/         # UI components
│   ├── hooks/              # React hooks
│   ├── lib/                # Utilities
│   ├── pages/              # Page components
│   ├── services/           # Business logic
│   ├── styles/             # CSS files
│   └── types/              # TypeScript types
│
├── src-tauri/              # Rust backend
│   ├── src/                # Rust source files
│   │   ├── main.rs         # Entry point
│   │   ├── commands/       # Tauri commands
│   │   └── lib.rs          # Library code
│   ├── Cargo.toml          # Rust dependencies
│   └── tauri.conf.json     # Tauri configuration
│
├── public/                 # Static assets
├── docs/                   # Documentation site
├── package.json            # Node dependencies
├── tsconfig.json           # TypeScript config
├── vite.config.ts          # Vite configuration
└── README.md

Common Commands

Development:

# Start dev server with hot reload
bun run tauri dev

# Start frontend only (for UI work)
bun run dev

# Run TypeScript type checking
bun run tsc

# Run linter
bun run lint

# Run tests
bun run test

Building:

# Build for production
bun run tauri build

# Build frontend only
bun run build

# Build with debug symbols
bun run tauri build --debug

Code Quality:

# Format code with Biome
bunx biome format --write

# Lint and fix issues
bunx biome lint --write

# Type check
bun run tsc

Making Changes

Frontend Changes:

Edit files in src/
Changes hot-reload automatically
Check browser console for errors
Test in the Tauri window

Backend Changes:

Edit Rust files in src-tauri/src/
Tauri automatically recompiles
Application restarts with changes
Check terminal for Rust compiler errors

Database Changes:

Modify schema in src-tauri/src/db/
Update TypeScript types in src/types/
Run migrations if needed
Test with existing data

Use console.log() for frontend debugging and println!() or dbg!() for Rust debugging.

Building from Source

Development Build

# Fast build with debug symbols
bun run tauri build --debug

# Output locations:
# macOS: src-tauri/target/debug/bundle/
# Windows: src-tauri/target/debug/
# Linux: src-tauri/target/debug/

Production Build

# Optimized release build
bun run tauri build

# Output locations:
# macOS: src-tauri/target/release/bundle/macos/
# Windows: src-tauri/target/release/bundle/
# Linux: src-tauri/target/release/bundle/appimage/

Build artifacts:

macOS: .dmg installer
Windows: .msi installer
Linux: .AppImage, .deb, .rpm

Build Options

Custom build configuration:

# Build for specific target
cargo build --release --target x86_64-apple-darwin

# Build with features
cargo build --release --features "feature1,feature2"

# Cross-compile (requires setup)
cargo build --release --target x86_64-pc-windows-msvc

Testing

Running Tests

Frontend Tests:

# Run Vitest tests
bun run test

# Watch mode
bun run test:watch

# Coverage
bun run test:coverage

Backend Tests:

cd src-tauri
cargo test

# With output
cargo test -- --nocapture

# Specific test
cargo test test_name

Writing Tests

Frontend Example:

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { MyComponent } from './MyComponent';

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent />);
    expect(screen.getByText('Hello')).toBeInTheDocument();
  });
});

Backend Example:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_my_function() {
        let result = my_function(42);
        assert_eq!(result, expected_value);
    }
}

Debugging

Frontend Debugging

Browser DevTools:

# Tauri window has DevTools built-in
# Right-click → Inspect Element
# Or press: Cmd+Alt+I (Mac) / Ctrl+Shift+I (Windows/Linux)

VS Code Launch Configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "Debug Frontend",
      "url": "http://localhost:5173",
      "webRoot": "${workspaceFolder}/src"
    }
  ]
}

Backend Debugging

Rust Debugging:

# Run with logging
RUST_LOG=debug bun run tauri dev

# Use debugger
# Install: https://lldb.llvm.org/
lldb target/debug/talkcody

VS Code Rust Debugging:

{
  "type": "lldb",
  "request": "launch",
  "name": "Debug Rust",
  "cargo": {
    "args": ["build", "--manifest-path=src-tauri/Cargo.toml"]
  },
  "program": "${workspaceFolder}/src-tauri/target/debug/talkcody"
}

Common Issues

Build Failures:

# Clean and rebuild
rm -rf node_modules dist src-tauri/target
bun install
bun run tauri build

Tauri Won't Start:

# Check Rust installation
rustc --version

# Update Tauri CLI
cargo install tauri-cli --force

# Clear Cargo cache
cargo clean

Hot Reload Not Working:

# Restart dev server
# Check firewall settings
# Verify port 5173 is available

Contributing

Getting Started with Contributions

Fork the repository on GitHub
Clone your fork locally
Create a branch for your feature/fix
Make your changes
Test thoroughly
Submit a pull request

Contribution Guidelines

Branch Naming:

feature/description  - New features
fix/description      - Bug fixes
docs/description     - Documentation
refactor/description - Code refactoring

Commit Messages:

feat: Add voice input support
fix: Resolve memory leak in chat
docs: Update installation guide
refactor: Simplify agent configuration

Code Style:

TypeScript: Follow project .prettierrc
Rust: Use cargo fmt
Tests: Add tests for new features
Documentation: Update relevant docs

Pull Request Process

Update your branch with latest main
Ensure all tests pass
Run linters and formatters
Write clear PR description
Request review from maintainers
Address review feedback
Merge once approved

See CONTRIBUTING.md for detailed guidelines.

Development Tools

Recommended VS Code Extensions

{
  "recommendations": [
    "tauri-apps.tauri-vscode",
    "rust-lang.rust-analyzer",
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss",
    "biomejs.biome"
  ]
}

Useful Scripts

Package Scripts:

{
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "tauri": "tauri",
    "tauri:dev": "tauri dev",
    "tauri:build": "tauri build",
    "test": "vitest",
    "lint": "biome lint",
    "format": "biome format --write"
  }
}

Next Steps

Architecture - Understand the codebase
Contributing Guidelines
GitHub Issues - Report bugs or request features

Join our Discord community for development discussions and support!

Development Setup

On This Page