Desktop App Development
Relevant source files
The following files were used as context for generating this wiki page:
Onyx Desktop is a lightweight macOS application built using the Tauri framework. It provides a native-feeling interface for Onyx Cloud and self-hosted instances, utilizing the system's native WebKit engine rather than bundling a full Chromium instance. This architecture results in a significantly smaller bundle size (~10MB) compared to traditional Electron-based applications (~150MB+).
The application serves as a wrapper for the Onyx web interface, adding native desktop capabilities such as system-level keyboard shortcuts, window state persistence (size and position), and multi-window support. While optimized for macOS with specific features like "traffic light" window controls and an overlay title bar style, it is designed with cross-platform compatibility in mind.
Sources: desktop/README.md:1-13, desktop/README.md:20-21
Architecture and Framework
The desktop application follows the Tauri architecture, which splits the application into a Rust-based backend and a web-based frontend. The frontend is derived from the core Onyx web project, while the Rust backend handles system-level integrations and window management.
Component Stack
| Layer | Technology | Description |
|---|---|---|
| Frontend UI | Next.js / React | The same UI used in the web application, rendered via WebKit. |
| App Shell | Tauri | Framework connecting the Rust backend to the webview. |
| Backend Logic | Rust | Handles shortcuts, file system access, and native windowing. |
| Styling | Tailwind CSS | Custom Opal design system and Onyx-specific color variables. |
Sources: desktop/README.md:5-9, desktop/README.md:53-62, desktop/CLAUDE.md:1-10
Application Flow
The following diagram illustrates how the desktop app initializes and connects to either the cloud or a custom server.
The application defaults to https://cloud.onyx.app but can be reconfigured via a local config.json file.
Sources: desktop/README.md:79-106
Frontend Development Standards
Desktop development adheres to the same "Opal" design system standards as the main web application. This ensures a consistent user experience across platforms.
UI Components
Developers must use the Opal design system components located in web/lib/opal/src/. Legacy components in web/src/components/ are phased out and should be avoided. Key primitives include:
- Content/ContentAction: Standardized layouts for icon, title, and description pairs.
- Interactive Primitives: Stateless and Stateful containers that handle hover and active states via a central color matrix.
- Opal Text: A typography component that enforces Figma-compliant styles and supports opt-in markdown.
Sources: desktop/CLAUDE.md:10-50, desktop/CLAUDE.md:188-210
Design Constraints
- Dark Mode: The
dark:Tailwind modifier is strictly forbidden. The system uses a carefully definedcolors.cssmapping that handles themes automatically. - Icons: Only icons from
web/src/iconsare permitted. External libraries likelucideorreact-iconsare restricted to maintain aesthetic consistency. - Spacing: Padding is preferred over margins. If a component lacks a padding variant, the library component itself should be updated rather than adding wrapper divs.
Sources: desktop/CLAUDE.md:150-185, desktop/CLAUDE.md:215-225, desktop/CLAUDE.md:315-330
Native Integration and Configuration
Native Shortcuts
The application implements native macOS shortcuts via the Rust backend. These are configured in the setup_shortcuts function within the Rust source.
| Shortcut | Action |
|---|---|
⌘ N | New Chat |
⌘ ⇧ N | New Window |
⌘ , | Open Config File |
⌘ W | Close Window |
Sources: desktop/README.md:23-33, desktop/README.md:113-115
Configuration Management
Native configuration is stored in platform-specific directories. This allows users to point the desktop app to a self-hosted instance of Onyx.
{
"server_url": "https://your-onyx-instance.company.com",
"window_title": "Onyx"
}
Paths by Platform:
- macOS:
~/Library/Application Support/app.onyx.desktop/config.json - Linux:
~/.config/app.onyx.desktop/config.json - Windows:
%APPDATA%/app.onyx.desktop/config.json
Sources: desktop/README.md:85-100
Development and Build Process
Prerequisites
- Rust: Latest stable version is required for the backend.
- Node.js: Version 18+ (Node 22 is recommended for the broader Onyx project).
- Xcode Command Line Tools: Required for compilation on macOS.
Sources: desktop/README.md:35-49, CONTRIBUTING.md:108-115
Build Commands
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build for current architecture
npm run build
# Build Universal Binary (Intel + Apple Silicon)
npm run build:dmg
Sources: desktop/README.md:53-76
Project Structure
onyx-desktop/
├── src/
│ └── index.html # Fallback/loading page
└── src-tauri/
├── Cargo.toml # Rust dependencies
├── tauri.conf.json # Tauri window & app configuration
├── src/
│ └── main.rs # Rust entry point and native logic
└── icons/ # Native application icons
Sources: desktop/README.md:79-88
Summary
Desktop App Development for Onyx leverages Tauri to provide a high-performance, native alternative to the browser interface. By sharing the Opal design system with the web frontend, the desktop app maintains full feature parity while offering better system integration, such as native window management and global shortcuts. Development requires a dual environment of Node.js for the UI and Rust for the native shell.
Sources: desktop/README.md:5-13, desktop/AGENTS.md:5-10