Development

kftray uses mise for development tools and tasks. For platform dependencies and release builds, see building from source. For the pull request process, see contributing.

PrerequisitesCopy Anchor Link

miseCopy Anchor Link

Install mise. It manages the other development tools and the tasks:

curl https://mise.run | sh

After the installation, restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

mise installs the tools pinned in .mise.toml:

• Node.js 26
• pnpm 12
• syft and grype (for the sbom:* tasks)

mise run setup installs the system dependencies and the pnpm packages, including the Tauri CLI.

RustCopy Anchor Link

mise doesn't install Rust. Install it with rustup, along with the nightly rustfmt that mise run format:back uses:

rustup toolchain install stable
rustup toolchain install nightly --profile minimal --component rustfmt

mise run test:back also needs cargo-llvm-cov and cargo-nextest:

cargo install --locked cargo-llvm-cov cargo-nextest

Quick startCopy Anchor Link

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

# Install tools defined in .mise.toml
mise install

# Set up system dependencies and install project dependencies
mise run setup

# Start development
mise run dev

Development workflowCopy Anchor Link

First-time setupCopy Anchor Link

# Install mise-managed tools (Node, pnpm, syft, grype)
mise install

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

Daily developmentCopy Anchor Link

# 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

mise run dev builds the kftray-helper binary in release mode first, then starts pnpm tauri dev.

BuildingCopy Anchor Link

# Build production app
mise run build

# Build only the UI
mise run build:ui

# Build with bundle analysis
mise run build:analyze

For platform requirements and build outputs, see Building from Source.

Available tasksCopy Anchor Link

Run mise tasks to see all available tasks. These are the most common ones.

DevelopmentCopy Anchor Link

Code qualityCopy Anchor Link

TestingCopy Anchor Link

Pre-commitCopy Anchor Link

UtilitiesCopy Anchor Link

Version managementCopy Anchor Link

Project structureCopy Anchor Link

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
│   └── ...
└── README.md               # Project overview and documentation links

See Architecture for what each crate does.

DocumentationCopy Anchor Link

Guides live in kftray-blog/content/docs. Update the corresponding MDX page when app behavior or development commands change. Repository READMEs provide short introductions and links to these pages.

When adding a page, include it in its directory's meta.json navigation. Publish new site routes before repository links that depend on them. The version bump utility updates package manifests and Tauri configuration. Documentation downloads link to the website instead of requiring version updates in local Markdown guides.

Git workflowCopy Anchor Link

Pre-commit hookCopy Anchor Link

The repository doesn't install a Git hook. mise run precommit:hook is meant to be used as one. It:

Run it before you commit, or call it from your own .git/hooks/pre-commit.

To bypass the hook (not recommended):

git commit --no-verify

Pull requestsCopy Anchor Link

1. Fork and clone the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Make your changes.
4. Run mise run format and mise run lint, then commit.
5. Push and create a pull request.

CI runs these checks:

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

See Contributing for the full pull request and merge process.

TestingCopy Anchor Link

Backend testsCopy Anchor Link

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

# Run a specific test
cargo test test_name

Frontend type checkingCopy Anchor Link

# Check TypeScript types
mise run check

Docker proxy testsCopy Anchor Link

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

TroubleshootingCopy Anchor Link

mise not foundCopy Anchor Link

After installing mise, restart your terminal or run:

source ~/.bashrc  # or ~/.zshrc

System dependencies missingCopy Anchor Link

Run the setup task again. It detects your OS and installs the missing dependencies:

mise run setup

Tool version mismatchCopy Anchor Link

Reinstall the tools to get the versions pinned in .mise.toml:

mise install

Port already in useCopy Anchor Link

Tauri uses a default development port. In tauri.conf.json the dev URL is http://localhost:1420. Stop any process that uses the port:

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

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

Pre-commit hook failingCopy Anchor Link

If you call mise run precommit:hook from your own Git hook, it runs mise run format and cargo check. 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 WindowsCopy Anchor Link

Check that 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 and pnpm version issuesCopy Anchor Link

mise manages the Node and pnpm versions. If you have version issues:

# Check installed versions
mise ls

# Reinstall tools
mise install --force

Additional resourcesCopy Anchor Link

• Tauri documentation
• mise documentation
• Contributing
• Building from Source
• Linux packaging for maintainers who publish the Linux packages
• Security for the SBOM and vulnerability scan that mise run precommit runs

Getting helpCopy Anchor Link

• Check the Issues page.
• Join the Slack community.