fullstack-starter/AGENTS.md

AGENTS.md

Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know.

Stack & runtime

• Bun-only (mise.toml pins bun = 1.3.13). Never invoke npm/npx/node/yarn/pnpm. Use bun run <script> (bare bun <script> can collide with Bun built-in subcommands).
• TanStack Start (React 19 SSR, file-routed) + Vite 8 + Nitro (nightly, preset bun). Vite dev port is strict 3000.
• PostgreSQL + Drizzle ORM 0.45.2 (0.x, NOT 1.0 beta) — see "Drizzle" section, this matters a lot.
• ORPC (contract-first), TanStack Query v5, Tailwind v4.

Scripts

bun run dev          # bunx --bun vite dev  (localhost:3000)
bun run build        # bunx --bun vite build → .output/
bun run compile      # bun compile.ts → out/server-<target> (standalone CLI binary)
bun run cli <cmd>    # bun bin.ts <cmd>  — run a CLI subcommand in source (dev)
bun run typecheck    # tsc --noEmit
bun run fix          # biome check --write  (lint + format + organize imports)
bun run db:push      # dev only — push schema to DB, no migration file
bun run db:generate  # produce SQL migration files in ./drizzle
bun run db:migrate   # apply migrations via drizzle-kit (local convenience)
bun run db:studio    # Drizzle Studio

Cross-compile targets live under compile:{linux,darwin,windows}[:arch]. compile.ts accepts --target bun-<os>-<arch>; default derives from host.

Before committing: bun run fix && bun run typecheck. No CI, no pre-commit hooks, no lint-staged — so these are on you.

Drizzle (v0.x — critical)

Why it matters: the project was on 1.0 beta and was rolled back. Online docs default to 1.0 beta APIs that do NOT exist here. If typecheck complains, you are probably importing a 1.0 beta API.

• Driver: drizzle-orm/postgres-js. Do NOT use drizzle-orm/bun-sql.
• drizzle() is called with { connection, schema } where schema = import * as schema from '@/server/db/schema'. There is no relations.ts and no defineRelations in 0.x.
• Zod generators live in the separate drizzle-zod package (^0.8.3). Import from drizzle-zod, not drizzle-orm/zod (that subpath only exists in 1.0 beta).
• Relational queries use RQB v1 callback syntax:

  db.query.todoTable.findMany({
    orderBy: (t, { desc }) => desc(t.createdAt),
  })
  

  Do NOT use the v2 object form (orderBy: { createdAt: 'desc' }, where: { id }) — it won't type-check.
