electron-ipc-cat

Based on frankwallis/electron-ipc-proxy, and used in TiddlyGit-Desktop.

electron-ipc-cat

Passing object and type between Electron main process and renderer process simply via preload script.

Overview

In latest electron, the remote module is deprecated, and you are required to passing data using IPC. But it requires tons of boilerplate code to build up IPC bridge, just like the vanilla Redux.

Luckily we have frankwallis/electron-ipc-proxy which provide a good example about how to automatically build IPC channel for a class in the main process. But it doesn't work well when we have contextIsolation: true, so here we have electron-ipc-cat!

We wrap our main process class, and can use them from the window.xxx in the renderer and preload script. All types are preserved, so you can get typescript intellisense just like using a local function.

Install

pnpm i electron-ipc-cat

Example

Real use case in TiddlyGit-Desktop's workspace feature

1. The class

/** workspaces.ts */
export class Workspace implements IWorkspaceService {
  /**
   * Record from workspace id to workspace settings
   */
  private workspaces: Record<string, IWorkspace> = {};
  public workspaces$: BehaviorSubject<Record<string, IWorkspace>>;

  public async getWorkspacesAsList(): Promise<IWorkspace[]> {
    return Object.values(this.workspaces).sort((a, b) => a.order - b.order);
  }

  public async get(id: string): Promise<IWorkspace | undefined> {
    return this.workspaces[id];
  }

  public get$(id: string): Observable<IWorkspace | undefined> {
    return this.workspaces$.pipe(map((workspaces) => workspaces[id]));
  }
}

export interface IWorkspaceService {
  workspaces$: BehaviorSubject<Record<string, IWorkspace>>;
  getWorkspacesAsList(): Promise<IWorkspace[]>;
  get(id: string): Promise<IWorkspace | undefined>;
  get$(id: string): Observable<IWorkspace | undefined>;
}

export const WorkspaceServiceIPCDescriptor = {
  channel: WorkspaceChannel.name,
  properties: {
    workspaces$: ProxyPropertyType.Value$,
    getWorkspacesAsList: ProxyPropertyType.Function,
    get: ProxyPropertyType.Function,
    get$: ProxyPropertyType.Function$,
  },
};

2. bindServiceAndProxy in Main

/** bindServiceAndProxy.ts */

/**
 * Don't forget to edit src/preload/services.ts to export service to renderer process
 */
import { registerProxy } from 'electron-ipc-cat/server';

import serviceIdentifier from '@services/serviceIdentifier';
import { container } from '@services/container';

import { Workspace } from '@services/workspaces';
import { IWorkspaceService, WorkspaceServiceIPCDescriptor } from '@services/workspaces/interface';

function bindServiceAndProxy(): void {
  // if using inversifyjs
  container.bind<IWorkspaceService>(serviceIdentifier.Workspace).to(Workspace).inSingletonScope();
  const workspaceService = container.get<IWorkspaceService>(serviceIdentifier.Workspace);
  // if using vanilla js class
  const workspaceService = new WorkspaceService();

  // register
  registerProxy(workspaceService, WorkspaceServiceIPCDescriptor);
}

bindServiceAndProxy();

3. bridge proxy in preload script

/** preload/services.ts */

/**
 * Provide API from main services to GUI (for example, preference window), and tiddlywiki
 * This file should be required by BrowserView's preload script to work
 */

import { createProxy } from 'electron-ipc-cat/client';
import { AsyncifyProxy } from 'electron-ipc-cat/common';

import { IWorkspaceService, WorkspaceServiceIPCDescriptor } from '@services/workspaces/interface';

export const workspace = createProxy<AsyncifyProxy<IWorkspaceService>>(WorkspaceServiceIPCDescriptor);

export const descriptors = {
  workspace: WorkspaceServiceIPCDescriptor,
};

/** preload/index.ts */
import { contextBridge } from 'electron';
import * as service from './services';

contextBridge.exposeInMainWorld('service', service);

declare global {
  interface Window {
    meta: IPossibleWindowMeta;
    observables: IServicesWithOnlyObservables<typeof service>;
    service: IServicesWithoutObservables<typeof service>;
  }
}

4. receive in Renderer

/** renderer.tsx */
import 'electron-ipc-cat/fixContextIsolation';

/** react hooks */
import { map } from 'rxjs/operators';
import { useObservable } from 'beautiful-react-hooks';

