desktop

lobehub/lobehub

Electron desktop development guide for LobeHub — IPC, controllers, preload scripts, and window management.

What is desktop?

A reference guide for building Electron desktop features in LobeHub. Use this when adding new desktop capabilities, setting up IPC communication between main and renderer processes, or managing windows and menus.

Create controllers in the main process with IPC method decorators
Define type-safe IPC interfaces for main-renderer communication
Build renderer services that invoke main process functionality
Implement store actions for state management
Configure window and menu behavior
Write tests for desktop controllers

How to install desktop

npx skills add https://github.com/lobehub/lobehub --skill desktop

Prerequisites

Familiarity with Electron architecture (main/renderer processes)
Understanding of TypeScript and async/await patterns
Access to LobeHub repository structure
Node.js development environment

Claude Code

Cursor

Windsurf

Cline

How to use desktop

1.Review the architecture overview to understand main process, renderer process, and preload script roles
2.Create a new controller class in apps/desktop/src/main/controllers/ extending ControllerModule
3.Define IPC types in packages/electron-client-ipc/src/types/ for your feature's parameters and return values
4.Register your controller in apps/desktop/src/main/controllers/registry.ts
5.Create a renderer service in src/services/electron/ that calls the IPC method
6.Implement store actions in src/store/ to manage state from the service
7.Write tests in apps/desktop/src/main/controllers/__tests__/ to verify controller behavior
8.Reference the detailed guides in references/ for menu configuration, window management, or local tools workflow

Use cases

Good for

Adding a new system feature (file access, notifications, etc.) to the LobeHub desktop app
Setting up bidirectional communication between Electron main and renderer processes
Implementing menu items or window controls that require main process access
Creating a local tool integration that needs system-level permissions
Testing desktop-specific functionality before deployment

Who it's for

Electron/desktop developers
LobeHub contributors extending desktop features
Full-stack developers building cross-platform apps
Teams maintaining Electron-based applications

desktop FAQ

Where do I put code that needs system-level access?

System-level code goes in the main process controller (apps/desktop/src/main/controllers/). Use IPC methods to expose it safely to the renderer process.

How do I safely communicate between main and renderer processes?

Define types in packages/electron-client-ipc/src/types/, create a controller with @IpcMethod() decorators, and call it from a renderer service using the ensureElectronIpc() utility.

What's the purpose of preload scripts?

Preload scripts securely expose main process APIs to the renderer process without exposing the full Electron API, reducing security risks.

Where should I configure app menus and windows?

Refer to references/menu-config.md for menu configuration and references/window-management.md for window setup and lifecycle management.

How do I test new desktop features?

Write tests in apps/desktop/src/main/controllers/__tests__/ that verify your controller methods return expected results.

Full instructions (SKILL.md)

Source of truth, from lobehub/lobehub.

name: desktop description: Electron desktop development guide — IPC handlers, controllers, preload scripts, window/menu management. disable-model-invocation: true

Desktop Development Guide

Architecture Overview

LobeHub desktop is built on Electron with main-renderer architecture:

Main Process (apps/desktop/src/main): App lifecycle, system APIs, window management
Renderer Process: Reuses web code from src/
Preload Scripts (apps/desktop/src/preload): Securely expose main process to renderer

Adding New Desktop Features

1. Create Controller

Location: apps/desktop/src/main/controllers/

import { ControllerModule, IpcMethod } from '@/controllers';

export default class NewFeatureCtr extends ControllerModule {
  static override readonly groupName = 'newFeature';

  @IpcMethod()
  async doSomething(params: SomeParams): Promise<SomeResult> {
    // Implementation
    return { success: true };
  }
}

2. Define IPC Types

Location: packages/electron-client-ipc/src/types/<domain>.ts, re-exported from types/index.ts

export interface SomeParams {
  /* ... */
}
export interface SomeResult {
  success: boolean;
  error?: string;
}

3. Create Renderer Service

Location: src/services/electron/

import { ensureElectronIpc } from '@/utils/electron/ipc';

const ipc = ensureElectronIpc();

export const newFeatureService = async (params: SomeParams) => {
  return ipc.newFeature.doSomething(params);
};