Tauri Setup and Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
KamehaDB uses Tauri v2 as its primary framework for delivering a local-first, cross-platform desktop experience. The integration combines a Rust-based shell for native capabilities with a React 19 frontend and a local Node.js sidecar that handles database connectivity. Tauri serves as the orchestration layer, managing the application lifecycle and providing secure access to native OS features such as the keychain and filesystem.
The project architecture relies on Tauri to package the web assets (built via Vite and Tailwind CSS v4) and bundle a Node.js sidecar server. This sidecar is responsible for executing database operations, while Tauri ensures the entire system remains local-only to protect user credentials and data.
Sources: AGENTS.md:12-18, PLAN.md:200-210, README.md:123-127
System Architecture and Data Flow
The Tauri integration in KamehaDB follows a specific runtime flow where the desktop application acts as the coordinator between the user interface and the backend sidecar.
Runtime Operation Flow
The application logic is distributed across three primary layers: the React UI, the Tauri Rust shell, and the Node.js sidecar.
The diagram shows how the Tauri shell manages the sidecar process while the UI communicates directly with the sidecar's Hono server.
Sources: PLAN.md:154-162, AGENTS.md:55-60
Component Responsibilities
| Layer | Responsibility |
|---|---|
| Tauri (Rust) | Packaging, native commands, starting/stopping the sidecar, providing app data directories, and bridging to the OS keychain. |
| Frontend (React) | Workspace layout, connection navigation, SQL editor (Monaco), and state management via TanStack Query/Store. |
| Sidecar (Node) | Database adapter execution, connection pooling, normalization of metadata, and enforcing safety guards (read-only modes). |
Sources: PLAN.md:164-180, AGENTS.md:63-93
Technical Configuration
Rust Environment and Dependencies
The Rust backend is configured using Cargo.toml and standard Tauri build scripts. It includes specific plugins for shell operations and security.
[dependencies]
tauri = { version = "2", features = [] }
tauri-plugin-opener = "2"
tauri-plugin-shell = "2"
keyring = "3"
tokio = { version = "1", features = ["full"] }
Sources: apps/desktop/src-tauri/Cargo.toml:13-19
The build process is initialized through build.rs, which invokes the standard tauri_build logic.
Sources: apps/desktop/src-tauri/build.rs:1-3
Build and Development Scripts
The project uses pnpm to manage its monorepo workspace. Tauri-specific commands are filtered through the @kamehadb/desktop package.
| Command | Action |
|---|---|
pnpm tauri | Runs the Tauri CLI within the desktop package. |
pnpm dev | Runs both the sidecar and the desktop app concurrently. |
pnpm --filter @kamehadb/desktop tauri build | Compiles the production bundle for the current platform. |
Sources: AGENTS.md:43-52, package.json:9-21
Sidecar Integration
A critical aspect of the Tauri setup is the management of the Node.js sidecar. The sidecar runs a Hono HTTP server bound exclusively to 127.0.0.1.
- Process Management: Tauri is responsible for starting the sidecar process on application launch and terminating it when the app closes.
- Communication: The sidecar selects a random available port and communicates this to the Tauri-managed UI.
- Data Directory: Tauri provides the path to the system's application data directory, where the sidecar stores its
kamehadb.dbmetadata SQLite file.
Sources: AGENTS.md:63-71, PLAN.md:170-176
Cross-Platform Packaging
KamehaDB leverages Tauri to generate platform-specific installers. The build process requires specific Rust targets to be installed via rustup.
Target Support
- macOS: Supports
aarch64-apple-darwin(M1/M2/M3) andx86_64-apple-darwin(Intel). - Windows: Supports
x86_64-pc-windows-msvc. - Linux: Supports
x86_64-unknown-linux-gnu.
Sources: README.md:144-162
Security and Signing
For macOS, unsigned builds require specific Gatekeeper bypasses during local testing, such as removing the quarantine attribute using xattr. Tauri integration eventually includes secure storage via the keyring crate to interface with the macOS Keychain, Windows Credential Manager, and Linux Secret Service.
Sources: README.md:129-141, PLAN.md:112-117, apps/desktop/src-tauri/Cargo.toml:18
Summary
The Tauri Setup and Integration in KamehaDB provides the structural glue between a high-performance React frontend and a multi-adapter Node.js backend. By utilizing Tauri v2, the project achieves cross-platform distribution while maintaining a strictly local-first security posture, ensuring that database credentials and metadata never leave the user's machine.
Sources: PLAN.md:200-210, README.md:12-15