mcpField
E
electrobun

electrobun

github.com/gyorkluu开发54 次安装
代码仓库

关于 electrobun

electrobun 是基于 TypeScript、Bun 和系统原生 Webview 的桌面应用框架，适用于构建桌面应用。它提供主进程与 Webview 间的双向类型安全 RPC，以及窗口、菜单和更新等功能。

主要功能

  1. 01基于 Bun 的 TypeScript 开发与打包
  2. 02使用系统原生 Webview
  3. 03主进程与 Webview 双向类型安全 RPC
  4. 04窗口、菜单、系统托盘和文件对话框
  5. 05应用更新器与生命周期事件

适用场景

  1. 01使用 React、Svelte 或其他模板启动桌面应用
  2. 02构建多个窗口的桌面应用
  3. 03在界面与主进程间传递调用
  4. 04实现菜单、托盘或文件选择功能

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/gyorkluu/electrobun-skills --skill electrobun

安装后在 Claude Code 中输入/electrobun确认已加载。

详细介绍

Electrobun

Electrobun 是一个以 TypeScript 为先的桌面应用框架，使用 Bun（运行时 + 打包器）和系统原生 WebView。构建约 14MB 的应用，更新包约 14KB，启动时间 <50ms。

快速开始

初始化新项目
bunx electrobun init          # Interactive scaffold
bun run dev                   # Development mode
bun run build                 # Production bundle

从模板中选择：

  • hello-world：最小化入门模板
  • react-tailwind-vite：React + Tailwind + Vite
  • svelte：Svelte 框架
  • photo-booth：摄像头访问示例
  • multitab-browser：基于标签页的浏览器示例
项目结构
my-app/
├── electrobun.config.ts      # Build configuration
├── src/
│   ├── bun/
│   │   └── main.ts           # Main process (Bun)
│   └── views/
│       └── mainview/
│           ├── index.html
│           └── index.ts      # Webview frontend
└── package.json

核心概念

主进程与 WebView
  • 主进程（src/bun/main.ts）：在 Bun 中运行，具有完整的系统访问权限，管理窗口并处理 RPC
  • WebView 进程（src/views/*/index.ts）：在操作系统 WebView 中运行，处于沙盒环境中，处理 UI 并调用 RPC
BrowserWindow

创建和管理应用窗口。

import { BrowserWindow } from "electrobun/bun";

const win = new BrowserWindow({
  title: "My App",
  url: "views://mainview/index.html",
  width: 1200,
  height: 800,
  frame: true,  // Standard window frame
  styleMask: ["titled", "closable", "miniaturizable", "resizable"],
});

主要选项：

  • title：窗口标题
  • url：加载 URL（使用 views:// 协议加载打包的视图）
  • width、height：窗口尺寸
  • x、y：窗口位置（可选）
  • frame：显示标准窗口边框（true/false）
  • styleMask：窗口控件数组（macOS）
  • titleBarStyle："default" | "hidden" | "hiddenInset"
  • trafficLightPosition：自定义 macOS 红绿灯按钮位置

方法：

win.loadURL("views://otherview/index.html")
win.setTitle("New Title")
win.resize({ width: 1024, height: 768 })
win.move({ x: 100, y: 100 })
win.show() / win.hide()
win.close()
win.focus()
win.minimize() / win.maximize() / win.fullscreen()
RPC：主进程 ↔ WebView 通信

Electrobun 的杀手级功能——类型化、快速、双向 RPC。

主进程（bun/main.ts）：

import { BrowserWindow } from "electrobun/bun";

const win = new BrowserWindow({ /* ... */ });

// Define what main exposes TO the webview
win.defineRpc({
  handlers: {
    async getUser(id: string) {
      // Full system access here
      const user = await db.getUser(id);
      return { name: user.name, id: user.id };
    },
    async saveFile(path: string, content: string) {
      await Bun.write(path, content);
      return { success: true };
    }
  }
});

// Call webview methods FROM main
const result = await win.rpc.updateUI({ data: "new data" });

WebView（views/mainview/index.ts）：

import { Electroview } from "electrobun/browser";

const electroview = new Electroview();

// Call main process functions
const user = await electroview.rpc.getUser("123");
const result = await electroview.rpc.saveFile("/path/to/file.txt", "content");

// Define handlers main can call
electroview.defineRpc({
  handlers: {
    async updateUI(data: any) {
      // Update DOM here
      document.getElementById("content").textContent = data.data;
      return { updated: true };
    }
  }
});

要点：

  • 完全类型安全（使用 TypeScript）
  • 双向通信（主进程可以调用 WebView，WebView 也可以调用主进程）
  • 默认异步
  • 自动序列化数据（JSON）
应用菜单
import { ApplicationMenu } from "electrobun/bun";

ApplicationMenu.setMenu([
  {
    label: "File",
    submenu: [
      { 
        label: "New Window", 
        accelerator: "CmdOrCtrl+N",
        action: () => createWindow()
      },
      { type: "separator" },
      { 
        label: "Quit", 
        accelerator: "CmdOrCtrl+Q",
        action: () => process.exit(0)
      },
    ]
  },
  {
    label: "Edit",
    submenu: [
      { role: "undo" },
      { role: "redo" },
      { type: "separator" },
      { role: "cut" },
      { role: "copy" },
      { role: "paste" },
    ]
  }
]);

内置角色： undo、redo、cut、copy、paste、selectAll、minimize、close、quit

上下文菜单
import { ContextMenu } from "electrobun/bun";

