fullstack-starter/apps/desktop/AGENTS.md

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 — 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

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.