seastem-electronjs/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). 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 build:win              # Build + package for Windows
bun build:mac              # Build + package for macOS
bun build:linux            # Build + package for Linux
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

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

Production Build Workflow

1. Build server: bun build in apps/server → .output/
2. Compile server: bun compile in apps/server → out/server-{platform}
3. Copy binary: Copy the platform-appropriate binary to apps/desktop/resources/server
4. Package desktop: bun build:linux (or :mac / :win) in apps/desktop

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.