Contributing

Thank you for your interest in contributing to Thumper-Run! This guide covers everything from setting up your dev environment to submitting your first PR.

Development Setup

Clone the repository and run the setup command. This installs Rust toolchains, downloads the Tailwind CSS binary, and creates placeholder files for rust-analyzer.

bash

git clone https://github.com/thumper-ai/thumper-run.git
cd thumper-run
make setup

Verify your setup by running the fast test suite.

bash

# ~10-15 min: unit + integration + examples (2,340+ tests)
make test-fast

If you’re using VS Code or Zed, rust-analyzer should work out of the box after setup. If you see build errors, run make setup-rust-analyzer and restart your editor.

Crate Map

Thumper-Run is a Rust monorepo with several crates. Here are the main ones you’ll work with.

Crate	Path	Purpose
tr-shared-ui	crates/tr-shared-ui/	Leptos frontend components, pages, routing, CRDT stores
tr-tauri-shell	crates/tr-tauri-shell/	Tauri desktop shell: IPC commands, window management
tr-web-shell	crates/tr-web-shell/	SSR web server: Axum handlers, middleware, SSR rendering
lt-crdt-core	crates/lt-crdt-core/	CRDT engine: Loro integration, sync modes, encryption
lt-mirror	crates/lt-mirror/	Multi-CRDT storage, key management, Leptos integration
tr-services	crates/tr-services/	Backend services: launcher, model discovery, agents, gallery

First Contribution

Not sure where to start? Here are three levels of contribution, from easiest to most involved.

Level 1: Fix a Typo or Improve Docs

Documentation pages live in crates/tr-shared-ui/src/components/v2/pages/marketing/. Fix a typo, improve wording, or add a missing detail. These PRs are reviewed quickly.

Level 2: Add a Model Pack

Model pack manifests live in examples/model-manifests/. Pick a model from HuggingFace, write a .model.yaml and .pack.yaml, and submit a PR. See the Model Pack Tutorial for a walkthrough.

Level 3: Add an App Manifest

App manifests live in the catalog. Fork the repo, write a .thumper.yaml for an AI app, test it locally with make build-csr, and submit a PR. The App Manifest Tutorial walks through the full process.

Quick Check: .thumper.yaml

name—Application display namerequired

description—One-line descriptionrequired

emoji—Single Unicode emojirequired

runtime.type—Runtime: python, docker, native, or noderequired

runtime.launch—Launch commandrequired

install_commands[]—At least one install commandrequired

health_check—Health check endpoint or scriptrequired

model_packs[]—Model packs (if app uses models)optional

patches[]—Platform patches for GPU/OS (optional)optional

screenshots[]—3-5 screenshots for catalog (optional)optional

gradient—Card gradient CSS class (optional)optional

Testing

All PRs must pass the fast test suite before merging. Here are the key commands.

bash

# RECOMMENDED: Fast comprehensive testing (~10-15 min)
make test-fast
 
# Simulate CI pipeline (format + lint + fast tests)
make test-ci
 
# Run clippy lints
cargo clippy --workspace
 
# Check WASM target compiles
cargo check -p tr-shared-ui --target wasm32-unknown-unknown

For per-crate testing, use the crate-specific make targets.

bash

make test-lt-core         # lt-core
make test-lt-crdt-core    # lt-crdt-core (with test-all features)
make test-lt-mirror       # lt-mirror (all security modes)
make test-server-shell    # server-shell

Code Style

We follow standard Rust conventions with a few project-specific guidelines.

Rust 1.75+ with Leptos 0.8 for the frontend.
Use serde(default) on all new struct fields for backward compatibility.
Use #[serde(alias = "old_name")] for field renames instead of breaking changes.
Run cargo clippy before submitting. Zero warnings policy.
Use "text" for Leptos string literals — not bare strings.
Feature-gate platform-specific code with #[cfg(target_arch = "wasm32")] or Cargo features.
Write doc comments on public functions and types.

Key Takeaways

make setup to initialize, make test-fast to verify
Six key crates: tr-shared-ui, tr-tauri-shell, tr-web-shell, lt-crdt-core, lt-mirror, tr-services
Easiest contributions: doc fixes, model pack YAMLs, app manifests
All PRs must pass make test-ci (format + lint + tests)
Use serde(default) on new fields for backward compatibility

Advanced Reading

For the full onboarding tutorial, see TUTORIAL.md on GitHub (13 KB).

Learn More

Platform Architecture

Full system architecture and module boundaries

Manifest Field Reference

Schema docs for app, model, and pack manifests

Self-Hosting Guide

Deploy your own Thumper-Run instance