forked from imbytecat/fullstack-starter
imbytecat
cd7448c3b3
bun build 会调用 Bun 内置 bundler 而非 package.json script， 将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。 bun test 保留不变（直接使用 Bun 内置 test runner）。
96 lines
4.6 KiB
Markdown
96 lines
4.6 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). 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
|
|
|
|
```bash
|
|
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.
|