Skip to main content
skill CX Codex

electron · gentleman-programming — Claude Code skill: what it does, how to install

Guides desktop app development in Electron with secure IPC patterns, typed channels, and clear separation between main and renderer processes.

MIT 175 installs ★ 678 updated 2026-03-28

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add Gentleman-Programming/Gentleman-Skills --skill electron -a claude-code
Open on GitHub

What electron does

The skill organizes an Electron application into clear directories for main, preload, renderer, and shared types. It enforces baseline security in BrowserWindow settings by specifying contextIsolation: true, nodeIntegration: false, and sandbox: true.

It provides structured patterns for type-safe IPC communication via contextBridge and TypeScript interfaces. This setup bridges UI components with OS dialogs, local file operations, and electron-store without exposing raw Node.js primitives to the browser layer.

What it helps with

  • separate main, preload, and renderer layers cleanly
  • configure secure IPC using contextBridge and sandboxing
  • define typed request and response contracts for IPC channels
  • integrate native file dialogs and persistent storage into UI components

Example prompts for the agent

  • Scaffold an Electron project structure with React and TypeScript
  • Create a type-safe IPC handler for file reading and writing
  • Set up contextBridge in preload to expose safe app version calls

How to install electron

1Skills CLI (Vercel)

npx skills add Gentleman-Programming/Gentleman-Skills --skill electron -a claude-code

2Manually: put the files in place

~/.claude/skills/electron/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/electron/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about electron

How do I install electron in Claude Code?

Run npx skills add Gentleman-Programming/Gentleman-Skills --skill electron -a claude-code.

What does the electron skill do?

It guides your coding agent to scaffold reliable Electron apps with type-safe IPC, secure preload scripts, and separated process boundaries.

Why does this skill enforce contextIsolation?

Leaving isolation disabled gives renderer scripts direct access to Node.js internals. The skill enforces contextBridge so that the UI accesses system features strictly through explicit channel declarations.

Source text

SKILL.md · MIT
---
name: electron
description: >
  Electron patterns for building cross-platform desktop applications.
  Trigger: When building desktop apps, working with Electron main/renderer processes, IPC communication, or native integrations.
metadata:
  author: gentleman-programming
  version: "1.0"
---

## When to Use

Load this skill when:
- Building cross-platform desktop applications
- Working with Electron's main and renderer processes
- Implementing IPC (Inter-Process Communication)
- Integrating native OS features (menus, notifications, file system)
- Setting up Electron with React, Vue, or other frameworks
- Configuring auto-updates and app distribution

## Critical Patterns

### Pattern 1: Project Structure

```
src/
├── main/                    # Main process (Node.js)
│   ├── index.ts            # Entry point
│   ├── ipc/                # IPC handlers
│   │   ├── handlers.ts
│   │   └── channels.ts     # Type-safe channel names
│   ├── services/           # Native services
│   │   ├── store.ts        # electron-store
│   │   └── updater.ts      # auto-updater
│   └── windows/            # Window management
│       └── main-window.ts
├── renderer/               # Renderer process (browser)
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/
│   │   └── hooks/
│   │       └── useIPC.ts   # IPC hooks
│   └── index.html
├── preload/                # Preload scripts
│   └── index.ts            # Expose safe APIs
└── shared/                 # Shared types
    └── types.ts
```

### Pattern 2: Secure IPC Communication

Always use contextBridge for secure communication:

```typescript
// preload/index.ts
import { contextBridge, ipcRenderer } from 'electron';
import type { IpcChannels } from '../shared/types';

// Type-safe exposed API
const electronAPI = {
  // One-way: renderer -> main
  send: <T extends keyof IpcChannels>(
    channel: T, 
    data: IpcChannels[T]['request']
  ) => {
    ipcRenderer.send(channel, data);
  },

  // Two-way: renderer -> main -> renderer
  invoke: <T extends keyof IpcChannels>(
    channel: T, 
    data: IpcChannels[T]['request']
  ): Promise<IpcChannels[T]['response']> => {
    return ipcRenderer.invoke(channel, data);
  },

  // Listen: main -> renderer
  on: <T extends keyof IpcChannels>(
    channel: T, 
    callback: (data: IpcChannels[T]['response']) => void
  ) => {
    const subscription = (_: Electron.IpcRendererEvent, data: IpcChannels[T]['response']) => {
      callback(data);
    };
    ipcRenderer.on(channel, subscription);
    return () => ipcRenderer.removeListener(channel, subscription);
  },
};

contextBridge.exposeInMainWorld('electron', electronAPI);
```

