forked from imbytecat/fullstack-starter
imbytecat
fd9478d64e
- 所有 AGENTS.md 新增「开发原则」：不向后兼容、改代码必须同步文档、前向迁移 - 根 AGENTS.md: 更新 Database 段落为 Drizzle v1 beta + postgres-js + RQBv2 - server AGENTS.md: 更新 tech stack、目录结构、ORPC 示例、数据库段落 - drizzle-zod → drizzle-orm/zod - bun-sql → postgres-js - RQBv1 回调 → RQBv2 对象语法 - 新增 relations.ts 和 DB instance 示例 - desktop AGENTS.md: 添加开发原则和文档同步规则
96 lines
4.4 KiB
Markdown
96 lines
4.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 (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
|
|
|
|
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 --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 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`.
|
|
|
|
## 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.
|