fullstack-starter/apps/desktop/AGENTS.md

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

1. Start server: bun run dev in apps/server (or use root bun run dev via Turbo).
2. Start desktop: bun run dev in apps/desktop.
3. 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):

1. Build server: apps/server → vite build → .output/
2. Compile server: apps/server → bun compile.ts --target ... → out/server-{os}-{arch}
3. 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.

1. 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.
2. 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.
3. 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.