import { IWorkspace } from '@services/workspaces';

export function useWorkspacesListObservable(): IWorkspace[] | undefined {
  const [workspaces, workspacesSetter] = useState<IWorkspace[] | undefined>();
  // beware not pipe directly in the react hock, as it will re-pipe every time React reRenders, and every time regarded as new Observable, so it will re-subscribe
  // useMemo will solve this
  const workspacesList$ = useMemo(
    () => window.observables.workspace.workspaces$.pipe(map<Record<string, IWorkspace>, IWorkspace[]>((workspaces) => Object.values(workspaces))),
    [],
  );
  useObservable<IWorkspace[] | undefined>(workspacesList$, workspacesSetter);
  return workspaces;
}

export function useWorkspaceObservable(id: string): IWorkspace | undefined {
  const [workspace, workspaceSetter] = useState<IWorkspace | undefined>();
  const workspace$ = useMemo(() => window.observables.workspace.get$(id), [id]);
  useObservable<IWorkspace | undefined>(workspace$, workspaceSetter);
  return workspace;
}

Notes

All Values and Functions will return promises on the renderer side, no matter how they have been defined on the source object. This is because communication happens asynchronously. For this reason it is recommended that you make them promises on the source object as well, so the interface is the same on both sides.

Use Value$ and Function$ when you want to expose or return an Observable stream across IPC. Due to contextIsolation's limit we can't directly proxy observables, so we have to place observables into window.observables.xxx.

Only plain objects can be passed between the 2 sides of the proxy, as the data is serialized to JSON, so no functions or prototypes will make it across to the other side.

Notice the second parameter of createProxy - Observable this is done so that the library itself does not need to take on a dependency to rxjs. You need to pass in the Observable constructor yourself if you want to consume Observable streams.

The channel specified must be unique and match on both sides of the proxy.

The packages exposes 2 entry points in the "main" and "browser" fields of package.json. "main" is for the main thread and "browser" is for the renderer thread.

Worker Thread Usage

You can also use electron-ipc-cat to communicate between the main process and Node.js worker threads.

Worker Thread Example

// In worker thread (worker.js)
import { createWorkerProxy, type WorkerProxy } from 'electron-ipc-cat/worker';
import { Observable } from 'rxjs';
import { WorkspaceServiceIPCDescriptor, type IWorkspaceService } from './services';

// Create proxy - uses the same descriptor as IPC
const workspace = createWorkerProxy<WorkerProxy<IWorkspaceService>>(
  WorkspaceServiceIPCDescriptor,
  Observable
);

// Use it like local service
const workspaces = await workspace.getWorkspacesAsList();
workspace.get$(id).subscribe(ws => console.log(ws));

Main Process - Register Worker Service

// Main process
import { Worker } from 'worker_threads';
import { registerProxy, attachWorker } from 'electron-ipc-cat/server';
import { Workspace } from './services/workspace';
import { WorkspaceServiceIPCDescriptor } from './services';

const workspaceService = new Workspace();

// Register service (automatically available for both IPC and future workers)
registerProxy(workspaceService, WorkspaceServiceIPCDescriptor);
registerProxy(authService, AuthServiceIPCDescriptor);

// Later, when you create workers (can be created anytime)
const worker = new Worker('./worker.js');
attachWorker(worker); // This worker can now call all registered services

// Create more workers dynamically as needed
const anotherWorker = new Worker('./another-worker.js');
attachWorker(anotherWorker);

That's it! The library handles all the message routing, Observable streaming, and error handling automatically.

Custom Transport

If you need custom communication logic, you can provide your own transport:

import { createWorkerProxy, type WorkerTransport } from 'electron-ipc-cat/worker';

const customTransport: WorkerTransport = {
  postMessage: (message) => {
    // Your custom message sending logic
  },
  on: (event, handler) => {
    // Your custom message receiving logic
  }
};

const workspace = createWorkerProxy<WorkerProxy<IWorkspaceService>>(
  WorkspaceServiceIPCDescriptor,
  Observable,
  customTransport
);

See it working

Example in TiddlyGit

FAQ

reject string

You should reject an Error, other wise serialize-error can't handle it well.

- reject(errorMessage);
+ reject(new Error(errorMessage));

Change Log

V2.0.1

Use ESM to enable tree shaking.

V1.3.6

Fix observable's complete not triggered.