Claude Skill

desktop-ipc-electron

Type-safe Electron IPC patterns with typed channels, electron-trpc, MessagePort, and utility process communication

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_desktop-ipc-electron_skills_desktop-ipc-electron-707467a.zip · 17 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/desktop-ipc-electron/skills/desktop-ipc-electron
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Electron Type-Safe IPC Patterns

Quick Guide: All Electron IPC flows through a preload script using contextBridge.exposeInMainWorld(). Make it type-safe by defining a shared channel map that constrains channel names, payloads, and return types across main, preload, and renderer. For end-to-end type safety with minimal boilerplate, use electron-trpc (tRPC over IPC). For high-throughput streaming or renderer-to-renderer communication, use MessageChannelMain/MessagePort. For CPU-intensive background work, use utilityProcess with parentPort. Always validate IPC input in the main process -- treat renderer messages as untrusted.


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST validate and sanitize ALL data received via IPC in the main process -- treat renderer messages as untrusted input)

(You MUST use contextBridge.exposeInMainWorld() in preload scripts -- never expose ipcRenderer directly)

(You MUST define IPC channel names and payload types in a single shared file -- never use untyped string literals for channel names)

(You MUST use ipcMain.handle() / ipcRenderer.invoke() for request-response IPC -- sendSync blocks the renderer)

(You MUST clean up IPC listeners when components unmount or windows close -- listener leaks cause memory issues and duplicate handlers)

</critical_requirements>


Auto-detection: Electron IPC, ipcMain, ipcRenderer, contextBridge, preload, type-safe IPC, electron-trpc, ipcLink, createIPCHandler, exposeElectronTRPC, MessageChannelMain, MessagePortMain, MessagePort, utilityProcess, parentPort, typed channels, IPC channel map, postMessage, webContents.send, ipcMain.handle, ipcRenderer.invoke

When to use:

  • Adding type safety to Electron IPC communication
  • Setting up electron-trpc for end-to-end typed IPC
  • Defining shared channel/payload types between main and renderer
  • Building typed preload APIs with contextBridge
  • Using MessagePort for high-throughput or renderer-to-renderer communication
  • Implementing utility process IPC for background tasks
  • Validating and sanitizing IPC input in main process handlers

When NOT to use:

  • Choosing a UI framework for the renderer (use the appropriate framework skill)
  • General Electron app setup, packaging, or native APIs (use the Electron framework skill)
  • Simple IPC that does not need type safety beyond basic JavaScript

Key patterns covered:

  • Shared IPC channel map with typed payloads and return types
  • Typed preload API via contextBridge with declaration augmentation
  • electron-trpc for end-to-end type safety (queries, mutations, subscriptions)
  • Request-response (handle/invoke) with typed wrappers
  • Fire-and-forget (on/send) with typed channels
  • Main-to-renderer push (webContents.send) with typed events
  • MessagePort for high-throughput and renderer-to-renderer communication
  • Utility process IPC with parentPort and MessagePort transfer
  • IPC input validation and channel allowlisting

Detailed Resources:




<decision_framework>

Decision Framework

Which Type Safety Approach?

How many IPC channels does the app have?
+-- 1-5 channels?
|   +-- Shared channel map + typed wrappers (no dependencies)
+-- 5-20 channels?
|   +-- Shared channel map works, but electron-trpc adds value
+-- 20+ channels or complex validation?
|   +-- electron-trpc (Zod validation + typed client)
+-- Need subscriptions / real-time updates?
    +-- electron-trpc subscriptions OR MessagePort

Which IPC Pattern?

Renderer needs a response from main?
+-- YES --> ipcMain.handle() + ipcRenderer.invoke()
Renderer sends data, no response needed?
+-- YES --> ipcMain.on() + ipcRenderer.send()
Main needs to push data to renderer?
+-- YES --> webContents.send() + ipcRenderer.on() (in preload)
Two renderers need to communicate?
+-- YES --> MessagePort (set up via main process)
High-frequency streaming data?
+-- YES --> MessagePort (avoids per-message IPC overhead)
CPU-intensive background work?
+-- YES --> utilityProcess.fork() + parentPort