win.on("context-menu", (event) => {
  ContextMenu.show([
    { label: "Copy", action: () => { /* copy logic */ } },
    { type: "separator" },
    { label: "Paste", action: () => { /* paste logic */ } },
  ]);
});
系统托盘
import { Tray } from "electrobun/bun";

const tray = new Tray({
  icon: "assets://tray-icon.png",
  tooltip: "My App",
  menu: [
    { label: "Show", action: () => win.show() },
    { label: "Hide", action: () => win.hide() },
    { type: "separator" },
    { label: "Quit", action: () => process.exit(0) },
  ]
});

// Update icon dynamically
tray.setIcon("assets://tray-icon-active.png");
自动更新器
import { Updater } from "electrobun/bun";

const updater = new Updater({
  url: "https://updates.myapp.com/latest.json",
  autoCheck: true,
  interval: 60 * 60 * 1000, // Check every hour
});

updater.on("update-available", async (info) => {
  console.log("Update available:", info.version);
  // Show dialog, then:
  updater.downloadAndInstall();
});

updater.on("update-downloaded", () => {
  console.log("Update ready, restart to apply");
});

updater.on("error", (err) => {
  console.error("Updater error:", err);
});
路径与资源
import { paths } from "electrobun/bun";

// OS directories
paths.appData      // App data directory
paths.userData     // User-specific data
paths.resources    // Bundled resources
paths.home         // User home directory
paths.temp         // Temporary directory

// Reference bundled assets:
// views://viewname/file.html  → views folder
// assets://file.png           → assets folder

示例：持久化状态

import { join } from "path";

const stateFile = join(paths.userData, "state.json");

// Read
const state = JSON.parse(await Bun.file(stateFile).text() || "{}");

// Write
await Bun.write(stateFile, JSON.stringify(state));
窗口事件
win.on("close", () => {
  console.log("Window closing");
});

win.on("resize", ({ width, height }) => {
  console.log("Window resized:", width, height);
});

win.on("move", ({ x, y }) => {
  console.log("Window moved:", x, y);
});

win.on("focus", () => console.log("Window focused"));
win.on("blur", () => console.log("Window blurred"));
应用生命周期事件
import { app } from "electrobun/bun";

app.on("ready", () => {
  console.log("App ready, create windows");
});

app.on("before-quit", () => {
  console.log("App about to quit, cleanup");
});

app.on("window-all-closed", () => {
  if (process.platform !== "darwin") {
    app.quit();
  }
});

构建配置

electrobun.config.ts：

import { defineConfig } from "electrobun";

export default defineConfig({
  app: {
    name: "My App",
    version: "1.0.0",
    identifier: "com.example.myapp",
  },
  build: {
    main: "src/bun/main.ts",
    views: {
      mainview: "src/views/mainview/index.ts",
      settings: "src/views/settings/index.ts",
    },
  },
  icons: {
    mac: "assets/icon.icns",
    win: "assets/icon.ico",
    linux: "assets/icon.png",
  },
  updates: {
    provider: "generic",
    url: "https://updates.myapp.com",
  },
});

常见模式

多个窗口
const windows = new Map<string, BrowserWindow>();

function createWindow(id: string, url: string) {
  const win = new BrowserWindow({
    url,
    width: 800,
    height: 600,
  });
  
  windows.set(id, win);
  
  win.on("close", () => {
    windows.delete(id);
  });
  
  return win;
}
打开外部链接
import { shell } from "electrobun/bun";

// In main process
shell.openExternal("https://example.com");

// In webview, intercept link clicks
document.addEventListener("click", (e) => {
  const link = (e.target as HTMLElement).closest("a");
  if (link && link.href.startsWith("http")) {
    e.preventDefault();
    electroview.rpc.openExternal(link.href);
  }
});
可拖动标题栏

<div style="-webkit-app-region: drag; height: 40px; background: #333;">
  <h1 style="-webkit-app-region: no-drag;">My App</h1>
  <button style="-webkit-app-region: no-drag;">Click Me</button>
</div>
文件对话框
import { dialog } from "electrobun/bun";

// Open file
const result = await dialog.showOpenDialog({
  title: "Select File",
  filters: [
    { name: "Images", extensions: ["png", "jpg", "jpeg"] },
    { name: "All Files", extensions: ["*"] }
  ],
  properties: ["openFile", "multiSelections"]
});

if (!result.canceled) {
  console.log("Selected files:", result.filePaths);
}

// Save file
const saveResult = await dialog.showSaveDialog({
  title: "Save File",
  defaultPath: "untitled.txt",
  filters: [
    { name: "Text Files", extensions: ["txt"] },
  ]
});

平台说明

macOS
  • 使用 WKWebView
  • 分发时需要代码签名
  • Gatekeeper 要求进行公证
  • 开发时请安装 Xcode Command Line Tools
Windows
  • 使用 WebView2（Edge）
  • 开发时需要 Visual Studio Build Tools
  • 建议进行代码签名，以便通过 SmartScreen 检查
Linux
  • 使用 WebKit2GTK
  • 安装开发包： 
    sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev

后续步骤

  • 高级窗口管理：查看 electrobun-window-management 技能，了解多窗口应用和 BrowserView
  • RPC 模式：查看 electrobun-rpc-patterns 技能，了解类型安全和性能
  • 原生 UI：查看 electrobun-native-ui 技能，了解菜单、托盘和对话框
  • 分发：查看 electrobun-distribution 技能，了解打包和更新
  • 调试：查看 electrobun-debugging 技能，了解故障排查

资源

评论

支持 Markdown