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). 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 dev                    # electron-vite dev (requires server dev running)
bun build                  # electron-vite build (main + preload)
bun dist                   # Build + package for current platform
bun dist:linux             # Build + package for Linux (x64 + arm64)
bun dist:linux:x64         # Build + package for Linux x64
bun dist:linux:arm64       # Build + package for Linux arm64
bun dist:mac               # Build + package for macOS (arm64 + x64)
bun dist:mac:arm64         # Build + package for macOS arm64
bun dist:mac:x64           # Build + package for macOS x64
bun dist:win               # Build + package for Windows x64
bun fix                    # Biome auto-fix
bun 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 dev in apps/server (or use root bun dev via Turbo).
Start desktop: bun dev in apps/desktop.
Connection: Main process polls localhost:3000 until responsive, then opens BrowserWindow.

Production Build Workflow

From monorepo root, run bun 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 dist:linux / bun dist:mac / bun dist:win in apps/desktop. For single-arch output, use bun dist:linux:x64, bun dist:linux:arm64, bun dist:mac:x64, or bun dist:mac:arm64.

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.

3.8 KiB Raw Blame History