Running locally
This chapter covers setting up a development environment, running the core and the settings window, and the commands used day to day.
Prerequisites
| Dependency | Version / notes | Where to get it |
|---|---|---|
| Rust | stable, 1.85+ recommended (the project uses edition 2024) | https://rustup.rs |
| Node.js | 18+, 24 recommended (for the frontend build) | https://nodejs.org |
| WebView2 | Runtime for the settings window (normally bundled with Win10/11) | Bundled with Windows / Microsoft |
| Inno Setup 6 | Optional, needed to build the installer locally | winget install JRSoftware.InnoSetup |
| pssuspend64.exe | Optional, needed to test enhanced freezing | Microsoft PSTools |
The settings window does not need a dev server
The frontend is embedded into zonedeck-config.exe at build time, so the final artefact runs statically. While working on the frontend, preview it in a browser with npm run dev (mock data, hot reload); after npm run build, verify the Tauri integration with cargo run -p zonedeck-config.
Cloning the project
git clone https://github.com/IvanHanloth/ZoneDeck.git
cd ZoneDeckCommon commands
Run these from the repository root:
Core (zonedeck-core)
# Run the core (development)
cargo run -p zonedeck-core
# Core smoke test: exits automatically after N milliseconds
cargo run -p zonedeck-core -- smoke 3000Frontend (apps/config/ui)
# First time: install frontend dependencies
npm --prefix apps/config/ui install
# Build the frontend (output goes to apps/config/dist for Tauri to embed)
npm --prefix apps/config/ui run build
# Frontend unit tests (vitest)
npm --prefix apps/config/ui test
# Browser preview (mock data, hot reload)
npm --prefix apps/config/ui run devSettings window (zonedeck-config, Tauri)
# Run the settings window (build the frontend first)
npm --prefix apps/config/ui run build && cargo run -p zonedeck-configChecks and tests
# Run all Rust tests
cargo test --workspace
# Static analysis (warnings as errors)
cargo clippy --workspace --all-targets -- -D warnings
# Format / check formatting only
cargo fmt --all
cargo fmt --all -- --checkRelease builds and packaging
# Release build (minimised size)
cargo build --release
# One-shot packaging (frontend + Rust + the portable folder dist/ZoneDeck)
powershell -File scripts/package.ps1
# Packaging plus installer (dist/installer; installs Inno Setup automatically on first run)
powershell -File scripts/package.ps1 -InstallerFor packaging details see Packaging & releasing.
Command cheat sheet
| Purpose | Command |
|---|---|
| Run the core | cargo run -p zonedeck-core |
| Core smoke test | cargo run -p zonedeck-core -- smoke 3000 |
| Install frontend deps | npm --prefix apps/config/ui install |
| Build the frontend | npm --prefix apps/config/ui run build |
| Frontend tests | npm --prefix apps/config/ui test |
| Frontend browser preview | npm --prefix apps/config/ui run dev |
| Run the settings window | npm --prefix apps/config/ui run build && cargo run -p zonedeck-config |
| Release build | cargo build --release |
| All Rust tests | cargo test --workspace |
| Clippy | cargo clippy --workspace --all-targets -- -D warnings |
| Format check | cargo fmt --all -- --check |
| One-shot packaging | powershell -File scripts/package.ps1 |
| Packaging + installer | powershell -File scripts/package.ps1 -Installer |
Common development problems
Antivirus blocks a freshly compiled executable
If you see os error 5 access denied, antivirus software has usually locked the newly built exe. Add the project's target folder to your antivirus allowlist.
Core tests must run single-threaded
Some core tests initialise COM, and running them in parallel can crash. If you hit this, run them single-threaded with cargo test -p zonedeck-core -- --test-threads=1. See Testing strategy.