### Pattern 3: Type-Safe IPC Channels

Define all channels with request/response types:

```typescript
// shared/types.ts
export interface IpcChannels {
  'app:get-version': {
    request: void;
    response: string;
  };
  'file:read': {
    request: { path: string };
    response: { content: string } | { error: string };
  };
  'file:write': {
    request: { path: string; content: string };
    response: { success: boolean };
  };
  'dialog:open-file': {
    request: { filters?: Electron.FileFilter[] };
    response: string | null;
  };
  'store:get': {
    request: { key: string };
    response: unknown;
  };
  'store:set': {
    request: { key: string; value: unknown };
    response: void;
  };
}

// Extend Window interface for renderer
declare global {
  interface Window {
    electron: typeof electronAPI;
  }
}
```

## Code Examples

### Example 1: Main Process Setup

```typescript
// main/index.ts
import { app, BrowserWindow, ipcMain } from 'electron';
import path from 'path';
import { registerIpcHandlers } from './ipc/handlers';

let mainWindow: BrowserWindow | null = null;

async function createWindow() {
  mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    minWidth: 800,
    minHeight: 600,
    webPreferences: {
      preload: path.join(__dirname, '../preload/index.js'),
      contextIsolation: true,  // Required for security
      nodeIntegration: false,  // Required for security
      sandbox: true,           // Extra security
    },
    titleBarStyle: process.platform === 'darwin' ? 'hiddenInset' : 'default',
    trafficLightPosition: { x: 15, y: 10 },
  });

  // Register IPC handlers
  registerIpcHandlers();

  // Load the app
  if (process.env.NODE_ENV === 'development') {
    mainWindow.loadURL('http://localhost:5173');
    mainWindow.webContents.openDevTools();
  } else {
    mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'));
  }

  mainWindow.on('closed', () => {
    mainWindow = null;
  });
}

app.whenReady().then(createWindow);

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});
```

### Example 2: IPC Handlers

```typescript
// main/ipc/handlers.ts
import { ipcMain, dialog, app } from 'electron';
import fs from 'fs/promises';
import Store from 'electron-store';

const store = new Store();

export function registerIpcHandlers() {
  // Get app version
  ipcMain.handle('app:get-version', () => {
    return app.getVersion();
  });

  // File operations
  ipcMain.handle('file:read', async (_, { path }) => {
    try {
      const content = await fs.readFile(path, 'utf-8');
      return { content };
    } catch (error) {
      return { error: (error as Error).message };
    }
  });

  ipcMain.handle('file:write', async (_, { path, content }) => {
    try {
      await fs.writeFile(path, content, 'utf-8');
      return { success: true };
    } catch {
      return { success: false };
    }
  });

  // Native dialogs
  ipcMain.handle('dialog:open-file', async (_, { filters }) => {
    const result = await dialog.showOpenDialog({
      properties: ['openFile'],
      filters: filters || [{ name: 'All Files', extensions: ['*'] }],
    });
    return result.canceled ? null : result.filePaths[0];
  });

  // Persistent storage
  ipcMain.handle('store:get', (_, { key }) => {
    return store.get(key);
  });

  ipcMain.handle('store:set', (_, { key, value }) => {
    store.set(key, value);
  });
}
```

### Example 3: React Hook for IPC

