Files

T

imbytecat a3a62c24b9 docs: 新增 README，AGENTS 同步至当前架构

- 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 / 测试等扩展边界）

2026-04-25 13:31:45 +08:00

2.6 KiB

Raw Blame History

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 — define postTable, spread ...generatedFields.
src/server/db/schema/index.ts — export * from './post'.
src/server/api/contracts/post.contract.ts — derive Zod from the table via drizzle-zod.
src/server/api/contracts/index.ts — add post to the contract object.
src/server/api/routers/post.router.ts — implement os.post.*.handler(...).
src/server/api/routers/index.ts — add post to the router object.
src/routes/<page>.tsx — UI with useSuspenseQuery + loader ensureQueryData; invalidate affected list queries in mutation onSuccess handlers.
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

2.6 KiB Raw Blame History