Electron Development Guidelines

Purpose

Establish secure and consistent patterns for Electron main process development in Gemini-Subtitle-Pro.

When to Use This Skill

Automatically activates when working on:

• Creating or modifying IPC handlers

• Working with preload scripts

• Native integrations (ffmpeg, whisper, yt-dlp)

• File system operations

• Desktop-specific features

• Protocol handlers

Quick Start

New IPC Channel Checklist

• Handler: Add in electron/main.ts using ipcMain.handle()

• Bridge: Expose in electron/preload.ts via contextBridge

• Types: Update src/types/electron.d.ts

• Naming: Use feature:action convention

Security Requirements (CRITICAL)

These settings MUST be maintained in electron/main.ts :

const mainWindow = new BrowserWindow({ webPreferences: { nodeIntegration: false, // NEVER change to true contextIsolation: true, // NEVER change to false sandbox: true, // NEVER change to false preload: path.join(__dirname, 'preload.js'), }, });

Why?

• nodeIntegration: false

• Prevents renderer from accessing Node.js APIs directly

• contextIsolation: true

• Separates preload from renderer context

• sandbox: true

• Limits preload script capabilities

IPC Contract Pattern

Step 1: Handler in main.ts

// electron/main.ts ipcMain.handle('video:compress', async (event, options: CompressOptions) => { try { const result = await compressVideo(options); return { success: true, data: result }; } catch (error) { return { success: false, error: error.message }; } });

Step 2: Bridge in preload.ts

// electron/preload.ts contextBridge.exposeInMainWorld('electronAPI', { compressVideo: (options: CompressOptions) => ipcRenderer.invoke('video:compress', options), });

Step 3: Types in electron.d.ts

// src/types/electron.d.ts interface ElectronAPI { compressVideo: (options: CompressOptions) => Promise<CompressResult>; }

declare global { interface Window { electronAPI: ElectronAPI; } }

Step 4: Use in Renderer

// src/services/video/compressor.ts const result = await window.electronAPI.compressVideo(options);

Directory Structure

electron/ ├── main.ts # Main process entry, IPC handlers ├── preload.ts # Context bridge ├── logger.ts # Logging utilities ├── i18n.ts # i18n for main process ├── locales/ # Main process locales └── services/ # Native service integrations ├── ffmpegService.ts ├── localWhisper.ts └── videoPreviewTranscoder.ts

Naming Conventions

IPC Channels

Use feature:action format:

// ✅ Good 'video:compress'; 'audio:extract'; 'subtitle:export'; 'file:select'; 'app:getVersion';

// ❌ Bad 'compressVideo'; 'COMPRESS_VIDEO'; 'video_compress';

Resource Files

For detailed guidelines, see the resources directory:

• ipc-patterns.md - IPC communication patterns

• native-services.md - Native service integration

• security-guide.md - Security best practices