</decision_framework>


<red_flags>

RED FLAGS

Critical Security Issues:

  • Exposing ipcRenderer directly via contextBridge instead of wrapping specific channels -- gives renderer full IPC access
  • Not validating IPC arguments in main process handlers -- path traversal, injection, privilege escalation
  • Using ipcRenderer.sendSync() -- blocks the entire renderer process, causes UI freezes
  • Accepting arbitrary file paths from renderer without resolving and checking boundaries

Type Safety Issues:

  • Using string literals for channel names without a shared type map -- typos become runtime bugs
  • Defining IPC types separately in main and renderer -- they will drift apart
  • Not augmenting window type with the preload API -- renderer code has no autocompletion
  • Using any for IPC payloads -- defeats the purpose of typed IPC

Architecture Issues:

  • Not cleaning up ipcRenderer.on listeners when components unmount -- causes memory leaks and duplicate handlers
  • Direct renderer-to-renderer communication without going through main or MessagePort -- not possible in Electron
  • Putting business logic in the renderer that should live in main
  • Using child_process.fork() instead of utilityProcess.fork() in Electron apps

electron-trpc Gotchas:

  • Forgetting exposeElectronTRPC() in the preload script -- client silently fails
  • Not using a transformer (e.g., SuperJSON) when procedures return Date, Map, or Set -- serialization loses type information
  • Subscriptions auto-cancel on window navigation -- resubscribe if the page is a SPA that does not reload
  • Custom error classes lose properties during IPC serialization -- use plain error objects or error codes

MessagePort Gotchas:

  • Ports must be transferred via postMessage, not send or invoke -- the transfer list is a third argument
  • Main side must call port.start() explicitly -- forgetting this means no messages flow
  • port.close event fires when the remote end is garbage collected -- handle gracefully
  • SharedArrayBuffer is NOT reliably supported in Electron across process boundaries due to cross-origin isolation limitations

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST validate and sanitize ALL data received via IPC in the main process -- treat renderer messages as untrusted input)

(You MUST use contextBridge.exposeInMainWorld() in preload scripts -- never expose ipcRenderer directly)

(You MUST define IPC channel names and payload types in a single shared file -- never use untyped string literals for channel names)

(You MUST use ipcMain.handle() / ipcRenderer.invoke() for request-response IPC -- sendSync blocks the renderer)

(You MUST clean up IPC listeners when components unmount or windows close -- listener leaks cause memory issues and duplicate handlers)

Failure to follow these rules will create security vulnerabilities, type mismatches across process boundaries, and memory leaks.

</critical_reminders>

