Getting Started

Installation

Follow installation instructions for trpc to build your router and client of choice.

pnpm

pnpm add electron-trpc-experimental

yarn

yarn add electron-trpc-experimental

npm

npm install --save add electron-trpc-experimental

TypeScript

It’s worth noting that you’ll need to figure out how to get TypeScript working on both the main process and render process client code. For one example of how to do this with a good developer experience (minimal configuration, fast bundling, client hot-reloading) see our basic examples.

Code

Preload

electron-trpc-experimental depends on Electron’s Context Isolation feature, and exposes the electron-trpc IPC channel to render processes using a preload file.

Some familiarization with these concepts can be helpful in case of unexpected issues during setup.

This is the most minimal working preload file for using electron-trpc-experimental. Depending on your application, you may need to add this to an existing preload file or customize it later.

preload.ts

import { exposeElectronTRPC } from 'electron-trpc-experimental/preload';

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

Main

In the main electron process, you will want to expose a tRPC router to one or more windows. These windows need to use the preload file you created.

main.ts

import { app } from 'electron';
import { createIPCHandler } from 'electron-trpc-experimental/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] });
});

Renderer

Windows you construct with the preload file and the IPC handler can reach the tRPC router in the main process over IPC. To do this, a script in the window needs to create a tRPC client using the IPC link:

renderer.ts

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

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

To use a different client, follow the appropriate usage instructions in the tRPC docs, ensuring that you substitute any HTTP or websocket links with the ipcLink.

Using Transformers

Transformers in tRPC allow you to serialize and deserialize data that can’t be directly transferred over JSON, such as Date objects, Map, Set, BigInt, etc. When using transformers with electron-trpc-experimental, you need to configure them on both the server (main process) and client (renderer process).

Install a transformer

First, install a transformer library like superjson:

# pnpm
pnpm add superjson

# yarn
yarn add superjson

# npm
npm install --save superjson

Configure the router (Main Process)

Configure your tRPC router to use the transformer:

api.ts

import { initTRPC } from '@trpc/server';
import superjson from 'superjson';
import { z } from 'zod';

const t = initTRPC.create({
isServer: true,
transformer: superjson
});

export const router = t.router({
  greeting: t.procedure
    .input(z.object({ name: z.string() }))
    .query((req) => {
      return {
        text: `Hello ${req.input.name}`,
        timestamp: new Date(), // Date objects require transformation
      };
    }),
});

Configure the client (Renderer Process)

Configure your tRPC client to use the same transformer:

renderer.ts

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

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

Important Notes

• Keep transformers in sync: The transformer used on the server (main process) must match the transformer used on the client (renderer process).
• Popular transformers: superjson is a popular choice that supports Dates, RegExp, Map, Set, BigInt, and more.
• Custom transformers: You can also create custom transformers following the tRPC transformer documentation.

For a complete working example with transformers, see our superjson example .