```typescript
// renderer/src/hooks/useIPC.ts
import { useCallback, useEffect, useState } from 'react';

export function useIPC<T>(
  channel: string,
  initialValue: T
): [T, boolean, Error | null] {
  const [data, setData] = useState<T>(initialValue);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let mounted = true;

    window.electron
      .invoke(channel, undefined)
      .then((result) => {
        if (mounted) {
          setData(result as T);
          setLoading(false);
        }
      })
      .catch((err) => {
        if (mounted) {
          setError(err);
          setLoading(false);
        }
      });

    return () => {
      mounted = false;
    };
  }, [channel]);

  return [data, loading, error];
}

// Hook for IPC subscriptions
export function useIPCListener<T>(
  channel: string,
  callback: (data: T) => void
) {
  useEffect(() => {
    const unsubscribe = window.electron.on(channel, callback);
    return unsubscribe;
  }, [channel, callback]);
}

// Hook for IPC mutations
export function useIPCMutation<TRequest, TResponse>(channel: string) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const mutate = useCallback(
    async (data: TRequest): Promise<TResponse | null> => {
      setLoading(true);
      setError(null);
      try {
        const result = await window.electron.invoke(channel, data);
        return result as TResponse;
      } catch (err) {
        setError(err as Error);
        return null;
      } finally {
        setLoading(false);
      }
    },
    [channel]
  );

  return { mutate, loading, error };
}
```

### Example 4: Auto-Updater Setup

```typescript
// main/services/updater.ts
import { autoUpdater } from 'electron-updater';
import { BrowserWindow } from 'electron';
import log from 'electron-log';

export function setupAutoUpdater(mainWindow: BrowserWindow) {
  autoUpdater.logger = log;
  autoUpdater.autoDownload = false;
  autoUpdater.autoInstallOnAppQuit = true;

  autoUpdater.on('checking-for-update', () => {
    mainWindow.webContents.send('updater:checking');
  });

  autoUpdater.on('update-available', (info) => {
    mainWindow.webContents.send('updater:available', info);
  });

  autoUpdater.on('update-not-available', () => {
    mainWindow.webContents.send('updater:not-available');
  });

  autoUpdater.on('download-progress', (progress) => {
    mainWindow.webContents.send('updater:progress', progress);
  });

  autoUpdater.on('update-downloaded', () => {
    mainWindow.webContents.send('updater:downloaded');
  });

  autoUpdater.on('error', (error) => {
    mainWindow.webContents.send('updater:error', error.message);
  });

  // Check for updates on startup (with delay)
  setTimeout(() => {
    autoUpdater.checkForUpdates();
  }, 5000);
}

// IPC handlers for updater
export function registerUpdaterHandlers() {
  ipcMain.handle('updater:check', () => autoUpdater.checkForUpdates());
  ipcMain.handle('updater:download', () => autoUpdater.downloadUpdate());
  ipcMain.handle('updater:install', () => autoUpdater.quitAndInstall());
}
```

### Example 5: Native Menu Setup

```typescript
// main/menu.ts
import { Menu, shell, app, BrowserWindow } from 'electron';

export function createMenu(mainWindow: BrowserWindow) {
  const isMac = process.platform === 'darwin';

  const template: Electron.MenuItemConstructorOptions[] = [
    ...(isMac
      ? [{
          label: app.name,
          submenu: [
            { role: 'about' as const },
            { type: 'separator' as const },
            { role: 'services' as const },
            { type: 'separator' as const },
            { role: 'hide' as const },
            { role: 'hideOthers' as const },
            { role: 'unhide' as const },
            { type: 'separator' as const },
            { role: 'quit' as const },
          ],
        }]
      : []),
    {
      label: 'File',
      submenu: [
        {
          label: 'Open File',
          accelerator: 'CmdOrCtrl+O',
          click: () => mainWindow.webContents.send('menu:open-file'),
        },
        {
          label: 'Save',
          accelerator: 'CmdOrCtrl+S',
          click: () => mainWindow.webContents.send('menu:save'),
        },
        { type: 'separator' },
        isMac ? { role: 'close' } : { role: 'quit' },
      ],
    },
    {
      label: 'Edit',
      submenu: [
        { role: 'undo' },
        { role: 'redo' },
        { type: 'separator' },
        { role: 'cut' },
        { role: 'copy' },
        { role: 'paste' },
        { role: 'selectAll' },
      ],
    },
    {
      label: 'View',
      submenu: [
        { role: 'reload' },
        { role: 'forceReload' },
        { role: 'toggleDevTools' },
        { type: 'separator' },
        { role: 'togglefullscreen' },
      ],
    },
    {
      label: 'Help',
      submenu: [
        {
          label: 'Documentation',
          click: () => shell.openExternal('https://example.com/docs'),
        },
      ],
    },
  ];

  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
}
```

