imbytecat
a3a62c24b9
- README: 用户向 quick-start、scripts 表、add-a-feature checklist、deploy 流程 - AGENTS: - 修订 stale 文案（VITE_APP_TITLE/experimental_defaults/.gitkeep/route 组件风格） - 新增 Testing 段（bun test 约定）和 Endpoints 段（/, /health, /api/*） - Layout 补 logger.ts、health.ts、components/、styles.css、根 drizzle/ - 追加 10 条 room-to-grow 纪律（client query / middleware / interceptor / 测试等扩展边界）
fullstack-starter
Opinionated single-binary fullstack starter. Bun + TanStack Start (React 19 SSR) + ORPC (contract-first) + Drizzle + PostgreSQL, deployed as one compiled executable.
Agent notes and non-obvious invariants live in AGENTS.md. Read it before making structural changes.
Quick start
cp .env.example .env
bun install
bun run db:push # dev: sync schema without migration files
bun run dev # http://localhost:3000
RPC endpoint: /api/rpc · OpenAPI docs: /api/docs · Spec: /api/spec.json · Liveness: /health.
Scripts
| Command | What it does |
|---|---|
bun run dev |
Vite dev server on port 3000 (strict) |
bun run build |
Build to .output/ |
bun run compile |
Single-binary out/server-<target> via bun build --compile |
bun run cli <cmd> |
Run a CLI subcommand in source (serve, migrate) |
bun run typecheck |
tsc --noEmit |
bun run fix |
Biome lint + format + organize imports |
bun run db:push |
Dev-only schema sync (no migration files) |
bun run db:generate |
Write SQL migrations to ./drizzle |
bun run db:migrate |
Apply migrations locally via drizzle-kit |
bun run db:studio |
Drizzle Studio |
Cross-compile: bun run compile:{linux,darwin,windows}[:arch].
Add a feature (e.g. post)
Contract-first, additive. Create or touch files in this order:
src/server/db/schema/post.ts— definepostTable, spread...generatedFields.src/server/db/schema/index.ts—export * from './post'.src/server/api/contracts/post.contract.ts— derive Zod from the table viadrizzle-zod.src/server/api/contracts/index.ts— addpostto thecontractobject.src/server/api/routers/post.router.ts— implementos.post.*.handler(...).src/server/api/routers/index.ts— addpostto therouterobject.src/routes/<page>.tsx— UI withuseSuspenseQuery+ loaderensureQueryData; invalidate affected list queries in mutationonSuccesshandlers.bun run db:generate— emit SQL migrations to./drizzle.
Deploy
Always migrate-then-serve. Migrations are an explicit deploy step, never a server startup hook.
./server migrate # applies ./drizzle against $DATABASE_URL
./server # starts HTTP server (default subcommand)
Dockerfile copies ./drizzle/ next to the binary. compose.yaml models the pattern with a one-shot migrate service that app depends on (service_completed_successfully). On Kubernetes: run ./server migrate as an initContainer or Helm pre-upgrade Job.
docker compose up --build