imbytecat/fullstack-starter
1
1
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 统一使用 bun run <script> 避免与 Bun 内置子命令冲突

Browse Source 
bun build 会调用 Bun 内置 bundler 而非 package.json script，
将所有文档中的 bun <script> 改为 bun run <script> 以避免歧义。
bun test 保留不变（直接使用 Bun 内置 test runner）。
This commit is contained in:
imbytecat
2026-03-05 12:57:26 +08:00
parent 58d7a453b6
commit cd7448c3b3
4 changed files with 86 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
AGENTS.md
View File

@@ -4,7 +4,7 @@ Guidelines for AI agents working in this Bun monorepo.
## Project Overview ## 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 - **Monorepo**: Bun workspaces + Turborepo orchestration
- **Runtime**: Bun (see `mise.toml` for version) — **NOT Node.js** - **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) ### Root Commands (via Turbo)
```bash ```bash
bun dev # Start all apps in dev mode bun run dev # Start all apps in dev mode
bun build # Build all apps bun run build # Build all apps
bun compile # Compile server to standalone binary (current platform) bun run compile # Compile server to standalone binary (current platform)
bun compile:darwin # Compile server for macOS (arm64 + x64) bun run compile:darwin # Compile server for macOS (arm64 + x64)
bun compile:linux # Compile server for Linux (x64 + arm64) bun run compile:linux # Compile server for Linux (x64 + arm64)
bun compile:windows # Compile server for Windows x64 bun run compile:windows # Compile server for Windows x64
bun dist # Package desktop distributable (current platform) bun run dist # Package desktop distributable (current platform)
bun dist:linux # Package desktop for Linux (x64 + arm64) bun run dist:linux # Package desktop for Linux (x64 + arm64)
bun dist:mac # Package desktop for macOS (arm64 + x64) bun run dist:mac # Package desktop for macOS (arm64 + x64)
bun dist:win # Package desktop for Windows x64 bun run dist:win # Package desktop for Windows x64
bun fix # Lint + format (Biome auto-fix) bun run fix # Lint + format (Biome auto-fix)
bun typecheck # TypeScript check across monorepo bun run typecheck # TypeScript check across monorepo
``` ```
### Server App (`apps/server`) ### Server App (`apps/server`)
```bash ```bash
bun dev # Vite dev server (localhost:3000) bun run dev # Vite dev server (localhost:3000)
bun build # Production build -> .output/ bun run build # Production build -> .output/
bun compile # Compile to standalone binary (current platform) bun run compile # Compile to standalone binary (current platform)
bun compile:darwin # Compile for macOS (arm64 + x64) bun run compile:darwin # Compile for macOS (arm64 + x64)
bun compile:darwin:arm64 # Compile for macOS arm64 bun run compile:darwin:arm64 # Compile for macOS arm64
bun compile:darwin:x64 # Compile for macOS x64 bun run compile:darwin:x64 # Compile for macOS x64
bun compile:linux # Compile for Linux (x64 + arm64) bun run compile:linux # Compile for Linux (x64 + arm64)
bun compile:linux:arm64 # Compile for Linux arm64 bun run compile:linux:arm64 # Compile for Linux arm64
bun compile:linux:x64 # Compile for Linux x64 bun run compile:linux:x64 # Compile for Linux x64
bun compile:windows # Compile for Windows (default: x64) bun run compile:windows # Compile for Windows (default: x64)
bun compile:windows:x64 # Compile for Windows x64 bun run compile:windows:x64 # Compile for Windows x64
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
# Database (Drizzle) # Database (Drizzle)
bun db:generate # Generate migrations from schema bun run db:generate # Generate migrations from schema
bun db:migrate # Run migrations bun run db:migrate # Run migrations
bun db:push # Push schema (dev only) bun run db:push # Push schema (dev only)
bun db:studio # Open Drizzle Studio bun run db:studio # Open Drizzle Studio
``` ```
### Desktop App (`apps/desktop`) ### Desktop App (`apps/desktop`)
```bash ```bash
bun dev # electron-vite dev mode (requires server dev running) bun run dev # electron-vite dev mode (requires server dev running)
bun build # electron-vite build (main + preload) bun run build # electron-vite build (main + preload)
bun dist # Build + package for current platform bun run dist # Build + package for current platform
bun dist:linux # Build + package for Linux (x64 + arm64) bun run dist:linux # Build + package for Linux (x64 + arm64)
bun dist:linux:x64 # Build + package for Linux x64 bun run dist:linux:x64 # Build + package for Linux x64
bun dist:linux:arm64 # Build + package for Linux arm64 bun run dist:linux:arm64 # Build + package for Linux arm64
bun dist:mac # Build + package for macOS (arm64 + x64) bun run dist:mac # Build + package for macOS (arm64 + x64)
bun dist:mac:arm64 # Build + package for macOS arm64 bun run dist:mac:arm64 # Build + package for macOS arm64
bun dist:mac:x64 # Build + package for macOS x64 bun run dist:mac:x64 # Build + package for macOS x64
bun dist:win # Build + package for Windows x64 bun run dist:win # Build + package for Windows x64
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
``` ```
### Testing ### Testing
@@ -160,7 +160,7 @@ export const myTable = pgTable('my_table', {
## Critical Rules ## Critical Rules
**DO:** **DO:**
- Run `bun fix` before committing - Run `bun run fix` before committing
- Use `@/*` path aliases (not relative imports) - Use `@/*` path aliases (not relative imports)
- Include `createdAt`/`updatedAt` on all tables - Include `createdAt`/`updatedAt` on all tables
- Use `catalog:` for dependency versions - Use `catalog:` for dependency versions
@@ -178,9 +178,9 @@ export const myTable = pgTable('my_table', {
## Git Workflow ## Git Workflow
1. Make changes following style guide 1. Make changes following style guide
2. `bun fix` - auto-format and lint 2. `bun run fix` - auto-format and lint
3. `bun typecheck` - verify types 3. `bun run typecheck` - verify types
4. `bun dev` - test locally 4. `bun run dev` - test locally
5. Commit with descriptive message 5. Commit with descriptive message
## Directory Structure ## Directory Structure

36
apps/desktop/AGENTS.md
View File

@@ -4,7 +4,7 @@ Thin Electron shell hosting the fullstack server app.
## Tech Stack ## 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 - **Type**: Electron desktop shell
- **Design**: Server-driven desktop (thin native window hosting web app) - **Design**: Server-driven desktop (thin native window hosting web app)
@@ -22,18 +22,18 @@ Thin Electron shell hosting the fullstack server app.
## Commands ## Commands
```bash ```bash
bun dev # electron-vite dev (requires server dev running) bun run dev # electron-vite dev (requires server dev running)
bun build # electron-vite build (main + preload) bun run build # electron-vite build (main + preload)
bun dist # Build + package for current platform bun run dist # Build + package for current platform
bun dist:linux # Build + package for Linux (x64 + arm64) bun run dist:linux # Build + package for Linux (x64 + arm64)
bun dist:linux:x64 # Build + package for Linux x64 bun run dist:linux:x64 # Build + package for Linux x64
bun dist:linux:arm64 # Build + package for Linux arm64 bun run dist:linux:arm64 # Build + package for Linux arm64
bun dist:mac # Build + package for macOS (arm64 + x64) bun run dist:mac # Build + package for macOS (arm64 + x64)
bun dist:mac:arm64 # Build + package for macOS arm64 bun run dist:mac:arm64 # Build + package for macOS arm64
bun dist:mac:x64 # Build + package for macOS x64 bun run dist:mac:x64 # Build + package for macOS x64
bun dist:win # Build + package for Windows x64 bun run dist:win # Build + package for Windows x64
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
``` ```
## Directory Structure ## Directory Structure
@@ -56,13 +56,13 @@ bun typecheck # TypeScript check
## Development Workflow ## Development Workflow
1. **Start server**: `bun dev` in `apps/server` (or use root `bun dev` via Turbo). 1. **Start server**: `bun run dev` in `apps/server` (or use root `bun run dev` via Turbo).
2. **Start desktop**: `bun dev` in `apps/desktop`. 2. **Start desktop**: `bun run dev` in `apps/desktop`.
3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow. 3. **Connection**: Main process polls `localhost:3000` until responsive, then opens BrowserWindow.
## Production Build Workflow ## 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/` 1. **Build server**: `apps/server` → `vite build` → `.output/`
2. **Compile server**: `apps/server` → `bun compile.ts --target ...` → `out/server-{os}-{arch}` 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. 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`. 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 dist:linux:x64`, `bun dist:linux:arm64`, `bun dist:mac:x64`, or `bun dist:mac:arm64`. 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 ## Development Principles

42
apps/server/AGENTS.md
View File

@@ -4,7 +4,7 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
## Tech Stack ## 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) - **Framework**: TanStack Start (React 19 SSR, file-based routing)
- **Runtime**: Bun — **NOT Node.js** - **Runtime**: Bun — **NOT Node.js**
@@ -20,33 +20,33 @@ TanStack Start fullstack web app with ORPC (contract-first RPC).
```bash ```bash
# Development # Development
bun dev # Vite dev server (localhost:3000) bun run dev # Vite dev server (localhost:3000)
bun db:studio # Drizzle Studio GUI bun run db:studio # Drizzle Studio GUI
# Build # Build
bun build # Production build → .output/ bun run build # Production build → .output/
bun compile # Compile to standalone binary (current platform, depends on build) bun run compile # Compile to standalone binary (current platform, depends on build)
bun compile:darwin # Compile for macOS (arm64 + x64) bun run compile:darwin # Compile for macOS (arm64 + x64)
bun compile:darwin:arm64 # Compile for macOS arm64 bun run compile:darwin:arm64 # Compile for macOS arm64
bun compile:darwin:x64 # Compile for macOS x64 bun run compile:darwin:x64 # Compile for macOS x64
bun compile:linux # Compile for Linux (x64 + arm64) bun run compile:linux # Compile for Linux (x64 + arm64)
bun compile:linux:arm64 # Compile for Linux arm64 bun run compile:linux:arm64 # Compile for Linux arm64
bun compile:linux:x64 # Compile for Linux x64 bun run compile:linux:x64 # Compile for Linux x64
bun compile:windows # Compile for Windows (default: x64) bun run compile:windows # Compile for Windows (default: x64)
bun compile:windows:x64 # Compile for Windows x64 bun run compile:windows:x64 # Compile for Windows x64
# Code Quality # Code Quality
bun fix # Biome auto-fix bun run fix # Biome auto-fix
bun typecheck # TypeScript check bun run typecheck # TypeScript check
# Database # Database
bun db:generate # Generate migrations from schema bun run db:generate # Generate migrations from schema
bun db:migrate # Run migrations bun run db:migrate # Run migrations
bun db:push # Push schema directly (dev only) bun run db:push # Push schema directly (dev only)
# Testing (not yet configured) # Testing (not yet configured)
bun test path/to/test.ts # Run single test bun test path/to/test.ts # Run single test
bun test -t "pattern" # Run tests matching pattern bun test -t "pattern" # Run tests matching pattern
``` ```
## Directory Structure ## Directory Structure
@@ -257,7 +257,7 @@ export const env = createEnv({
## Critical Rules ## Critical Rules
**DO:** **DO:**
- Run `bun fix` before committing - Run `bun run fix` before committing
- Use `@/*` path aliases - Use `@/*` path aliases
- Include `createdAt`/`updatedAt` on all tables - Include `createdAt`/`updatedAt` on all tables
- Use `ORPCError` with proper codes - Use `ORPCError` with proper codes

7
turbo.json
View File

@@ -14,12 +14,7 @@
"cache": false "cache": false
}, },
"typecheck": { "typecheck": {
"inputs": [ "inputs": ["package.json", "tsconfig.json", "tsconfig.*.json", "**/*.{ts,tsx,d.ts}"],
"package.json",
"tsconfig.json",
"tsconfig.*.json",
"**/*.{ts,tsx,d.ts}"
],
"outputs": [] "outputs": []
} }
}, },