fullstack-starter/README.md

fullstack-starter

强约定的单二进制全栈 starter。Bun + TanStack Start（React 19 SSR）+ ORPC（契约优先）+ Drizzle + PostgreSQL，编译为单个可执行文件部署。

Agent 笔记与非显而易见的不变量见 AGENTS.md。改结构前先读。

快速开始

cp .env.example .env
bun install
bun run db:push     # 开发期：同步 schema 不生成 migration 文件
bun run dev         # http://localhost:3000

RPC 入口：/api/rpc · OpenAPI 文档：/api/docs · Spec：/api/spec.json · 存活探针：/health。

脚本

命令	作用
bun run dev	Vite 开发服务器，3000 端口（strict）
bun run build	构建到 .output/
bun run compile	bun build --compile 生成单二进制 out/server-<target>
bun run cli <cmd>	源码态运行 CLI 子命令（serve、migrate）
bun run typecheck	tsc --noEmit
bun run test	bun test（同目录 *.test.ts）
bun run fix	Biome lint + format + 整理 imports
bun run db:push	仅开发期 schema 同步（不写 migration 文件）
bun run db:generate	把 SQL migration 写到 ./drizzle/ 并重生 migrations.gen.ts
bun run db:embed	仅从 ./drizzle/ 重生 src/server/db/migrations.gen.ts（手改 SQL 后用）
bun run db:migrate	通过 drizzle-kit 本地应用 migration（开发便利）
bun run db:studio	Drizzle Studio

跨平台编译：bun run compile:{linux,darwin,windows}[:arch]。

新增一个功能（以 post 为例）

契约优先、纯增量。按以下顺序建/改文件：

1. src/server/db/schema/post.ts — 定义 postTable，展开 ...generatedFields。
2. src/server/db/schema/index.ts — export * from './post'。
3. src/server/api/contracts/post.contract.ts — 通过 drizzle-zod 从表派生 Zod schema。
4. src/server/api/contracts/index.ts — 把 post 加进 contract 对象。
5. src/server/api/routers/post.router.ts — 实现 os.post.*.handler(...)。
6. src/server/api/routers/index.ts — 把 post 加进 router 对象。
7. src/client/queries/post.ts — 导出 useInvalidatePosts（或更细粒度 helper），用于失效受影响的 list key。
8. src/routes/<page>.tsx — 用 useSuspenseQuery + loader ensureQueryData；mutation 的 onSuccess 调用上一步的 helper。
9. bun run db:generate — 写 SQL migration 到 ./drizzle/ 并嵌入 src/server/db/migrations.gen.ts。

部署

永远 先 migrate 再 serve。Migration 已嵌入二进制，二进制是你唯一发布的产物。

./server migrate   # 用 $DATABASE_URL 应用嵌入式 migration
./server           # 启动 HTTP 服务器（默认子命令）

compose.yaml 把这个模式编排了出来：一次性 migrate 服务，app 通过 service_completed_successfully 等它完成。Kubernetes 上：把 ./server migrate 放进 initContainer 或 Helm pre-upgrade Job。

docker compose up --build