{"id":23422722,"url":"https://github.com/linonetwo/electron-ipc-cat","last_synced_at":"2025-09-03T02:08:10.407Z","repository":{"id":46673935,"uuid":"406622604","full_name":"linonetwo/electron-ipc-cat","owner":"linonetwo","description":"Passing object and type between Electron main process and renderer process simply via preload script.","archived":false,"fork":false,"pushed_at":"2023-07-05T07:45:42.000Z","size":627,"stargazers_count":20,"open_issues_count":8,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-08-23T18:09:02.420Z","etag":null,"topics":["electron","ipc","main","preload","proxy","remote","renderer"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/electron-ipc-cat","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linonetwo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-15T05:15:09.000Z","updated_at":"2025-03-30T00:48:28.000Z","dependencies_parsed_at":"2024-06-21T12:51:54.989Z","dependency_job_id":"7ccef921-c79d-40af-b837-93e26c833c19","html_url":"https://github.com/linonetwo/electron-ipc-cat","commit_stats":{"total_commits":56,"total_committers":4,"mean_commits":14.0,"dds":0.5714285714285714,"last_synced_commit":"cf30f3a19cdcfa0c7f220872483532d2608a76b5"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/linonetwo/electron-ipc-cat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linonetwo%2Felectron-ipc-cat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linonetwo%2Felectron-ipc-cat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linonetwo%2Felectron-ipc-cat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linonetwo%2Felectron-ipc-cat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linonetwo","download_url":"https://codeload.github.com/linonetwo/electron-ipc-cat/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linonetwo%2Felectron-ipc-cat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273377153,"owners_count":25094528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","ipc","main","preload","proxy","remote","renderer"],"created_at":"2024-12-23T03:09:45.022Z","updated_at":"2025-09-03T02:08:10.381Z","avatar_url":"https://github.com/linonetwo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# electron-ipc-cat\n\n\u003e Based on [frankwallis/electron-ipc-proxy](https://github.com/frankwallis/electron-ipc-proxy/pull/2), and used in [TiddlyGit-Desktop](https://github.com/tiddly-gittly/TiddlyGit-Desktop).\n\n\u003cp align=\"center\" style=\"color: #343a40\"\u003e\n  \u003cimg src=\"docs/image/title-image.png\" alt=\"electron-ipc-cat logo\"\u003e\n  \u003ch1 align=\"center\"\u003eelectron-ipc-cat\u003c/h1\u003e\n\u003c/p\u003e\n\u003cp align=\"center\" style=\"font-size: 1.2rem;\"\u003ePassing object and type between Electron main process and renderer process simply via preload script.\u003c/p\u003e\n\n## Overview\n\nIn 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.\n\nLuckily 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`!\n\nWe 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.\n\n## Install\n\n```sh\npnpm i electron-ipc-cat\n```\n\n## Example\n\nReal use case in [TiddlyGit-Desktop's workspace feature](https://github.com/tiddly-gittly/TiddlyGit-Desktop/blob/master/src/services/workspaces/index.ts)\n\n### 1. The class\n\n```ts\n/** workspaces.ts */\nexport class Workspace implements IWorkspaceService {\n  /**\n   * Record from workspace id to workspace settings\n   */\n  private workspaces: Record\u003cstring, IWorkspace\u003e = {};\n  public workspaces$: BehaviorSubject\u003cRecord\u003cstring, IWorkspace\u003e\u003e;\n\n  public async getWorkspacesAsList(): Promise\u003cIWorkspace[]\u003e {\n    return Object.values(this.workspaces).sort((a, b) =\u003e a.order - b.order);\n  }\n\n  public async get(id: string): Promise\u003cIWorkspace | undefined\u003e {\n    return this.workspaces[id];\n  }\n\n  public get$(id: string): Observable\u003cIWorkspace | undefined\u003e {\n    return this.workspaces$.pipe(map((workspaces) =\u003e workspaces[id]));\n  }\n}\n\nexport interface IWorkspaceService {\n  workspaces$: BehaviorSubject\u003cRecord\u003cstring, IWorkspace\u003e\u003e;\n  getWorkspacesAsList(): Promise\u003cIWorkspace[]\u003e;\n  get(id: string): Promise\u003cIWorkspace | undefined\u003e;\n  get$(id: string): Observable\u003cIWorkspace | undefined\u003e;\n}\n\nexport const WorkspaceServiceIPCDescriptor = {\n  channel: WorkspaceChannel.name,\n  properties: {\n    workspaces$: ProxyPropertyType.Value$,\n    getWorkspacesAsList: ProxyPropertyType.Function,\n    get: ProxyPropertyType.Function,\n    get$: ProxyPropertyType.Function$,\n  },\n};\n```\n\n### 2. bindServiceAndProxy in Main\n\n```ts\n/** bindServiceAndProxy.ts */\n\n/**\n * Don't forget to edit src/preload/services.ts to export service to renderer process\n */\nimport { registerProxy } from 'electron-ipc-cat/server';\n\nimport serviceIdentifier from '@services/serviceIdentifier';\nimport { container } from '@services/container';\n\nimport { Workspace } from '@services/workspaces';\nimport { IWorkspaceService, WorkspaceServiceIPCDescriptor } from '@services/workspaces/interface';\n\nfunction bindServiceAndProxy(): void {\n  // if using inversifyjs\n  container.bind\u003cIWorkspaceService\u003e(serviceIdentifier.Workspace).to(Workspace).inSingletonScope();\n  const workspaceService = container.get\u003cIWorkspaceService\u003e(serviceIdentifier.Workspace);\n  // if using vanilla js class\n  const workspaceService = new WorkspaceService();\n\n  // register\n  registerProxy(workspaceService, WorkspaceServiceIPCDescriptor);\n}\n\nbindServiceAndProxy();\n```\n\n### 3. bridge proxy in preload script\n\n```ts\n/** preload/services.ts */\n\n/**\n * Provide API from main services to GUI (for example, preference window), and tiddlywiki\n * This file should be required by BrowserView's preload script to work\n */\n\nimport { createProxy } from 'electron-ipc-cat/client';\nimport { AsyncifyProxy } from 'electron-ipc-cat/common';\n\nimport { IWorkspaceService, WorkspaceServiceIPCDescriptor } from '@services/workspaces/interface';\n\nexport const workspace = createProxy\u003cAsyncifyProxy\u003cIWorkspaceService\u003e\u003e(WorkspaceServiceIPCDescriptor);\n\nexport const descriptors = {\n  workspace: WorkspaceServiceIPCDescriptor,\n};\n```\n\n```ts\n/** preload/index.ts */\nimport { contextBridge } from 'electron';\nimport * as service from './services';\n\ncontextBridge.exposeInMainWorld('service', service);\n\ndeclare global {\n  interface Window {\n    meta: IPossibleWindowMeta;\n    observables: IServicesWithOnlyObservables\u003ctypeof service\u003e;\n    service: IServicesWithoutObservables\u003ctypeof service\u003e;\n  }\n}\n```\n\n### 4. receive in Renderer\n\n```ts\n/** renderer.tsx */\nimport 'electron-ipc-cat/fixContextIsolation';\n\n/** react hooks */\nimport { map } from 'rxjs/operators';\nimport { useObservable } from 'beautiful-react-hooks';\n\nimport { IWorkspace } from '@services/workspaces';\n\nexport function useWorkspacesListObservable(): IWorkspace[] | undefined {\n  const [workspaces, workspacesSetter] = useState\u003cIWorkspace[] | undefined\u003e();\n  // 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\n  // useMemo will solve this\n  const workspacesList$ = useMemo(\n    () =\u003e window.observables.workspace.workspaces$.pipe(map\u003cRecord\u003cstring, IWorkspace\u003e, IWorkspace[]\u003e((workspaces) =\u003e Object.values(workspaces))),\n    [],\n  );\n  useObservable\u003cIWorkspace[] | undefined\u003e(workspacesList$, workspacesSetter);\n  return workspaces;\n}\n\nexport function useWorkspaceObservable(id: string): IWorkspace | undefined {\n  const [workspace, workspaceSetter] = useState\u003cIWorkspace | undefined\u003e();\n  const workspace$ = useMemo(() =\u003e window.observables.workspace.get$(id), [id]);\n  useObservable\u003cIWorkspace | undefined\u003e(workspace$, workspaceSetter);\n  return workspace;\n}\n```\n\n## Notes\n\nAll `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.\n\nUse `Value$` and `Function$` when you want to expose or return an Observable stream across IPC. Due to [contextIsolation's limit](https://github.com/electron/electron/issues/28176) we can't directly proxy observables, so we have to place observables into `window.observables.xxx`.\n\nOnly 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.\n\nNotice 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.\n\nThe channel specified must be unique and match on both sides of the proxy.\n\nThe 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.\n\n## See it working\n\n[Example in TiddlyGit](https://github.com/tiddly-gittly/TiddlyGit-Desktop/blob/0c6b26c0c1113e0c66d6f49f022c5733d4fa85e8/src/preload/common/services.ts#L27-L42)\n\n## FAQ\n\n### reject string\n\nYou should reject an Error, other wise `serialize-error` can't handle it well.\n\n```diff\n- reject(errorMessage);\n+ reject(new Error(errorMessage));\n```\n\n## Change Log\n\n### V2.0.1\n\nUse ESM to enable tree shaking.\n\n### V1.3.6\n\nFix observable's complete not triggered.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinonetwo%2Felectron-ipc-cat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinonetwo%2Felectron-ipc-cat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinonetwo%2Felectron-ipc-cat/lists"}