Back to Details

buntralino

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Buntralino Integration Guide

Buntralino集成指南

Buntralino uses a Bun main process with Neutralino windows for UI, connected through WebSockets. Use this skill when building or diagnosing Buntralino apps that combine Bun backend logic with Neutralino frontend code.
Buntralino采用Bun主进程搭配Neutralino窗口实现UI，通过WebSockets进行连接。当你构建或排查结合Bun后端逻辑与Neutralino前端代码的Buntralino应用时，可参考本指南。

When to Use

适用场景

  • Building Buntralino apps that bridge Bun backend logic with Neutralino windows
  • Wiring client-to-server method calls, events, and multi-window routing
  • Troubleshooting connection, runtime, or platform-specific issues
  • 构建连接Bun后端逻辑与Neutralino窗口的Buntralino应用
  • 配置客户端到服务端的方法调用、事件及多窗口路由
  • 排查连接、运行时或平台特定问题

What This Skill Covers

指南涵盖内容

  • Buntralino architecture, CLI usage, and build/run workflows
  • Bun API window management and server-side method registration
  • Client API usage for method calls, events, and window lifecycle
  • Buntralino架构、CLI使用及构建/运行工作流
  • Bun API窗口管理与服务端方法注册
  • 客户端API的方法调用、事件及窗口生命周期管理

Quick Start

快速开始

Bun Side

Bun端

js
import * as buntralino from 'buntralino';

buntralino.registerMethod('sayHello', async (payload) => {
  const name = payload?.name ?? 'world';
  return { message: `Hello, ${name}!` };
});

await buntralino.create('/', {
  name: 'main',
  title: 'My App',
  width: 800,
  height: 600,
  center: true
});
js
import * as buntralino from 'buntralino';

buntralino.registerMethod('sayHello', async (payload) => {
  const name = payload?.name ?? 'world';
  return { message: `Hello, ${name}!` };
});

await buntralino.create('/', {
  name: 'main',
  title: 'My App',
  width: 800,
  height: 600,
  center: true
});

Neutralino Window

Neutralino窗口端

js
import * as buntralino from 'buntralino-client';

await buntralino.ready;
const response = await buntralino.run('sayHello', { name: 'Ada' });
displayMessage(response.message);
js
import * as buntralino from 'buntralino-client';

await buntralino.ready;
const response = await buntralino.run('sayHello', { name: 'Ada' });
displayMessage(response.message);

Communication Patterns

通信模式

Method Calls With Result Contracts

带结果约定的方法调用

js
import * as buntralino from 'buntralino';

buntralino.registerMethod('processData', async (payload) => {
  try {
    const result = await heavyProcessing(payload.input);
    return { ok: true, result };
  } catch (error) {
    return { ok: false, error: String(error) };
  }
});
js
import * as buntralino from 'buntralino-client';

await buntralino.ready;
const response = await buntralino.run('processData', { input: 'data' });
if (response.ok) {
  updateUI(response.result);
} else {
  showError(response.error);
}
js
import * as buntralino from 'buntralino';

buntralino.registerMethod('processData', async (payload) => {
  try {
    const result = await heavyProcessing(payload.input);
    return { ok: true, result };
  } catch (error) {
    return { ok: false, error: String(error) };
  }
});
js
import * as buntralino from 'buntralino-client';

await buntralino.ready;
const response = await buntralino.run('processData', { input: 'data' });
if (response.ok) {
  updateUI(response.result);
} else {
  showError(response.error);
}

Event Broadcasting

事件广播

js
import * as buntralino from 'buntralino';

buntralino.broadcast('dataUpdated', { timestamp: Date.now() });
js
Neutralino.events.on('dataUpdated', (event) => {
  updateUI(event.detail);
});
js
import * as buntralino from 'buntralino';

buntralino.broadcast('dataUpdated', { timestamp: Date.now() });
js
Neutralino.events.on('dataUpdated', (event) => {
  updateUI(event.detail);
});

Multi-Window Routing

多窗口路由

js
import * as buntralino from 'buntralino';

await buntralino.create('/settings', { name: 'settings', width: 640, height: 480 });
await buntralino.sendEvent('settings', 'settingsLoaded', { ready: true });
js
import * as buntralino from 'buntralino';

await buntralino.create('/settings', { name: 'settings', width: 640, height: 480 });
await buntralino.sendEvent('settings', 'settingsLoaded', { ready: true });

Neutralino Integration Notes

Neutralino集成注意事项

  • Ensure required Neutralino namespaces and methods are allowlisted in neutralino.config.json for your app.
  • If you intentionally create windows with Neutralino.window.create, call buntralino.disableBunCheck in the window after importing buntralino-client.
  • 请确保你的应用在neutralino.config.json中允许所需的Neutralino命名空间和方法。
  • 如果你通过Neutralino.window.create手动创建窗口，在导入buntralino-client后，需在窗口中调用buntralino.disableBunCheck。

Example Scripts

示例脚本

  • Basic Integration
  • File Processing
  • Real-time Dashboard
  • Authentication
  • 基础集成
  • 文件处理
  • 实时仪表盘
  • 身份验证

References

参考资料

JavaScript references use the default filenames. TypeScript references use the same names with a -types suffix.
  • Architecture
  • CLI Usage
  • Programmatic CLI
  • Programmatic CLI (TypeScript)
  • Bun API
  • Bun API (TypeScript)
  • Server API
  • Client API
  • Client API (TypeScript)
  • Troubleshooting Linux
  • Examples
  • Error Handling
  • Examples (TypeScript)
  • Error Handling (TypeScript)
JavaScript参考使用默认文件名，TypeScript参考使用带-types后缀的同名文件。
  • 架构说明
  • CLI使用指南
  • 可编程CLI
  • 可编程CLI（TypeScript版）
  • Bun API文档
  • Bun API文档（TypeScript版）
  • 服务端API文档
  • 客户端API文档
  • 客户端API文档（TypeScript版）
  • Linux平台问题排查
  • 示例集合
  • 错误处理指南
  • TypeScript示例集合
  • TypeScript错误处理指南