Cross-Platform Deployment Builds
Relevant source files
The following files were used as context for generating this wiki page:
KamehaDB is designed as a local-first, cross-platform database GUI packaged using the Tauri v2 framework. The deployment process involves orchestrating a multi-package build that combines a React-based desktop frontend with a Node.js sidecar service. This architecture allows the application to run natively on macOS, Windows, and Linux while maintaining local-only data privacy.
Sources: AGENTS.md:10-12, PLAN.md:143-150, README.md:13-17
Build Architecture and Workflow
The build system leverages pnpm workspaces to manage dependencies across the desktop app, sidecar, and shared packages. The deployment pipeline follows a specific order: shared contracts are built first, followed by the sidecar, and finally the desktop package which uses the Tauri CLI to bundle everything into platform-specific installers.
Core Build Stages
The following diagram illustrates the sequence of operations required to generate a production-ready build.
The build flow ensures that the sidecar and shared logic are compiled before the Tauri shell packages them into the final executable.
Sources: AGENTS.md:46, AGENTS.md:107-111, PLAN.md:310-315
Platform-Specific Build Configurations
KamehaDB targets three major operating systems. Each platform requires specific Rust targets and produces different output formats.
Target Architectures
| Platform | Rust Target Triple | Output Formats |
|---|---|---|
| macOS (Silicon) | aarch64-apple-darwin | .dmg, .app |
| macOS (Intel) | x86_64-apple-darwin | .dmg, .app |
| Windows | x86_64-pc-windows-msvc | .exe, .msi |
| Linux | x86_64-unknown-linux-gnu | .deb, .AppImage, .rpm |
Sources: README.md:120-140, AGENTS.md:111
Tauri Configuration
The apps/desktop/src-tauri/tauri.conf.json file defines the application metadata and build hooks used during the deployment process.
{
"productName": "KamehaDB",
"version": "0.1.0",
"identifier": "com.kamehadb",
"build": {
"beforeDevCommand": "pnpm --filter @kamehadb/desktop build",
"beforeBuildCommand": "pnpm --filter @kamehadb/desktop build",
"frontendDist": "../dist"
}
}
Sources: apps/desktop/src-tauri/tauri.conf.json:3-11
Release Automation
The project uses GitHub Actions for automated release management. The workflow is triggered by version tags (e.g., v*) and handles the compilation and asset upload for all supported platforms.
Release Workflow Stages
- Tag Trigger: Pushing a tag matching
v*initiates therelease.ymlworkflow. - Draft Creation: A draft GitHub release is created to host the artifacts.
- Multi-Platform Matrix: Parallel runners build the application for macOS, Windows, and Linux.
- Asset Upload: Installable bundles are uploaded to the GitHub release.
Sources: AGENTS.md:106-114, PLAN.md:330-335
Build Commands
The following commands are utilized within the CI/CD pipeline and for manual local builds:
# Build the entire workspace (Shared -> Sidecar -> Desktop)
pnpm build
# Trigger Tauri production build for the current platform
pnpm tauri build
# Specific target builds (from apps/desktop)
pnpm tauri build --target aarch64-apple-darwin # macOS Silicon
pnpm tauri build --target x86_64-pc-windows-msvc # Windows
Sources: package.json:14-19, README.md:120-140
Security and Metadata in Builds
Deployment builds ensure that the application remains "local-first." Metadata, including connection profiles and SQL history, is stored in a local SQLite database (kamehadb.db) within the user's app data directory rather than being bundled with the application binary or sent to external servers. Credentials for database connections are managed via a secure bridge to the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
Sources: PLAN.md:162-166, PLAN.md:231-236, README.md:30-31
Conclusion
The cross-platform deployment builds of KamehaDB successfully unify a Node.js sidecar and a React frontend into a native desktop experience. By leveraging Tauri v2 and pnpm workspaces, the project maintains a consistent build pipeline that produces secure, local-first installers for macOS, Windows, and Linux.