apps/desktop/README.md
LobeHub Desktop is a cross-platform desktop application for LobeHub, built with Electron, providing a more native desktop experience and functionality.
# Install dependencies
pnpm install-isolated
# Start development server
pnpm dev
# Type checking
pnpm type-check
# Run tests
pnpm test
Copy .env.desktop to .env and configure as needed:
cp .env.desktop .env
[!WARNING] Backup your
.envfile before making changes to avoid losing configurations.
| Command | Description |
|---|---|
pnpm build:main | Build main/preload (dist output only) |
pnpm package:mac | Package for macOS (Intel + Apple Silicon) |
pnpm package:win | Package for Windows |
pnpm package:linux | Package for Linux |
pnpm package:local | Local packaging build (no ASAR) |
pnpm package:local:reuse | Local packaging build reusing existing dist |
# 1. Development
pnpm dev # Start with hot reload
# 2. Code Quality
pnpm lint # ESLint checking
pnpm format # Prettier formatting
pnpm type-check # TypeScript validation
# 3. Testing
pnpm test # Run Vitest tests
# 4. Build & Package
pnpm build:main # Production build (dist only)
pnpm package:local # Local testing package
| Channel | Description | Stability | Auto-Updates |
|---|---|---|---|
| Stable | Thoroughly tested releases | ๐ข High | โ Yes |
| Beta | Pre-release with new features | ๐ก Medium | โ Yes |
| Nightly | Daily builds with latest changes | ๐ Low | โ Yes |
37.1.0 - Cross-platform desktop framework22+ - Backend runtime5.7+ - Type-safe development6.2+ - Build toolingThe desktop application uses a sophisticated dependency injection and event-driven architecture:
src/main/core/
โโโ App.ts # ๐ฏ Main application orchestrator
โโโ IoCContainer.ts # ๐ Dependency injection container
โโโ window/ # ๐ช Window management modules
โ โโโ WindowThemeManager.ts # ๐จ Theme synchronization
โ โโโ WindowPositionManager.ts # ๐ Position persistence
โ โโโ WindowErrorHandler.ts # โ ๏ธ Error boundaries
โ โโโ WindowConfigBuilder.ts # โ๏ธ Configuration builder
โโโ browser/ # ๐ Browser management modules
โ โโโ Browser.ts # ๐ช Individual window instances
โ โโโ BrowserManager.ts # ๐ฅ Multi-window coordinator
โโโ ui/ # ๐จ UI system modules
โ โโโ Tray.ts # ๐ System tray integration
โ โโโ TrayManager.ts # ๐ง Tray management
โ โโโ MenuManager.ts # ๐ Native menu system
โ โโโ ShortcutManager.ts # โจ๏ธ Global shortcuts
โโโ infrastructure/ # ๐ง Infrastructure services
โโโ StoreManager.ts # ๐พ Configuration storage
โโโ I18nManager.ts # ๐ Internationalization
โโโ UpdaterManager.ts # ๐ฆ Auto-update system
โโโ StaticFileServerManager.ts # ๐๏ธ Local file serving
The App.ts class orchestrates the entire application lifecycle through key phases:
@IpcMethod wires controller methods into type-safe channelssrc/main/utils/ipc/base.ts captures the IpcContext with AsyncLocalStorage, so controller logic can call getIpcContext() anywhere inside an IPC handler without explicitly threading arguments.src/main/controllers/registry.ts exports controllerIpcConstructors and DesktopIpcServices, enabling automatic typing of renderer IPC proxies.src/utils/electron/ipc.ts exposes ensureElectronIpc() which lazily builds a proxy on top of window.electronAPI.invoke, giving React/Next.js code a type-safe API surface without exposing raw proxies in preload.apps/desktop/src/main/exports.d.ts augments @lobechat/electron-client-ipc so every package can consume DesktopIpcServices without importing desktop business code directly.ControllerModule and expose renderer methods via @IpcMethodbeforeAppReady and afterAppReady for initialization phasesRenderer code uses a lightweight proxy generated at runtime to keep IPC calls type-safe without exposing raw Electron objects through contextBridge. Use the helper exported from src/utils/electron/ipc.ts to access the main-process services:
import { ensureElectronIpc } from '@/utils/electron/ipc';
const ipc = ensureElectronIpc();
await ipc.windows.openSettingsWindow({ tab: 'provider' });
The helper internally builds a proxy on top of window.electronAPI.invoke, so no proxy objects need to be cloned across the preload boundary.
apps/desktop/src/main/controllers/__tests__/ # Controller unit tests
tests/ # Integration tests
pnpm test # Run all tests
pnpm test:watch # Watch mode
pnpm type-check # Type validation
Desktop application development involves complex cross-platform considerations and native integrations. We welcome community contributions to improve functionality, performance, and user experience. You can participate in improvements through:
Development.md - Comprehensive development documentation/docs - Detailed technical specificationsCONTRIBUTING.md - Contribution guidelines