Files

imbytecat cd7448c3b3 docs: 统一使用 bun run <script> 避免与 Bun 内置子命令冲突

bun build 会调用 Bun 内置 bundler 而非 package.json script，
将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。
bun test 保留不变（直接使用 Bun 内置 test runner）。

2026-03-05 12:57:26 +08:00

4.6 KiB

Raw Blame History

AGENTS.md - Desktop App Guidelines

Thin Electron shell hosting the fullstack server app.

Tech Stack

⚠️ This project uses Bun as the package manager. Runtime is Electron (Node.js). Always use bun run <script> (not bun <script>) to avoid conflicts with Bun built-in subcommands. Never use npm, npx, yarn, or pnpm.

Type: Electron desktop shell
Design: Server-driven desktop (thin native window hosting web app)
Runtime: Electron (Main/Renderer) + Sidecar server binary (Bun-compiled)
Build Tool: electron-vite (Vite-based, handles main + preload builds)
Packager: electron-builder (installers, signing, auto-update)
Orchestration: Turborepo

Architecture

Server-driven design: The desktop app is a "thin" native shell. It does not contain UI or business logic; it opens a BrowserWindow pointing to the apps/server TanStack Start application.
Dev mode: Opens a BrowserWindow pointing to localhost:3000. Requires apps/server to be running separately (Turbo handles this).
Production mode: Spawns a compiled server binary (from resources/) as a sidecar process, waits for readiness, then loads its URL.

Commands

bun run dev                    # electron-vite dev (requires server dev running)
bun run build                  # electron-vite build (main + preload)
bun run dist                   # Build + package for current platform
bun run dist:linux             # Build + package for Linux (x64 + arm64)
bun run dist:linux:x64         # Build + package for Linux x64
bun run dist:linux:arm64       # Build + package for Linux arm64
bun run dist:mac               # Build + package for macOS (arm64 + x64)
bun run dist:mac:arm64         # Build + package for macOS arm64
bun run dist:mac:x64           # Build + package for macOS x64
bun run dist:win               # Build + package for Windows x64
bun run fix                    # Biome auto-fix
bun run typecheck              # TypeScript check

Directory Structure

.
├── src/
│   ├── main/
│   │   └── index.ts       # Main process (server lifecycle + BrowserWindow)
│   └── preload/
│       └── index.ts       # Preload script (security isolation)
├── resources/             # Sidecar binaries (gitignored, copied from server build)
├── out/                   # electron-vite build output (gitignored)
├── electron.vite.config.ts
├── electron-builder.yml   # Packaging configuration
├── package.json
├── turbo.json
└── AGENTS.md

Development Workflow

Start server: bun run dev in apps/server (or use root bun run dev via Turbo).
Start desktop: bun run dev in apps/desktop.
Connection: Main process polls localhost:3000 until responsive, then opens BrowserWindow.

Production Build Workflow

From monorepo root, run bun run dist to execute the full pipeline automatically (via Turbo task dependencies):

Build server: apps/server → vite build → .output/
Compile server: apps/server → bun compile.ts --target ... → out/server-{os}-{arch}
Package desktop: apps/desktop → electron-vite build + electron-builder → distributable

The electron-builder.yml extraResources config reads binaries directly from ../server/out/, no manual copy needed.

To build for a specific platform explicitly, use bun run dist:linux / bun run dist:mac / bun run dist:win in apps/desktop. For single-arch output, use bun run dist:linux:x64, bun run dist:linux:arm64, bun run dist:mac:x64, or bun run dist:mac:arm64.

Development Principles

These principles apply to ALL code changes. Agents MUST follow them on every task.

No backward compatibility — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
Always sync documentation — When code changes, immediately update all related documentation (AGENTS.md, README.md, inline code examples). Code and docs must never drift apart.
Forward-only migration — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.

Critical Rules

DO:

Use arrow functions for all utility functions.
Keep the desktop app as a thin shell — no UI or business logic.
Use catalog: for all dependency versions in package.json.

DON'T:

Use npm, npx, yarn, or pnpm. Use bun for package management.
Include UI components or business logic in the desktop app.
Use as any or @ts-ignore.
Leave docs out of sync with code changes.

4.6 KiB Raw Blame History