Development Guide

February 12, 2026 · View on GitHub

This guide covers the development workflow for kftray using mise as the unified task runner.

Table of Contents

Prerequisites

Required: mise

The project uses mise to manage all development tools and tasks. You only need to install mise:

curl https://mise.run | sh

After installation, restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

That's it! mise will handle installing:

  • Node.js 24
  • pnpm (latest)
  • Rust nightly (with required components)
  • Cargo tools (cargo-llvm-cov, cargo-nextest, cargo-insta, tauri-cli)
  • System dependencies (via mise run setup)

Quick Start

# Clone the repository
git clone https://github.com/hcavarsan/kftray.git
cd kftray

# Install tools defined in .mise.toml
mise install

# Setup system dependencies and install project dependencies
mise run setup

# Start development
mise run dev

Development Workflow

1. First Time Setup

# Install mise-managed tools (Node, Rust, pnpm, etc.)
mise install

# Install system dependencies (webkit, build tools, etc.)
# This detects your OS and installs the right packages
mise run setup

2. Daily Development

# Start development mode (hot reload enabled)
mise run dev

# In another terminal, run tests
mise run test:back

# Format and lint before committing
mise run format
mise run lint

3. Building

# Build production app
mise run build

# Build only the UI
mise run build:ui

# Build with bundle analysis
mise run build:analyze

Available Tasks

Run mise tasks to see all available tasks. Here are the most commonly used:

Development

TaskDescription
mise run devStart Tauri development mode (hot reload)
mise run buildBuild production application
mise run build:uiBuild only the frontend UI
mise run build:analyzeBuild with bundle size analysis

Code Quality

TaskDescription
mise run formatFormat frontend (Prettier) and backend (rustfmt)
mise run format:frontFormat only frontend code
mise run format:backFormat only backend code
mise run lintLint with auto-fix (ESLint + Clippy)
mise run lint:frontLint frontend with auto-fix
mise run lint:backLint backend with auto-fix
mise run lint:back:checkLint backend without auto-fix (CI mode)
mise run checkTypeScript type checking

Testing

TaskDescription
mise run test:backRun Rust backend tests with coverage
mise run test:serverRun Docker proxy tests

Pre-commit

TaskDescription
mise run precommitRun format, lint, and tests
mise run precommit:hookGit hook version (format + lint + stage changes)

Utilities

TaskDescription
mise run setupSetup development environment
mise run generate-iconsGenerate application icons
mise run knipDetect unused exports in frontend

Version Management

TaskDescription
mise run bump:patchBump patch version (0.0.x)
mise run bump:minorBump minor version (0.x.0)
mise run bump:majorBump major version (x.0.0)
mise run release:patchBump patch and create release commit
mise run release:minorBump minor and create release commit

Project Structure

kftray/
├── .mise.toml              # mise configuration (tools + tasks)
├── frontend/               # React + TypeScript UI
│   ├── src/
│   └── package.json
├── crates/                 # Rust workspace
│   ├── kftray-tauri/      # Desktop app (Tauri)
│   ├── kftui/             # Terminal UI
│   ├── kftray-server/     # Proxy relay server
│   ├── kftray-portforward/# Port forwarding logic
│   └── ...
├── hacks/                  # Utility scripts
│   ├── setup.sh           # OS-specific setup script
│   └── ...
└── docs/                   # Documentation

Git Workflow

Pre-commit Hook

The repository has an automatic pre-commit hook that:

  1. Formats all code (Prettier + rustfmt)
  2. Lints with auto-fix (ESLint + Clippy)
  3. Stages the fixed files automatically

When you run git commit, the hook runs automatically. Your code will be formatted and linted before the commit is created.

To bypass the hook (not recommended):

git commit --no-verify

Creating Pull Requests

  1. Fork and clone the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Make your changes
  4. Commit (pre-commit hook runs automatically)
  5. Push and create a pull request

The CI will run:

  • Format check
  • Lint check (no auto-fix in CI)
  • Backend tests with coverage
  • Frontend bundle analysis

Testing

Backend Tests

# Run all backend tests with coverage
mise run test:back

# Run specific test
cargo test test_name

Frontend Type Checking

# Check TypeScript types
mise run check

Docker Proxy Tests

# Test TCP/UDP proxy functionality
mise run test:server

Troubleshooting

mise not found

After installing mise, restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

System dependencies missing

Run the setup script again:

mise run setup

This will detect your OS and install missing dependencies.

Tool version mismatch

Ensure you have the latest tools:

mise install  # Reinstall all tools

Port already in use

The default development port is used by Tauri. Kill any process using the port:

# macOS/Linux
lsof -ti:PORT | xargs kill -9

# Windows
netstat -ano | findstr :PORT
taskkill /PID <PID> /F

Pre-commit hook failing

The hook runs format and lint automatically. If it fails:

  1. Check the error message
  2. Fix the issue manually
  3. Try committing again

Or run the checks manually:

mise run format
mise run lint

Building fails on Windows

Ensure you have:

  1. Microsoft C++ Build Tools installed
  2. WebView2 Runtime installed
  3. NASM installed (for some dependencies)

Run mise run setup to see detailed instructions.

Node/pnpm/Rust version issues

mise manages all tool versions. If you're having version issues:

# Check installed versions
mise ls

# Reinstall tools
mise install --force

Additional Resources

Getting Help