forked from imbytecat/fullstack-starter
docs: 统一使用 bun run <script> 避免与 Bun 内置子命令冲突
bun build 会调用 Bun 内置 bundler 而非 package.json script， 将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。 bun test 保留不变（直接使用 Bun 内置 test runner）。
This commit is contained in:
92
AGENTS.md
92
AGENTS.md
@@ -4,7 +4,7 @@ Guidelines for AI agents working in this Bun monorepo.
|
||||
|
||||
## Project Overview
|
||||
|
||||
> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run` / `bun <script>` for scripts. Never use `npm`, `npx`, or `node`.**
|
||||
> **This project uses [Bun](https://bun.sh) exclusively as both the JavaScript runtime and package manager. Do NOT use Node.js / npm / yarn / pnpm. All commands start with `bun` — use `bun install` for dependencies and `bun run <script>` for scripts. Always prefer `bun run <script>` over `bun <script>` to avoid conflicts with Bun built-in subcommands (e.g. `bun build` invokes Bun's bundler, NOT your package.json script). Never use `npm`, `npx`, or `node`.**
|
||||
|
||||
- **Monorepo**: Bun workspaces + Turborepo orchestration
|
||||
- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js**
|
||||
@@ -18,57 +18,57 @@ Guidelines for AI agents working in this Bun monorepo.
|
||||
|
||||
### Root Commands (via Turbo)
|
||||
```bash
|
||||
bun dev # Start all apps in dev mode
|
||||
bun build # Build all apps
|
||||
bun compile # Compile server to standalone binary (current platform)
|
||||
bun compile:darwin # Compile server for macOS (arm64 + x64)
|
||||
bun compile:linux # Compile server for Linux (x64 + arm64)
|
||||
bun compile:windows # Compile server for Windows x64
|
||||
bun dist # Package desktop distributable (current platform)
|
||||
bun dist:linux # Package desktop for Linux (x64 + arm64)
|
||||
bun dist:mac # Package desktop for macOS (arm64 + x64)
|
||||
bun dist:win # Package desktop for Windows x64
|
||||
bun fix # Lint + format (Biome auto-fix)
|
||||
bun typecheck # TypeScript check across monorepo
|
||||
bun run dev # Start all apps in dev mode
|
||||
bun run build # Build all apps
|
||||
bun run compile # Compile server to standalone binary (current platform)
|
||||
bun run compile:darwin # Compile server for macOS (arm64 + x64)
|
||||
bun run compile:linux # Compile server for Linux (x64 + arm64)
|
||||
bun run compile:windows # Compile server for Windows x64
|
||||
bun run dist # Package desktop distributable (current platform)
|
||||
bun run dist:linux # Package desktop for Linux (x64 + arm64)
|
||||
bun run dist:mac # Package desktop for macOS (arm64 + x64)
|
||||
bun run dist:win # Package desktop for Windows x64
|
||||
bun run fix # Lint + format (Biome auto-fix)
|
||||
bun run typecheck # TypeScript check across monorepo
|
||||
```
|
||||
|
||||
### Server App (`apps/server`)
|
||||
```bash
|
||||
bun dev # Vite dev server (localhost:3000)
|
||||
bun build # Production build -> .output/
|
||||
bun compile # Compile to standalone binary (current platform)
|
||||
bun compile:darwin # Compile for macOS (arm64 + x64)
|
||||
bun compile:darwin:arm64 # Compile for macOS arm64
|
||||
bun compile:darwin:x64 # Compile for macOS x64
|
||||
bun compile:linux # Compile for Linux (x64 + arm64)
|
||||
bun compile:linux:arm64 # Compile for Linux arm64
|
||||
bun compile:linux:x64 # Compile for Linux x64
|
||||
bun compile:windows # Compile for Windows (default: x64)
|
||||
bun compile:windows:x64 # Compile for Windows x64
|
||||
bun fix # Biome auto-fix
|
||||
bun typecheck # TypeScript check
|
||||
bun run dev # Vite dev server (localhost:3000)
|
||||
bun run build # Production build -> .output/
|
||||
bun run compile # Compile to standalone binary (current platform)
|
||||
bun run compile:darwin # Compile for macOS (arm64 + x64)
|
||||
bun run compile:darwin:arm64 # Compile for macOS arm64
|
||||
bun run compile:darwin:x64 # Compile for macOS x64
|
||||
bun run compile:linux # Compile for Linux (x64 + arm64)
|
||||
bun run compile:linux:arm64 # Compile for Linux arm64
|
||||
bun run compile:linux:x64 # Compile for Linux x64
|
||||
bun run compile:windows # Compile for Windows (default: x64)
|
||||
bun run compile:windows:x64 # Compile for Windows x64
|
||||
bun run fix # Biome auto-fix
|
||||
bun run typecheck # TypeScript check
|
||||
|
||||
# Database (Drizzle)
|
||||
bun db:generate # Generate migrations from schema
|
||||
bun db:migrate # Run migrations
|
||||
bun db:push # Push schema (dev only)
|
||||
bun db:studio # Open Drizzle Studio
|
||||
bun run db:generate # Generate migrations from schema
|
||||
bun run db:migrate # Run migrations
|
||||
bun run db:push # Push schema (dev only)
|
||||
bun run db:studio # Open Drizzle Studio
|
||||
```
|
||||
|
||||
### Desktop App (`apps/desktop`)
|
||||
```bash
|
||||
bun dev # electron-vite dev mode (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
|
||||
bun run dev # electron-vite dev mode (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
|
||||
```
|
||||
|
||||
### Testing
|
||||
@@ -160,7 +160,7 @@ export const myTable = pgTable('my_table', {
|
||||
## Critical Rules
|
||||
|
||||
**DO:**
|
||||
- Run `bun fix` before committing
|
||||
- Run `bun run fix` before committing
|
||||
- Use `@/*` path aliases (not relative imports)
|
||||
- Include `createdAt`/`updatedAt` on all tables
|
||||
- Use `catalog:` for dependency versions
|
||||
@@ -178,9 +178,9 @@ export const myTable = pgTable('my_table', {
|
||||
## Git Workflow
|
||||
|
||||
1. Make changes following style guide
|
||||
2. `bun fix` - auto-format and lint
|
||||
3. `bun typecheck` - verify types
|
||||
4. `bun dev` - test locally
|
||||
2. `bun run fix` - auto-format and lint
|
||||
3. `bun run typecheck` - verify types
|
||||
4. `bun run dev` - test locally
|
||||
5. Commit with descriptive message
|
||||
|
||||
## Directory Structure
|
||||
|
||||
@@ -4,7 +4,7 @@ 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`.**
|
||||
> **⚠️ 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)
|
||||
@@ -22,18 +22,18 @@ Thin Electron shell hosting the fullstack server app.
|
||||
## 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
|
||||
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
|
||||
@@ -56,13 +56,13 @@ bun typecheck # TypeScript check
|
||||
|
||||
## 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`.
|
||||
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 dist` to execute the full pipeline automatically (via Turbo task dependencies):
|
||||
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}`
|
||||
@@ -70,8 +70,8 @@ From monorepo root, run `bun dist` to execute the full pipeline automatically (v
|
||||
|
||||
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`.
|
||||
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
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
|
||||
|
||||
## Tech Stack
|
||||
|
||||
> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Never use `npm`, `npx`, or `node`.**
|
||||
> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
|
||||
|
||||
- **Framework**: TanStack Start (React 19 SSR, file-based routing)
|
||||
- **Runtime**: Bun — **NOT Node.js**
|
||||
@@ -20,33 +20,33 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
|
||||
|
||||
```bash
|
||||
# Development
|
||||
bun dev # Vite dev server (localhost:3000)
|
||||
bun db:studio # Drizzle Studio GUI
|
||||
bun run dev # Vite dev server (localhost:3000)
|
||||
bun run db:studio # Drizzle Studio GUI
|
||||
|
||||
# Build
|
||||
bun build # Production build → .output/
|
||||
bun compile # Compile to standalone binary (current platform, depends on build)
|
||||
bun compile:darwin # Compile for macOS (arm64 + x64)
|
||||
bun compile:darwin:arm64 # Compile for macOS arm64
|
||||
bun compile:darwin:x64 # Compile for macOS x64
|
||||
bun compile:linux # Compile for Linux (x64 + arm64)
|
||||
bun compile:linux:arm64 # Compile for Linux arm64
|
||||
bun compile:linux:x64 # Compile for Linux x64
|
||||
bun compile:windows # Compile for Windows (default: x64)
|
||||
bun compile:windows:x64 # Compile for Windows x64
|
||||
bun run build # Production build → .output/
|
||||
bun run compile # Compile to standalone binary (current platform, depends on build)
|
||||
bun run compile:darwin # Compile for macOS (arm64 + x64)
|
||||
bun run compile:darwin:arm64 # Compile for macOS arm64
|
||||
bun run compile:darwin:x64 # Compile for macOS x64
|
||||
bun run compile:linux # Compile for Linux (x64 + arm64)
|
||||
bun run compile:linux:arm64 # Compile for Linux arm64
|
||||
bun run compile:linux:x64 # Compile for Linux x64
|
||||
bun run compile:windows # Compile for Windows (default: x64)
|
||||
bun run compile:windows:x64 # Compile for Windows x64
|
||||
|
||||
# Code Quality
|
||||
bun fix # Biome auto-fix
|
||||
bun typecheck # TypeScript check
|
||||
bun run fix # Biome auto-fix
|
||||
bun run typecheck # TypeScript check
|
||||
|
||||
# Database
|
||||
bun db:generate # Generate migrations from schema
|
||||
bun db:migrate # Run migrations
|
||||
bun db:push # Push schema directly (dev only)
|
||||
bun run db:generate # Generate migrations from schema
|
||||
bun run db:migrate # Run migrations
|
||||
bun run db:push # Push schema directly (dev only)
|
||||
|
||||
# Testing (not yet configured)
|
||||
bun test path/to/test.ts # Run single test
|
||||
bun test -t "pattern" # Run tests matching pattern
|
||||
bun test path/to/test.ts # Run single test
|
||||
bun test -t "pattern" # Run tests matching pattern
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
@@ -257,7 +257,7 @@ export const env = createEnv({
|
||||
## Critical Rules
|
||||
|
||||
**DO:**
|
||||
- Run `bun fix` before committing
|
||||
- Run `bun run fix` before committing
|
||||
- Use `@/*` path aliases
|
||||
- Include `createdAt`/`updatedAt` on all tables
|
||||
- Use `ORPCError` with proper codes
|
||||
|
||||
@@ -14,12 +14,7 @@
|
||||
"cache": false
|
||||
},
|
||||
"typecheck": {
|
||||
"inputs": [
|
||||
"package.json",
|
||||
"tsconfig.json",
|
||||
"tsconfig.*.json",
|
||||
"**/*.{ts,tsx,d.ts}"
|
||||
],
|
||||
"inputs": ["package.json", "tsconfig.json", "tsconfig.*.json", "**/*.{ts,tsx,d.ts}"],
|
||||
"outputs": []
|
||||
}
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user