forked from imbytecat/fullstack-starter
imbytecat
dac6bb1643
- build:linux/mac/win → dist/dist:linux/dist:mac/dist:win - Turbo 任务依赖：desktop#dist:* → server#compile → server#build - 根目录 bun dist 一条命令完成完整打包流水线 - 更新 AGENTS.md 文档同步命令变更
82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
bun dist:mac # Build + package for macOS
|
|
bun dist:win # Build + package for Windows
|
|
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
|
|
|
|
From monorepo root, run `bun 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` → `out/server-{platform}`
|
|
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 dist:linux` / `bun dist:mac` / `bun dist: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`.
|