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 test	bun test (colocated *.test.ts)
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:

1. src/server/db/schema/post.ts — define postTable, spread ...generatedFields.
2. src/server/db/schema/index.ts — export * from './post'.
3. src/server/api/contracts/post.contract.ts — derive Zod from the table via drizzle-zod.
4. src/server/api/contracts/index.ts — add post to the contract object.
5. src/server/api/routers/post.router.ts — implement os.post.*.handler(...).
6. src/server/api/routers/index.ts — add post to the router object.
7. src/client/queries/post.ts — export useInvalidatePosts (or finer-grained helpers) for affected list keys.
8. src/routes/<page>.tsx — UI with useSuspenseQuery + loader ensureQueryData; call the helper from mutation onSuccess.
9. 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