• To add relations later: declare per-table with relations() from drizzle-orm and export them from the same file as the table; they get picked up automatically because index.ts does drizzle({ schema }) via import *.
• Every table must spread ...generatedFields from src/server/db/fields.ts (gives id UUIDv7 with $defaultFn fallback, createdAt, updatedAt with $onUpdateFn). There's also a generatedFieldKeys helper to feed createInsertSchema(...).omit(...).
• drizzle.config.ts runs outside Vite — @/* path aliases do NOT resolve there. It currently does import { env } from './src/env' (relative). Preserve that.
• The ./drizzle/ migrations directory is gitignored-by-absence right now (no migrations yet). Migrations are applied via the CLI (./server migrate, see "CLI & single-binary deploy" below), NOT at server startup. Dev uses db:push. Don't mix push and migrate on the same DB.

CLI & single-binary deploy

bun run compile produces a single executable that dispatches subcommands via citty. Entry is bin.ts at repo root, subcommands live in src/cli/.

./server [serve]   # default — start the HTTP server
./server migrate   # apply migrations from ./drizzle
./server --help

Nitro side-effect pitfall (important). Under the bun preset, .output/server/index.mjs has a top-level serve(...) call — merely importing it starts the HTTP server. bin.ts therefore must not eager-import any subcommand module, and src/cli/serve.ts reaches .output/server/index.mjs through the src/cli/_serve-nitro.mjs bridge (with _serve-nitro.d.mts for types, since .output/ doesn't exist at typecheck time). Citty's subCommands: { x: () => import('...') } lazy-loader is what keeps --help and migrate from booting the server.

Citty eager-loads subcommand modules for --help to read each subcommand's meta. So every src/cli/*.ts module body must be side-effect-free: do NOT static-import @/env, @/server/db/*, or anything that reads env at module-load time. Use await import('@/env') inside run(). Otherwise ./server --help (or any subcommand's help) will fail with env validation errors before printing.

Add a subcommand: drop a file in src/cli/ that default-exports defineCommand({...}), then register it in bin.ts's subCommands with a () => import(...) thunk. Keep top-level imports limited to citty + Node built-ins; pull env / db / etc. via await import(...) inside run().

Deploy flow is always migrate-then-serve. The compiled binary bundles neither the ./drizzle/ SQL files nor the app schema migrations at runtime — they're read from disk next to the binary. Dockerfile copies drizzle/ alongside ./server, and compose.yaml models this with a one-shot migrate service that app depends_on: service_completed_successfully. On k8s, run ./server migrate as an initContainer or a Helm pre-upgrade Job; run ./server (= ./server serve) as the main container.

ORPC

Contract → Router → Handler → Client, all type-safe from a single contract.

• os is built in src/server/api/server.ts via implement(contract).$context<BaseContext>(). Always import os from @/server/api/server, never from @orpc/server directly. ORPCError, onError, ValidationError come from @orpc/server.
• Contracts (src/server/api/contracts/*.contract.ts) generate Zod from Drizzle tables via drizzle-zod:

  const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
  

  Barrel-aggregated in contracts/index.ts as export const contract = { todo }.
• Routers chain the db middleware (src/server/api/middlewares/db.middleware.ts, injects the getDB() singleton into context). Barrel in routers/index.ts builds os.router({ todo }).
• Interceptors are attached at the handler level, not in server.ts and not on os. Both src/routes/api/rpc.$.ts (RPCHandler) and src/routes/api/$.ts (OpenAPIHandler) register [onError(logError)] (server) and [onError(handleValidationError)] (client). The validation interceptor rewrites BAD_REQUEST + ValidationError into INPUT_VALIDATION_FAILED (422) and output validation errors into OUTPUT_VALIDATION_FAILED.
• OpenAPI/Scalar: docs at /api/docs, spec at /api/spec.json (handler prefix /api, plugin paths /docs and /spec.json).
• SSR isomorphism (src/client/orpc.ts): createIsomorphicFn().server(createRouterClient(...)).client(new RPCLink(...)). Server branch reads getRequestHeaders() for context; client branch POSTs to ${origin}/api/rpc.
• Global mutation invalidation uses experimental_defaults in createTanstackQueryUtils(...) — currently invalidates orpc.todo.list.key() on every todo.{create,update,remove} success. Add new features here rather than in each mutation site.
• SSR prefetch in route loaders: await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions()). Components use useSuspenseQuery(orpc.feature.list.queryOptions()).

Code style (Biome)

• 2-space, LF, single quotes, semicolons as-needed (omitted unless required), 120-col, arrow parens always, useArrowFunction: "error" — so React components must be const Foo = () => {...} not function Foo() {}. Also noReactPropAssignments: "error".
• Imports are auto-organized into two groups (external, then @/*), each alphabetical, with import type interleaved (NOT a separate group). bun run fix handles this; don't hand-sort.
• Files: utils kebab-case.ts, components PascalCase.tsx.
• routeTree.gen.ts is generated — ignored by Biome, never edit.

TypeScript

Strict mode, plus noUncheckedIndexedAccess, verbatimModuleSyntax, erasableSyntaxOnly, noImplicitOverride. No as any / @ts-ignore / @ts-expect-error.

Path alias: @/* → src/*. For files outside src/ use @/../<file> (example in the codebase: src/routes/api/$.ts imports name, version from @/../package.json).

Env

src/env.ts via @t3-oss/env-core. Server: DATABASE_URL (required, z.url()). Client needs VITE_ prefix (VITE_APP_TITLE optional). Never commit .env.

Docker / deploy

• Multi-stage: oven/bun:1.3.13 builds and runs bun compile.ts, then gcr.io/distroless/cc-debian13:nonroot runs the single ./server binary. The cc (glibc) distroless variant is required because Bun's compiled binary links glibc.
• drizzle/ folder is copied into the runtime image so ./server migrate can find migrations at runtime.
• compose.yaml: one-shot migrate service runs ./server migrate with restart: "no", then app starts (depends_on: migrate: service_completed_successfully). DATABASE_URL=postgres://postgres:postgres@db:5432/postgres for both.
• Distroless has no shell, so any init-then-serve pattern must use exec-form command: [...], not sh -c.

Layout (non-obvious parts only)

src/
├── client/orpc.ts              # isomorphic ORPC client + experimental_defaults invalidation
├── cli/                        # CLI subcommands (loaded lazily by bin.ts via citty)
│   ├── serve.ts                # `./server serve` — imports the Nitro bridge on demand
│   ├── migrate.ts              # `./server migrate` — drizzle migrate against ./drizzle
│   ├── _serve-nitro.mjs        # bridge: `import('../../.output/server/index.mjs')`
│   └── _serve-nitro.d.mts      # types for the bridge (build output has no .d.ts)
├── routes/api/
│   ├── $.ts                    # OpenAPI + Scalar; interceptors registered here
│   └── rpc.$.ts                # RPC; interceptors registered here
├── server/
│   ├── api/
│   │   ├── server.ts           # the ONLY place to build `os`
│   │   ├── context.ts          # BaseContext / DBContext types
│   │   ├── interceptors.ts     # logError, handleValidationError
│   │   ├── contracts/          # Zod schemas from Drizzle tables (barrel: contract)
│   │   ├── routers/            # os.* handlers (barrel: router)
│   │   └── middlewares/        # db middleware injects getDB() singleton
│   ├── db/
│   │   ├── index.ts            # createDB({ connection, schema }) + getDB()/closeDB() singleton
│   │   ├── fields.ts           # pk (UUIDv7), createdAt, updatedAt, generatedFields(Keys)
│   │   └── schema/             # pgTable definitions; also put `relations()` here when adding
│   └── plugins/
│       └── shutdown.ts         # SIGINT/SIGTERM → closeDB() with 500ms delay
├── env.ts                      # t3-oss env validation
├── router.tsx                  # QueryClient + setupRouterSsrQueryIntegration
└── routeTree.gen.ts            # auto-generated, do not edit
bin.ts                          # citty entry (root) — keep imports minimal (see "CLI" section)

Nitro plugins are wired in vite.config.ts (nitro({ plugins: [...] })), not via a Nitro config file.

Don'ts (specific, non-obvious)

• Don't edit routeTree.gen.ts.
• Don't eager-import anything from .output/ in bin.ts or any module it statically imports — it starts the HTTP server as a side effect. Subcommands must be lazy via citty's () => import(...) thunks.
• Don't re-add an auto-migrate Nitro plugin. Migrations are an explicit deploy step via ./server migrate.
• Don't import os from @orpc/server in middleware/routers — always @/server/api/server.
• Don't import from drizzle-orm/zod (1.0 beta only). Use drizzle-zod.
• Don't use RQB v2 object syntax, defineRelations, or pass relations to drizzle(). All are 1.0 beta.
• Don't use drizzle-orm/bun-sql.
• Don't use @/* aliases in drizzle.config.ts.
• Don't commit .env.