fullstack-starter/apps/desktop/AGENTS.md

AGENTS.md - Desktop App Guidelines

Electrobun desktop shell - loads the server app in a native window.

⚠️ This project uses Bun — NOT Node.js / npm. All commands use bun. Never use npm, npx, or node.

Architecture

• Type: Electrobun desktop application
• Design: Bun main process + system webview (or CEF)
• Dev mode: Connects to localhost:3000 (requires server dev running)
• Prod mode: Embeds server bundle and starts local HTTP server

Commands

# Development (from apps/desktop/)
bun dev                    # Start Electrobun dev mode

# Build
bun build                  # Build canary release
bun build:stable           # Build stable release

Directory Structure

apps/desktop/
├── src/
│   └── bun/
│       └── index.ts       # Electrobun main process entry
├── electrobun.config.ts   # Electrobun configuration
├── package.json
└── tsconfig.json

Development Workflow

1. Start server dev first: cd ../server && bun dev
2. Start Electrobun: bun dev (from apps/desktop/)
3. Electrobun connects to localhost:3000

Electrobun Patterns

BrowserWindow

import { BrowserWindow } from 'electrobun/bun'

new BrowserWindow({
  title: 'My App',
  url: 'http://localhost:3000',
  frame: {
    x: 100,
    y: 100,
    width: 1200,
    height: 800,
  },
})

Events

import Electrobun from 'electrobun/bun'

Electrobun.events.on('will-quit', () => {
  console.log('App quitting...')
})

Critical Rules

DO:

• Run server dev before desktop dev
• Use catalog: for dependencies
• Handle server startup gracefully

DON'T:

• Use npm, npx, node, yarn, pnpm — always use bun / bunx
• Hardcode dependency versions (use catalog)
• Block main thread during server wait