{"id":29618780,"url":"https://github.com/kekyo/sublimity-electron-bridge","last_synced_at":"2026-01-20T17:58:09.305Z","repository":{"id":303183155,"uuid":"1014628414","full_name":"kekyo/sublimity-electron-bridge","owner":"kekyo","description":"Electron IPC bridge generator for automatic IPC setup","archived":false,"fork":false,"pushed_at":"2025-07-16T07:16:09.000Z","size":298,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-16T07:19:46.058Z","etag":null,"topics":["automatic","bridge","electron","generator","ipc"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"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/kekyo.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,"zenodo":null}},"created_at":"2025-07-06T05:07:40.000Z","updated_at":"2025-07-11T07:56:43.000Z","dependencies_parsed_at":"2025-07-06T07:40:32.441Z","dependency_job_id":"db262e8f-87ae-4e42-9e06-94956e5bbd48","html_url":"https://github.com/kekyo/sublimity-electron-bridge","commit_stats":null,"previous_names":["kekyo/sublimity-electron-bridge"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kekyo/sublimity-electron-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fsublimity-electron-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fsublimity-electron-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fsublimity-electron-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fsublimity-electron-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kekyo","download_url":"https://codeload.github.com/kekyo/sublimity-electron-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fsublimity-electron-bridge/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266231761,"owners_count":23896472,"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","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":["automatic","bridge","electron","generator","ipc"],"created_at":"2025-07-21T03:00:31.579Z","updated_at":"2026-01-20T17:58:09.292Z","avatar_url":"https://github.com/kekyo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sublimity Electron IPC Bridge\n\nAn automated code generation tool for Electron applications that eliminates the need for manual IPC (Inter-Process Communication) setup between the main process and renderer process. \n\n## Status\n\n[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n|Package|Link|\n|:----|:----|\n|npm CLI|[![npm CLI](https://badge.fury.io/js/sublimity-electron-bridge-cli.svg)](https://www.npmjs.com/package/sublimity-electron-bridge-cli)|\n|npm Vite plugin|[![npm vite-plugin](https://badge.fury.io/js/sublimity-electron-bridge-vite.svg)](https://www.npmjs.com/package/sublimity-electron-bridge-vite)|\n\n-----\n\n## Overview\n\nAre you writing a lot of glue code by hand in your Electron application that calls functions implemented in the main process from the render process? Are you fed up? This tool may be useful for you.\n\nSublimity Electron IPC Bridge automates setting up IPC communication with only JSDoc annotation.\n\nThis tool analyzes TypeScript source code and automatically generates the necessary IPC handlers, preload bridge scripts, and type definitions.\n\n### Short example\n\nWe want to expose main process function to render process, add JSDoc `@decorator expose`:\n\n```typescript\n/**\n * Get system information in Electron main process.\n * \"Decorator\" makes to expose this function to render process automatically.\n * @decorator expose fileAPI\n */\nexport async function getSystemInfo(): Promise\u003cSystemInfo\u003e {\n  return {\n    platform: process.platform,\n    version: process.version,\n    arch: process.arch\n  }\n}\n```\n\nThen it is generated automatically preloader function and type-safe interface,\nand we can access it from render proces naturally:\n\n```typescript\n// Renderer process with full type safety\nconst systemInfo = await window.fileAPI.getSystemInfo();\nconsole.log(`Running on ${systemInfo.platform}`);\n```\n\nUsing this tool, the following source code will be automatically generated:\n\n```\nproject/\n├── src/main/generated/          # IPC event handlers (generated)\n│   └── seb_main.ts\n├── src/preload/generated/       # Context bridge implementation (generated)\n│   └── seb_preload.ts\n└── src/renderer/src/generated/  # IPC interface definitions (generated)\n    └── seb_types.ts\n```\n\nThese directories and files are default location.\nFor more information, see below section.\n\n-----\n\n## Installation and Usage\n\nChoose between \"CLI tool\" or \"Vite plugin\" based on your development workflow:\n\n### CLI tool\n\nInstall the CLI package globally or use it with npx:\n\n```bash\nnpm install -g sublimity-electron-bridge-cli\n```\n\n#### CLI tool basic usage\n\n```bash\n# Generate bridge code for specific TypeScript files\nseb generate src/services/FileService.ts src/utils/system.ts\n\n# Specify custom output directories\nseb generate src/services/FileService.ts \\\n  --main src/main/seb_main.ts \\\n  --preload src/preload/seb_preload.ts\n\n# Custom type definitions location\nseb generate src/services/FileService.ts \\\n  --types src/renderer/src/seb_types.d.ts\n```\n\n#### CLI tool options\n\n```bash\nseb generate \u003cfiles...\u003e\n\nOptions:\n  -b, --baseDir \u003cpath\u003e   Project base directory path (default: Current directory)\n  -m, --main \u003cfile\u003e      Main process output file (default: \"src/main/generated/seb_main.ts\")\n  -p, --preload \u003cfile\u003e   Preload script output file (default: \"src/preload/generated/seb_preload.ts\") \n  -t, --types \u003cfile\u003e     Type definitions output file (default: \"src/renderer/src/generated/seb_types.ts\")\n  -n, --namespace \u003cname\u003e Default namespace (default: \"mainProcess\")\n  -h, --help             Display help information\n```\n\n### Vite plugin\n\nInstall the Vite plugin for automatic generation during development builds:\n\n```bash\nnpm install --save-dev sublimity-electron-bridge-vite\n```\n\n#### Vite plugin configuration\n\nAdd the plugin to your `vite.config.ts`:\n\n```typescript\nimport { defineConfig } from 'vite';\nimport { sublimityElectronBridge } from 'sublimity-electron-bridge-vite';\n\n// Vite configuration\nexport default defineConfig({\n  plugins: [\n    sublimityElectronBridge()   // The plugin\n  ]\n});\n```\n\nOr you can use with \"electron-vite\" project configuration, `electron.vite.config.ts`:\n\n```typescript\nimport { defineConfig, externalizeDepsPlugin } from 'electron-vite';\nimport { sublimityElectronBridge } from 'sublimity-electron-bridge-vite';\n\n// electron-vite configuration\nexport default defineConfig({\n  main: {   // NOTE: We have to place the plugin into `main` process.\n    plugins: [\n      externalizeDepsPlugin(),\n      sublimityElectronBridge()   // The plugin\n    ]\n  }\n});\n```\n\n#### Vite plugin options\n\nThe `sourceFiles` can use the glob pattern. Only files matching this pattern will be parsed.\nThe default is `src/main/expose/**/*.ts`, which assumes that the public code is placed under this directory.\n\n```typescript\ninterface SublimityElectronBridgeOptions {\n  mainProcessHandlerFile?: string;   // Default: \"src/main/generated/seb_main.ts\"\n  preloadHandlerFile?: string;       // Default: \"src/preload/generated/seb_preload.ts\"\n  typeDefinitionsFile?: string;      // Default: \"src/renderer/src/generated/seb_types.ts\"\n  defaultNamespace?: string;         // Default: \"mainProcess\"\n  enableWorker?: boolean;            // Default: true - Enable worker thread processing\n  sourceFiles?: string[];            // Default: \"src/main/expose/**/*.ts\"\n}\n```\n\nHere's example (defaulted) directory structure in Vite plugin:\n\n```\nproject/\n├── src/main/\n│   ├── expose/                   # Your expose function source files here\n│   │   ├── fileApi.ts\n│   │   └── systemApi.ts\n│   └── generated/                # IPC event handlers (generated)\n│       └── seb_main.ts\n├── src/preload/generated/        # Context bridge implementation (generated)\n│   └── seb_preload.ts\n└── src/renderer/src/generated/   # IPC interface definitions (generated)\n    └── seb_types.ts\n```\n\nInsert optional parameters when you need:\n\n```typescript\nexport default defineConfig({\n  plugins: [\n    sublimityElectronBridge({\n      typeDefinitionsFile: \"src/renderer/src/types.d.ts\",   // Type definition in renderer\n      defaultNamespace: \"main\"                              // Place into: `window.main.foobar()`\n    });\n  ]\n});\n```\n\n-----\n\n## Code Example\n\nThe JSDoc decorator is specified by `@decorator expose`.\nYou can also specify the name of the object to be placed as an optional argument `@decorator expose \u003cnamespace\u003e`.\nDefault namespace is `mainProcess` when does not override optional parameter.\n\n### Prepare import auto-generated code\n\nIn `src/main/index.ts`:\n\n```typescript\n// Will be automatic hooking by this import:\nimport './generated/seb_main';\n\n// (Remains main process code fragemnts...)\n```\n\nIn `src/preload/index.ts`:\n\n```typescript\n// Will be automatic hooking by this import:\nimport './generated/seb_preload';\n\n// (Remains preload code fragemnts...)\n```\n\nIn `src/renderer/src/main.ts`:\n\n```typescript\n// Will be import type declarations:\nimport './generated/seb_types';\n\n// (Remains renderer code fragemnts...)\n```\n\n### The expose decorators\n\nMain process class example in: `main/services/FileService.ts`:\n\n```typescript\nexport class FileService {\n  /**\n   * \"window.fileAPI.readFile(path: string) =\u003e Promise\u003cstring\u003e\"\n   * @decorator expose fileAPI\n   */\n  async readFile(path: string): Promise\u003cstring\u003e {\n    const fs = await import('fs/promises');\n    return fs.readFile(path, 'utf-8');\n  }\n\n  /**\n   * \"window.fileAPI.writeFile(path: string, content: string): Promise\u003cvoid\u003e\"\n   * @decorator expose fileAPI\n   */\n  async writeFile(path: string, content: string): Promise\u003cvoid\u003e {\n    const fs = await import('fs/promises');\n    await fs.writeFile(path, content, 'utf-8');\n  }\n}\n```\n\nMain process function example in: `main/services/utils.ts`:\n\n```typescript\n/**\n * \"window.systemAPI.getSystemInfo(): Promise\u003cSystemInfo\u003e\"\n * @decorator expose systemAPI\n */\nexport async function getSystemInfo(): Promise\u003cSystemInfo\u003e {\n  return {\n    platform: process.platform,\n    version: process.version,\n    arch: process.arch\n  };\n}\n\n/**\n * \"window.utilsAPI.processData(data: string): Promise\u003cstring\u003e\"\n * @decorator expose utilsAPI\n */\nexport const processData = async (data: string): Promise\u003cstring\u003e =\u003e {\n  return data.toUpperCase();\n};\n```\n\n### Usage in renderer process\n\n```typescript\nimport 'generated/seb_types.d.ts';\n\n// Renderer process with full type safety\nconst content = await window.fileAPI.readFile('/path/to/file.txt');\nawait window.fileAPI.writeFile('/path/to/output.txt', content);\n\nconst systemInfo = await window.systemAPI.getSystemInfo();\nconsole.log(`Running on ${systemInfo.platform}`);\n```\n\n### Misc\n\n- **Namespace arguments** must be in camelCase format.\n- **Methods and functions** must return `Promise\u003cT\u003e` types.\n- **Invalid naming** will result in build-time errors in Vite plugin.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Repository\n\nSource code and documentation: [https://github.com/kekyo/sublimity-electron-bridge](https://github.com/kekyo/sublimity-electron-bridge)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkekyo%2Fsublimity-electron-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkekyo%2Fsublimity-electron-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkekyo%2Fsublimity-electron-bridge/lists"}