forked from imbytecat/fullstack-starter
imbytecat
e8e473b357
Electrobun 太不稳定，改用 webui-dev/webui（轻量 C 库，~300KB）通过 系统浏览器或 WebView 提供桌面窗口。已验证 bun:ffi 加载和 bun build --compile 均正常工作。 - 移除 electrobun 依赖和配置 - 添加 @webui-dev/bun-webui 依赖 - 重写桌面入口为 WebUI 窗口方案 - 移除 Conveyor 打包工具（mise.toml）
58 lines
2.2 KiB
Markdown
58 lines
2.2 KiB
Markdown
# AGENTS.md - Desktop App Guidelines
|
|
|
|
Thin WebUI shell hosting the fullstack server app.
|
|
|
|
## Tech Stack
|
|
|
|
> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**
|
|
|
|
- **Type**: WebUI desktop shell
|
|
- **Design**: Server-driven desktop (thin native window hosting web app)
|
|
- **Runtime**: Bun (Main process) + System browser / WebView (via WebUI)
|
|
- **Window Library**: [webui-dev/webui](https://github.com/webui-dev/webui) — opens installed browser or native WebView as GUI
|
|
- **Build**: Turborepo
|
|
|
|
## Architecture
|
|
|
|
- **Server-driven design**: The desktop app is a "thin" native shell. It does not contain UI or business logic; it opens a browser window pointing to the `apps/server` TanStack Start application.
|
|
- **Dev mode**: Waits for the Vite dev server at `localhost:3000`, then opens a WebUI window. Requires `apps/server` to be running separately.
|
|
- **WebUI**: Uses `@webui-dev/bun-webui` (FFI-based C library binding). Auto-detects and opens the best available browser in a private profile, or uses the system WebView.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
bun dev # Open WebUI window (requires server dev running)
|
|
bun fix # Biome auto-fix
|
|
bun typecheck # TypeScript check
|
|
```
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
.
|
|
├── src/
|
|
│ └── bun/
|
|
│ └── index.ts # Main process entry (server readiness check + WebUI window)
|
|
├── package.json # Scripts and dependencies
|
|
├── turbo.json # Dev pipeline (depends on server dev)
|
|
└── AGENTS.md # Desktop guidelines (this file)
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
1. **Start server**: In `apps/server`, run `bun dev`.
|
|
2. **Start desktop**: In `apps/desktop`, run `bun dev`.
|
|
3. **Connection**: The desktop app polls `localhost:3000` until responsive, then opens the browser window.
|
|
|
|
## Critical Rules
|
|
|
|
**DO:**
|
|
- Use arrow functions for all utility functions.
|
|
- Ensure `apps/server` dev server is running before starting desktop.
|
|
- Use `catalog:` for all dependency versions in `package.json`.
|
|
|
|
**DON'T:**
|
|
- Use `npm`, `npx`, `node`, `yarn`, or `pnpm`. Always use `bun`.
|
|
- Include UI components or business logic in the desktop app (keep it thin).
|
|
- Use `as any` or `@ts-ignore`.
|