## Anti-Patterns

### Don't: Enable nodeIntegration

```typescript
// ❌ DANGEROUS - Never do this
const win = new BrowserWindow({
  webPreferences: {
    nodeIntegration: true,    // Security vulnerability!
    contextIsolation: false,  // Security vulnerability!
  },
});

// ✅ Safe - Always use contextIsolation with preload
const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    contextIsolation: true,
    nodeIntegration: false,
    sandbox: true,
  },
});
```

### Don't: Use Remote Module

```typescript
// ❌ Bad - remote is deprecated and insecure
const { BrowserWindow } = require('@electron/remote');

// ✅ Good - Use IPC for all main process access
// In renderer:
const result = await window.electron.invoke('dialog:open-file', {});
```

### Don't: Expose Entire ipcRenderer

```typescript
// ❌ Bad - exposes everything
contextBridge.exposeInMainWorld('electron', {
  ipcRenderer: ipcRenderer, // Never expose the entire module!
});

// ✅ Good - expose only specific, typed methods
contextBridge.exposeInMainWorld('electron', {
  invoke: (channel: string, data: unknown) => {
    const allowedChannels = ['app:get-version', 'file:read'];
    if (allowedChannels.includes(channel)) {
      return ipcRenderer.invoke(channel, data);
    }
    throw new Error(`Channel ${channel} not allowed`);
  },
});
```

## Quick Reference

| Task | Pattern |
|------|---------|
| Create project | `npm create electron-vite@latest` |
| Main process file access | Use Node.js `fs` module in main |
| Renderer file access | IPC through preload |
| Persistent storage | `electron-store` in main process |
| Auto-updates | `electron-updater` |
| Native notifications | `new Notification()` in main |
| System tray | `Tray` class in main |
| Keyboard shortcuts | `globalShortcut.register()` |
| Deep linking | `app.setAsDefaultProtocolClient()` |
| Code signing | `electron-builder` config |

## Resources

- [Electron Documentation](https://www.electronjs.org/docs/latest)
- [Electron Forge](https://www.electronforge.io/)
- [electron-vite](https://electron-vite.org/)
- [electron-builder](https://www.electron.build/)
- [Electron Security Checklist](https://www.electronjs.org/docs/latest/tutorial/security)

© gentleman-programming · MIT · Gentleman-Programming/Gentleman-Skills

Similar skills

All skills for Frontend and UI →

electron by other authors comes first.

From the same set20

The whole set →
github-pr github-pr guides AI agents to format pull requests using Conventional Commits and GitHub CLI commands. CX Codex +1 205installs playwright Skill for writing E2E tests on Playwright using the Page Objects pattern. Guides you through exploring real UI with MCP tools first, then writing selectors and assertions based on actual page structure. CX Codex +1 194installs elixir-antipatterns elixir-antipatterns is a Claude Code skill that guides code reviews, Ecto query tuning, and Phoenix refactoring with a catalog of 8 anti-patterns. CX Codex +1 194installs nextjs-15 Supplies Next.js 15 App Router patterns covering file conventions, Server Actions, parallel data fetching, and middleware. CX Codex +1 185installs skill-creator skill-creator builds new AI agent skills against the Agent Skills spec. Use it for recurring patterns, project rules, and workflows that need explicit steps. CX Codex +1 171installs django-drf django-drf is a Claude Code skill with patterns for Django REST APIs: ViewSets, serializers, filters, permissions, and tests. The patterns cover starting or extending an API. CX Codex +1 162installs angular-forms A skill for building Angular forms: covers Signal Forms (experimental, Angular 21+) and production-ready Reactive Forms. Activates when you work with form validation, state management, or form creation. CX Codex +1 150installs spring-boot-3 Rules an AI agent follows when it writes or refactors a Spring Boot 3 service: configuration, dependency injection and the web layer. CX Codex +1 143installs

Project sponsors

Companies that keep this analytics open