Files (skills)
  • examples
    • core.md 10 KB
      Loading…
    • electron-trpc.md 9.1 KB
      Loading…
    • message-ports.md 9.8 KB
      Loading…
  • reference.md 4.6 KB
    Loading…
  • SKILL.md 16.4 KB
    ---
    name: desktop-ipc-electron
    description: Type-safe Electron IPC patterns with typed channels, electron-trpc, MessagePort, and utility process communication
    ---
    
    # Electron Type-Safe IPC Patterns
    
    > **Quick Guide:** All Electron IPC flows through a preload script using `contextBridge.exposeInMainWorld()`. Make it type-safe by defining a shared channel map that constrains channel names, payloads, and return types across main, preload, and renderer. For end-to-end type safety with minimal boilerplate, use `electron-trpc` (tRPC over IPC). For high-throughput streaming or renderer-to-renderer communication, use `MessageChannelMain`/`MessagePort`. For CPU-intensive background work, use `utilityProcess` with `parentPort`. Always validate IPC input in the main process -- treat renderer messages as untrusted.
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST validate and sanitize ALL data received via IPC in the main process -- treat renderer messages as untrusted input)**
    
    **(You MUST use `contextBridge.exposeInMainWorld()` in preload scripts -- never expose `ipcRenderer` directly)**
    
    **(You MUST define IPC channel names and payload types in a single shared file -- never use untyped string literals for channel names)**
    
    **(You MUST use `ipcMain.handle()` / `ipcRenderer.invoke()` for request-response IPC -- `sendSync` blocks the renderer)**
    
    **(You MUST clean up IPC listeners when components unmount or windows close -- listener leaks cause memory issues and duplicate handlers)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** Electron IPC, ipcMain, ipcRenderer, contextBridge, preload, type-safe IPC, electron-trpc, ipcLink, createIPCHandler, exposeElectronTRPC, MessageChannelMain, MessagePortMain, MessagePort, utilityProcess, parentPort, typed channels, IPC channel map, postMessage, webContents.send, ipcMain.handle, ipcRenderer.invoke
    
    **When to use:**
    
    - Adding type safety to Electron IPC communication
    - Setting up electron-trpc for end-to-end typed IPC
    - Defining shared channel/payload types between main and renderer
    - Building typed preload APIs with contextBridge
    - Using MessagePort for high-throughput or renderer-to-renderer communication
    - Implementing utility process IPC for background tasks
    - Validating and sanitizing IPC input in main process handlers
    
    **When NOT to use:**
    
    - Choosing a UI framework for the renderer (use the appropriate framework skill)
    - General Electron app setup, packaging, or native APIs (use the Electron framework skill)
    - Simple IPC that does not need type safety beyond basic JavaScript
    
    **Key patterns covered:**
    
    - Shared IPC channel map with typed payloads and return types
    - Typed preload API via contextBridge with declaration augmentation
    - electron-trpc for end-to-end type safety (queries, mutations, subscriptions)
    - Request-response (`handle`/`invoke`) with typed wrappers
    - Fire-and-forget (`on`/`send`) with typed channels
    - Main-to-renderer push (`webContents.send`) with typed events
    - MessagePort for high-throughput and renderer-to-renderer communication
    - Utility process IPC with `parentPort` and MessagePort transfer
    - IPC input validation and channel allowlisting
    
    ---
    
    **Detailed Resources:**
    
    - [examples/core.md](examples/core.md) - Shared channel map, typed preload, typed wrappers, declaration augmentation
    - [examples/electron-trpc.md](examples/electron-trpc.md) - electron-trpc setup, queries, mutations, subscriptions
    - [examples/message-ports.md](examples/message-ports.md) - MessagePort patterns, renderer-to-renderer, utility process IPC
    - [reference.md](reference.md) - IPC method quick reference, decision framework, security checklist
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    Electron IPC is stringly typed by default -- channel names are plain strings, payloads are `any`, and there is no compile-time guarantee that the main process handler matches what the renderer sends. Type-safe IPC solves this by defining a single source of truth for channel names, argument types, and return types, then threading those types through typed wrapper functions.
    
    **Three levels of type safety, pick one:**
    
    1. **Shared channel map + typed wrappers** (DIY) -- define an `IpcChannelMap` interface, create thin typed wrappers around `ipcMain`/`ipcRenderer`. Zero dependencies, full control.
    2. **electron-trpc** (library) -- tRPC over Electron IPC. Define a router in main with Zod-validated procedures, get a fully typed client in the renderer. Best DX for complex apps.
    3. **MessagePort with typed messages** -- for high-throughput streaming or renderer-to-renderer communication where standard IPC overhead matters.
    
    **When to use each:**
    
    - **Shared channel map:** Most apps. Simple, no dependencies, covers `handle`/`invoke`, `send`/`on`, and `webContents.send`.
    - **electron-trpc:** Apps with many IPC endpoints, complex input validation, or subscription needs. Worth the dependency when you have 10+ IPC channels.
    - **MessagePort:** Real-time data feeds, large binary transfers, or direct renderer-to-renderer communication. Not a replacement for standard IPC -- an addition for specific high-throughput needs.
    
    **When NOT to use type-safe IPC:**
    
    - Prototyping where speed matters more than safety
    - Apps with 1-2 trivial IPC calls where the overhead of typed infrastructure is not justified
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: Shared IPC Channel Map
    
    Define all channel names, argument types, and return types in a single shared file. Both main and renderer import from this file.
    
    ```typescript
    // shared/ipc-channels.ts
    export interface IpcHandleChannels {
      "file:read": (filePath: string) => { content: string };
      "file:write": (filePath: string, content: string) => { success: boolean };
      "dialog:open": (options: OpenDialogOptions) => string | null;
      "app:version": () => string;
    }
    
    export interface IpcSendChannels {
      "analytics:track": [eventName: string, metadata: Record<string, unknown>];
      "log:error": [message: string, stack?: string];
    }
    
    export interface IpcMainToRendererChannels {
      "update:progress": { percent: number; message: string };
      "update:available": { version: string };
      "theme:changed": "light" | "dark";
    }
    ```
    
    **Why good:** Single source of truth for all IPC contracts, TypeScript catches mismatches at compile time, channel names are autocompleted
    
    See [examples/core.md](examples/core.md) for typed wrappers that consume this map.
    
    ---
    
    ### Pattern 2: Typed Preload with contextBridge
    
    Build a typed preload API from the channel map, then augment `window` so the renderer gets full autocompletion.
    
    ```typescript
    // preload.ts
    import { contextBridge, ipcRenderer } from "electron";
    import type {
      IpcHandleChannels,
      IpcSendChannels,
    } from "../shared/ipc-channels";
    
    type ElectronAPI = {
      invoke: <C extends keyof IpcHandleChannels>(
        channel: C,
        ...args: Parameters<IpcHandleChannels[C]>
      ) => Promise<ReturnType<IpcHandleChannels[C]>>;
      send: <C extends keyof IpcSendChannels>(
        channel: C,
        ...args: IpcSendChannels[C]
      ) => void;
      on: (channel: string, callback: (...args: unknown[]) => void) => () => void;
    };
    
    contextBridge.exposeInMainWorld("electronAPI", {
      invoke: (channel, ...args) => ipcRenderer.invoke(channel, ...args),
      send: (channel, ...args) => ipcRenderer.send(channel, ...args),
      on: (channel, callback) => {
        const listener = (_event: unknown, ...args: unknown[]) => callback(...args);
        ipcRenderer.on(channel, listener);
        return () => ipcRenderer.removeListener(channel, listener);
      },
    } satisfies ElectronAPI);
    ```
    
    ```typescript
    // shared/electron-api.d.ts -- augment window for renderer autocompletion
    import type { ElectronAPI } from "../preload";
    
    declare global {
      interface Window {
        electronAPI: ElectronAPI;
      }
    }
    ```
    
    **Why good:** renderer gets autocomplete on channel names and typed payloads, `on` returns an unsubscribe function for easy cleanup
    
    See [examples/core.md](examples/core.md) for the full pattern with main process typed handlers.
    
    ---
    
    ### Pattern 3: electron-trpc for End-to-End Type Safety
    
    For apps with many IPC endpoints, electron-trpc provides the best developer experience by leveraging tRPC's router pattern.
    
    ```typescript
    // main/router.ts
    import { initTRPC } from "@trpc/server";
    import { z } from "zod";
    
    const t = initTRPC.create({ isServer: true });
    
    export const router = t.router({
      readFile: t.procedure
        .input(z.object({ path: z.string() }))
        .query(async ({ input }) => {
          const content = await fs.readFile(input.path, "utf-8");
          return { content };
        }),
      saveSettings: t.procedure
        .input(z.object({ theme: z.enum(["light", "dark"]) }))
        .mutation(async ({ input }) => {
          await saveToStore(input);
          return { success: true };
        }),
    });
    
    export type AppRouter = typeof router;
    ```
    
    ```typescript
    // renderer/client.ts
    import { createTRPCProxyClient } from "@trpc/client";
    import { ipcLink } from "electron-trpc/renderer";
    import type { AppRouter } from "../main/router";
    
    export const trpc = createTRPCProxyClient<AppRouter>({
      links: [ipcLink()],
    });
    
    // Fully typed -- autocomplete on procedures, typed input/output
    const result = await trpc.readFile.query({ path: "/some/file.txt" });
    ```
    
    **Why good:** Zod validates input at runtime in main, TypeScript validates at compile time in renderer, adding a new procedure auto-surfaces in the client
    
    See [examples/electron-trpc.md](examples/electron-trpc.md) for full setup including preload, subscriptions, and context patterns.
    
    ---
    
    ### Pattern 4: IPC Input Validation
    
    Always validate arguments in main process handlers. The renderer can be compromised via XSS -- main process handlers have full Node.js access.
    
    ```typescript
    // main/handlers.ts
    const ALLOWED_EXTENSIONS = new Set([".txt", ".md", ".json"]);
    const MAX_CONTENT_LENGTH = 10 * 1024 * 1024; // 10MB
    
    ipcMain.handle("file:read", async (_event, filePath: unknown) => {
      // Type check
      if (typeof filePath !== "string") {
        throw new Error("filePath must be a string");
      }
      // Path traversal prevention
      const resolved = path.resolve(app.getPath("userData"), filePath);
      if (!resolved.startsWith(app.getPath("userData"))) {
        throw new Error("Access denied: path outside allowed directory");
      }
      // Extension allowlist
      const ext = path.extname(resolved);
      if (!ALLOWED_EXTENSIONS.has(ext)) {
        throw new Error(`File type not allowed: ${ext}`);
      }
      return { content: await fs.readFile(resolved, "utf-8") };
    });
    ```
    
    **Why good:** validates type, prevents path traversal, restricts file extensions, uses named constants
    
    See [examples/core.md](examples/core.md) for a channel validation middleware pattern.
    
    ---
    
    ### Pattern 5: MessagePort for High-Throughput Communication
    
    Use `MessageChannelMain` for streaming data, large transfers, or direct renderer-to-renderer communication.
    
    ```typescript
    // main.ts -- create a port pair and send one end to renderer
    import { MessageChannelMain } from "electron";
    
    function createDataChannel(win: BrowserWindow): MessagePortMain {
      const { port1, port2 } = new MessageChannelMain();
      win.webContents.postMessage("port-transfer", null, [port2]);
      port1.start();
      return port1;
    }
    ```
    
    ```typescript
    // preload.ts -- receive port and expose to renderer
    ipcRenderer.on("port-transfer", (event) => {
      const [port] = event.ports;
      contextBridge.exposeInMainWorld("dataPort", port);
    });
    ```
    
    **Key points:** ports are transferred via `postMessage` (not `send`/`invoke`), `port.start()` must be called on the main side, renderer side auto-starts when adding a `message` listener.
    
    See [examples/message-ports.md](examples/message-ports.md) for renderer-to-renderer and utility process patterns.
    
    ---
    
    ### Pattern 6: Utility Process IPC
    
    Use `utilityProcess.fork()` for CPU-intensive work. Communication flows through `parentPort`.
    
    ```typescript
    // main.ts
    import { utilityProcess } from "electron";
    
    const worker = utilityProcess.fork(path.join(__dirname, "worker.js"));
    worker.postMessage({ type: "process-data", payload: largeDataset });
    worker.on("message", (result) => {
      mainWindow.webContents.send("processing-complete", result);
    });
    ```
    
    ```typescript
    // worker.ts (runs in utility process)
    process.parentPort.on("message", (event) => {
      const { type, payload } = event.data;
      if (type === "process-data") {
        const result = heavyComputation(payload);
        process.parentPort.postMessage({ type: "result", data: result });
      }
    });
    ```
    
    **Key points:** utility processes have full Node.js access, communicate via `parentPort.postMessage()`, and should be used instead of `child_process.fork()` in Electron apps.
    
    See [examples/message-ports.md](examples/message-ports.md) for typed utility process communication.
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    ### Which Type Safety Approach?
    
    ```
    How many IPC channels does the app have?
    +-- 1-5 channels?
    |   +-- Shared channel map + typed wrappers (no dependencies)
    +-- 5-20 channels?
    |   +-- Shared channel map works, but electron-trpc adds value
    +-- 20+ channels or complex validation?
    |   +-- electron-trpc (Zod validation + typed client)
    +-- Need subscriptions / real-time updates?
        +-- electron-trpc subscriptions OR MessagePort
    ```
    
    ### Which IPC Pattern?
    
    ```
    Renderer needs a response from main?
    +-- YES --> ipcMain.handle() + ipcRenderer.invoke()
    Renderer sends data, no response needed?
    +-- YES --> ipcMain.on() + ipcRenderer.send()
    Main needs to push data to renderer?
    +-- YES --> webContents.send() + ipcRenderer.on() (in preload)
    Two renderers need to communicate?
    +-- YES --> MessagePort (set up via main process)
    High-frequency streaming data?
    +-- YES --> MessagePort (avoids per-message IPC overhead)
    CPU-intensive background work?
    +-- YES --> utilityProcess.fork() + parentPort
    ```
    
    </decision_framework>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **Critical Security Issues:**
    
    - Exposing `ipcRenderer` directly via `contextBridge` instead of wrapping specific channels -- gives renderer full IPC access
    - Not validating IPC arguments in main process handlers -- path traversal, injection, privilege escalation
    - Using `ipcRenderer.sendSync()` -- blocks the entire renderer process, causes UI freezes
    - Accepting arbitrary file paths from renderer without resolving and checking boundaries
    
    **Type Safety Issues:**
    
    - Using string literals for channel names without a shared type map -- typos become runtime bugs
    - Defining IPC types separately in main and renderer -- they will drift apart
    - Not augmenting `window` type with the preload API -- renderer code has no autocompletion
    - Using `any` for IPC payloads -- defeats the purpose of typed IPC
    
    **Architecture Issues:**
    
    - Not cleaning up `ipcRenderer.on` listeners when components unmount -- causes memory leaks and duplicate handlers
    - Direct renderer-to-renderer communication without going through main or MessagePort -- not possible in Electron
    - Putting business logic in the renderer that should live in main
    - Using `child_process.fork()` instead of `utilityProcess.fork()` in Electron apps
    
    **electron-trpc Gotchas:**
    
    - Forgetting `exposeElectronTRPC()` in the preload script -- client silently fails
    - Not using a transformer (e.g., SuperJSON) when procedures return `Date`, `Map`, or `Set` -- serialization loses type information
    - Subscriptions auto-cancel on window navigation -- resubscribe if the page is a SPA that does not reload
    - Custom error classes lose properties during IPC serialization -- use plain error objects or error codes
    
    **MessagePort Gotchas:**
    
    - Ports must be transferred via `postMessage`, not `send` or `invoke` -- the transfer list is a third argument
    - Main side must call `port.start()` explicitly -- forgetting this means no messages flow
    - `port.close` event fires when the remote end is garbage collected -- handle gracefully
    - `SharedArrayBuffer` is NOT reliably supported in Electron across process boundaries due to cross-origin isolation limitations
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST validate and sanitize ALL data received via IPC in the main process -- treat renderer messages as untrusted input)**
    
    **(You MUST use `contextBridge.exposeInMainWorld()` in preload scripts -- never expose `ipcRenderer` directly)**
    
    **(You MUST define IPC channel names and payload types in a single shared file -- never use untyped string literals for channel names)**
    
    **(You MUST use `ipcMain.handle()` / `ipcRenderer.invoke()` for request-response IPC -- `sendSync` blocks the renderer)**
    
    **(You MUST clean up IPC listeners when components unmount or windows close -- listener leaks cause memory issues and duplicate handlers)**
    
    **Failure to follow these rules will create security vulnerabilities, type mismatches across process boundaries, and memory leaks.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.