home / skills / lobehub / lobe-chat / desktop

desktop skill

Q: Where do I register a new controller?

Register it in apps/desktop/src/main/controllers/registry.ts so the main process loads it at startup.

safe

This skill helps you implement and manage Electron desktop features, IPC handlers, and windowing by following clear architectural patterns.

npx playbooks add skill lobehub/lobe-chat --skill desktop

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

2.3 KB

---
name: desktop
description: Electron desktop development guide. Use when implementing desktop features, IPC handlers, controllers, preload scripts, window management, menu configuration, or Electron-specific functionality. Triggers on desktop app development, Electron IPC, or desktop local tools implementation.
disable-model-invocation: true
---

# Desktop Development Guide

## Architecture Overview

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

1. **Main Process** (`apps/desktop/src/main`): App lifecycle, system APIs, window management
2. **Renderer Process**: Reuses web code from `src/`
3. **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/`

```typescript
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 };
  }
}
```

Register in `apps/desktop/src/main/controllers/registry.ts`.

### 2. Define IPC Types
Location: `packages/electron-client-ipc/src/types.ts`

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

### 3. Create Renderer Service
Location: `src/services/electron/`

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

const ipc = ensureElectronIpc();

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

### 4. Implement Store Action
Location: `src/store/`

### 5. Add Tests
Location: `apps/desktop/src/main/controllers/__tests__/`

## Detailed Guides

See `references/` for specific topics:
- **Feature implementation**: `references/feature-implementation.md`
- **Local tools workflow**: `references/local-tools.md`
- **Menu configuration**: `references/menu-config.md`
- **Window management**: `references/window-management.md`

## Best Practices

1. **Security**: Validate inputs, limit exposed APIs
2. **Performance**: Use async methods, batch data transfers
3. **UX**: Add progress indicators, provide error feedback
4. **Code organization**: Follow existing patterns, add documentation

Overview

This skill is a practical guide for building and extending the Electron-based desktop app. It focuses on implementing new desktop features, wiring IPC handlers, creating controllers and preload scripts, and managing windows and menus. Use it to integrate secure renderer-main communication and align new code with the project's architecture and conventions.

How this skill works

The guide inspects the main-renderer architecture and explains where to place controllers, preload scripts, IPC types, and renderer services. It shows the pattern for creating ControllerModule classes with @IpcMethod decorators, registering controllers, defining shared TypeScript IPC types, and consuming IPC from renderer services. It also points to reference docs for menus, windows, and local tools workflows.

When to use it

Adding a new desktop feature that requires main-process APIs
Exposing secure functionality from main to renderer via preload/IPC
Implementing or testing IPC controllers and their TypeScript types
Configuring application menus or custom window behavior
Integrating local development tools or native OS interactions

Best practices

Keep main-process surface minimal: expose only needed APIs via preload
Validate and sanitize all IPC input parameters in controllers
Prefer async methods and batch transfers to avoid UI jank
Follow existing controller and service patterns for consistent code organization
Add tests for main controllers under apps/desktop/src/main/controllers/__tests__

Example use cases

Create a new controller to access native file dialogs and expose a doSomething IPC method
Add a renderer service that calls ipc.myFeature.doSomething with typed params and result
Implement window-management flows: create, persist, and restore window state from main
Configure a native menu item that triggers a controller action via IPC
Build local tools integration that runs in main and returns status updates to renderer

FAQ

Where do I register a new controller?

How do I share types between main and renderer?

Define shared interfaces in packages/electron-client-ipc/src/types.ts and import them from both sides.

How should I expose main APIs to the renderer?

Use a preload script to securely expose a small, typed API surface and call controller IPC methods from the renderer via services.