Skip to content

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 ​

DependencyVersion / notesWhere to get it
Ruststable, 1.85+ recommended (the project uses edition 2024)https://rustup.rs
Node.js18+, 24 recommended (for the frontend build)https://nodejs.org
WebView2Runtime for the settings window (normally bundled with Win10/11)Bundled with Windows / Microsoft
Inno Setup 6Optional, needed to build the installer locallywinget install JRSoftware.InnoSetup
pssuspend64.exeOptional, needed to test enhanced freezingMicrosoft 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 ​

bash
git clone https://github.com/IvanHanloth/ZoneDeck.git
cd ZoneDeck

Common commands ​

Run these from the repository root:

Core (zonedeck-core) ​

bash
# Run the core (development)
cargo run -p zonedeck-core

# Core smoke test: exits automatically after N milliseconds
cargo run -p zonedeck-core -- smoke 3000

Frontend (apps/config/ui) ​

bash
# 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 dev

Settings window (zonedeck-config, Tauri) ​

bash
# Run the settings window (build the frontend first)
npm --prefix apps/config/ui run build && cargo run -p zonedeck-config

Checks and tests ​

bash
# 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 -- --check

Release builds and packaging ​

bash
# 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 -Installer

For packaging details see Packaging & releasing.

Command cheat sheet ​

PurposeCommand
Run the corecargo run -p zonedeck-core
Core smoke testcargo run -p zonedeck-core -- smoke 3000
Install frontend depsnpm --prefix apps/config/ui install
Build the frontendnpm --prefix apps/config/ui run build
Frontend testsnpm --prefix apps/config/ui test
Frontend browser previewnpm --prefix apps/config/ui run dev
Run the settings windownpm --prefix apps/config/ui run build && cargo run -p zonedeck-config
Release buildcargo build --release
All Rust testscargo test --workspace
Clippycargo clippy --workspace --all-targets -- -D warnings
Format checkcargo fmt --all -- --check
One-shot packagingpowershell -File scripts/package.ps1
Packaging + installerpowershell -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.