electron-trpc

electron-trpc is an ergonomic and type-safe solution for building Inter-Process Communication (IPC) in Electron. It allows you to expose APIs from Electron's main process to one or more renderer processes using the tRPC pattern.

Key benefits include:

• Fully type-safe IPC: Leverages tRPC to provide inferred client types, ensuring end-to-end type safety between processes.
• Secure alternative to localhost: Uses native Electron IPC, which is faster and more secure than running local servers for communication.
• Full tRPC feature set: Supports Queries, Mutations, and Subscriptions, eliminating the need for manual, complex bi-directional IPC schemes.

Because electron-trpc relies on Electron's Context Isolation, you must use a preload script to expose the electron-trpc IPC channel to the renderer process. Use exposeElectronTRPC from electron-trpc/main within the process.once('loaded', ...) lifecycle hook.

import { exposeElectronTRPC } from 'electron-trpc/main';

process.once('loaded', async () => {
  exposeElectronTRPC();
});

To communicate with the main process, create a tRPC proxy client in your renderer code using createTRPCProxyClient from @trpc/client. You must provide the ipcLink from electron-trpc/renderer in the links array. This replaces standard HTTP or WebSocket links.

import { createTRPCProxyClient } from '@trpc/client';
import { ipcLink } from 'electron-trpc/renderer';

export const client = createTRPCProxyClient({
  links: [ipcLink()],
});

Install electron-trpc using your preferred package manager. Note that you must also follow the standard tRPC installation instructions to build your router and client.

# pnpm
pnpm add electron-trpc

# yarn
yarn add electron-trpc

# npm
npm install --save electron-trpc

In your Electron main process, use createIPCHandler to connect your tRPC router to specific windows. You must pass your router and an array of windows (the BrowserWindow instances) to the handler. Ensure the windows are configured to use the preload script created in the previous step.

import { app } from 'electron';
import { createIPCHandler } from 'electron-trpc/main';
import { router } from './api';

app.on('ready', () => {
  const win = new BrowserWindow({
    webPreferences: {
      // Replace this path with the path to your BUILT preload file
      preload: 'path/to/preload.js',
    },
  });

  createIPCHandler({ router, windows: [win] });
});

The Playwright configuration for this project uses testMatch to identify end-to-end test files. It is configured to only include files that end with the .e2e.ts suffix.

export default defineConfig({
  testMatch: /.*\.e2e\.ts/,
});

The IPCHandler class (returned by createIPCHandler) allows you to manually manage which windows are connected to the tRPC bridge.

• attachWindow(win: BrowserWindow): Adds a new window to the handler. This is useful if windows are created dynamically after the handler has been initialized.
• detachWindow(win: BrowserWindow, webContentsId?: number): Removes a window from the handler and cleans up any active subscriptions associated with that window or its web contents.

Note: If you call detachWindow on a window that has already been destroyed, you must provide the webContentsId as an argument to avoid errors.

const handler = createIPCHandler({ router });

// Later, when a new window is created:
const newWin = new BrowserWindow();
handler.attachWindow(newWin);

// When a window is being closed or detached:
handler.detachWindow(newWin);

Use exposeElectronTRPC to bridge your tRPC router from the Electron Main process to the Renderer process. This function sets up the necessary IPC communication so that your frontend can call procedures defined in your backend router.

import { exposeElectronTRPC } from 'electron-trpc';
import { app, BrowserWindow } from 'electron';
import { yourRouter } from './router';

// Inside your main process setup
exposeElectronTRPC(app, yourRouter);