Advanced

Build from Source

Prefer to compile KVault yourself? This page walks through the prerequisites, dev workflow, and production build — from a fresh clone to a signed-less binary in src-tauri/target.

Prerequisites

  • Node.js v18 or newer (v20 LTS recommended).
  • Rust stable toolchain, installed via rustup.
  • Tauri 2 system prerequisites — see the official Tauri prerequisites guide for the canonical, up-to-date list per platform.

Platform-specific notes

  • macOS — install the Xcode Command Line Tools: xcode-select --install.
  • Windows — Microsoft Visual C++ (MSVC) Build Tools and WebView2. WebView2 is bundled with Windows 11 and current Windows 10 installs.
  • Linux — install libwebkit2gtk-4.1-dev, build-essential, curl, wget, file, libssl-dev, libayatana-appindicator3-dev, and librsvg2-dev.

Clone & install

git clone https://github.com/uditalias/kvault.git
cd kvault
npm install

npm install pulls the JavaScript dependencies. Rust crates for the Tauri backend are fetched and compiled the first time you run a tauri command.

Run in development mode

npm run tauri dev

This starts the Vite dev server for the React frontend and launches the Tauri shell pointed at it. You get hot-reload for the UI and automatic rebuilds of the Rust backend as you edit files under src-tauri/.

Frontend-only dev

npm run dev

Runs Vite on its own, without the Tauri shell. The app loads in your browser, but anything that calls into Rust will fail — window.__TAURI__ is undefined in this mode. Useful for iterating on pure UI work (layout, styling, Storybook-like component tweaks) where the backend isn't involved.

Type-check & build frontend

npm run build

This runs tsc && vite build — a full TypeScript type-check followed by a production bundle of the frontend. It doubles as the project's type-check since there's no separate tsc --noEmit script.

Production build

npm run tauri build

Produces a release binary plus platform installers under src-tauri/target/release/bundle/ (.dmg on macOS, .msi/.exe on Windows, .AppImage/.deb on Linux).

Unsigned binaries. Code signing and notarization are not configured in this repo, so builds you produce locally are unsigned. See the Installation page for the platform-specific caveats (Gatekeeper on macOS, SmartScreen on Windows) that apply to unsigned builds.

Project layout

  • src/ — React 19 + TypeScript frontend (Zustand stores, components, themes).
  • src-tauri/ — Rust backend (Tauri 2 commands, SQLite via tauri-plugin-sql, Cloudflare API client, OS keychain integration).
  • public/ — static assets (icons, screenshots).
  • docs/ — landing page and this docs site (GitHub Pages source).
  • scripts/ — build helpers.

Architecture overview

The Rust side owns persistence — SQLite holds a local cache of key names for instant filtering, and the OS keychain stores Cloudflare API tokens so they never hit disk in plaintext — as well as all Cloudflare HTTP traffic. The React frontend calls into Rust via Tauri's invoke and subscribes to emit events for progress streams like background sync.

For a deeper map of modules, stores, and the command surface, see the CLAUDE.md in the repo root.