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