From a3a62c24b9701f6a46f710345f0cf177b36dd571 Mon Sep 17 00:00:00 2001 From: imbytecat Date: Sat, 25 Apr 2026 13:31:45 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20README=EF=BC=8CAGE?= =?UTF-8?q?NTS=20=E5=90=8C=E6=AD=A5=E8=87=B3=E5=BD=93=E5=89=8D=E6=9E=B6?= =?UTF-8?q?=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 / 测试等扩展边界） --- AGENTS.md | 67 +++++++++++++++++++++++++++++++++++++++++++------------ README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+), 14 deletions(-) create mode 100644 README.md diff --git a/AGENTS.md b/AGENTS.md index 6fed0f4..97f642e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # 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. +Compact, repo-specific notes for AI agents. Generic language/framework knowledge is omitted — only things that will bite you if you don't know. Pair this with `README.md` (user-facing quick-start + add-a-feature checklist + deploy flow). ## Stack & runtime @@ -17,6 +17,7 @@ bun run build # bunx --bun vite build → .output/ bun run compile # bun compile.ts → out/server- (standalone CLI binary) bun run cli # bun bin.ts — run a CLI subcommand in source (dev) bun run typecheck # tsc --noEmit +bun run test # bun test — runs all *.test.ts files (colocated with source) 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 @@ -26,7 +27,7 @@ bun run db:studio # Drizzle Studio Cross-compile targets live under `compile:{linux,darwin,windows}[:arch]`. `compile.ts` accepts `--target bun--`; 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. +Before committing: `bun run fix && bun run typecheck && bun run test`. No CI, no pre-commit hooks, no lint-staged — so these are on you. ## Drizzle (v0.x — critical) @@ -46,7 +47,7 @@ Before committing: `bun run fix && bun run typecheck`. No CI, no pre-commit hook - Every table must spread `...generatedFields` from `src/server/db/fields.ts` (`id` UUIDv7 via `$defaultFn(uuidv7)`, `createdAt`, `updatedAt` with `$onUpdateFn`). `generatedFieldKeys` (hand-written `as const`) feeds `createInsertSchema(...).omit(...)`. - `src/server/db/index.ts` exports a module-level `const db = drizzle(...)` — not a lazy singleton. On Bun this is a long-lived process, so top-level side effects are fine and requested. Don't reintroduce `getDB/closeDB` ceremony; the Nitro shutdown plugin calls `db.$client.end()` directly. (Cloudflare Workers would need per-request init — we don't support that deployment target.) - `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. +- The `./drizzle/` migrations directory ships empty with a `.gitkeep`. 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 @@ -77,19 +78,31 @@ Contract → Router → Handler → Client, all type-safe from a single contract ``` Barrel-aggregated in `contracts/index.ts` as `export const contract = { todo }`. - Routers (`src/server/api/routers/*.router.ts`) import `db` directly from `@/server/db` in their handlers. There is **no `middlewares/` directory** by default — `db` doesn't need one (module-level const). When you actually need per-request context (auth, tenant, rate-limit), create `src/server/api/middlewares/.middleware.ts` with `os.middleware(...)` and extend `BaseContext` in `context.ts`. -- **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`. +- **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`. `logError` calls `logger.error` from `@/server/logger` — never `console.*` directly. - 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. +- **Mutation invalidation is colocated at the call site** via `mutationOptions({ onSuccess })`, not in `src/client/orpc.ts`. `orpc` in `src/client/orpc.ts` is a plain `createTanstackQueryUtils(client)` — no `experimental_defaults`. Per-feature query helpers live in `src/client/queries/.ts` (e.g. `useInvalidateTodos`); routes/components compose those hooks rather than holding query keys inline. See `src/client/queries/todo.ts` + `src/routes/index.tsx` for the canonical shape. - 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"`. +- 2-space, LF, single quotes, **semicolons as-needed** (omitted unless required), 120-col, arrow parens always, `useArrowFunction: "error"` (covers function *expressions* only). Also `noReactPropAssignments: "error"`. +- **Route components use `function Foo()` declarations**, placed below the `Route` config so the file reads top-down (route on top, component below). This is the official TanStack Router/Start pattern and relies on hoisting — `const Foo = () => {}` would TDZ-error when referenced from `createFileRoute({ component: Foo })` above it. Inline arrows are fine for trivial leaf components (e.g. plain redirect routes). Non-route components (UI primitives in `src/components/`) use `const Foo = () => {}`. - 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. +## Testing + +`bun test` runs all `*.test.ts` files. Tests are colocated next to the source they exercise (e.g. `src/server/api/contracts/todo.contract.test.ts`). Use `import { describe, expect, test } from 'bun:test'`. The `@/*` alias resolves in tests via tsconfig paths. No Vitest, no Jest, no separate test config — keep it that way unless you need a browser/JSDOM environment. + +## Endpoints + +- `/` — Todos UI (file route). +- `/health` — bare `GET` returning `ok` (200, `text/plain`). Liveness only — no DB check, so it stays green even when Postgres is down. Add a separate `/ready` if you ever need readiness. +- `/api/rpc` — ORPC RPC handler (POST). +- `/api/*` — ORPC OpenAPI handler. Docs at `/api/docs`, spec at `/api/spec.json`. + ## TypeScript Strict mode, plus `noUncheckedIndexedAccess`, `verbatimModuleSyntax`, `erasableSyntaxOnly`, `noImplicitOverride`. No `as any` / `@ts-ignore` / `@ts-expect-error`. @@ -98,7 +111,7 @@ Path alias: `@/* → src/*`. For files outside `src/` use `@/../` (example ## 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`. +`src/env.ts` via `@t3-oss/env-core`. Server: `DATABASE_URL` (required, `z.url()`). `client: {}` is empty by default — any client-side env must be `VITE_`-prefixed. Never commit `.env`. ## Docker / deploy @@ -111,33 +124,44 @@ Path alias: `@/* → src/*`. For files outside `src/` use `@/../` (example ``` src/ -├── client/orpc.ts # isomorphic ORPC client + experimental_defaults invalidation +├── client/ +│ ├── orpc.ts # isomorphic ORPC client + TanStack Query utils (no global invalidation defaults) +│ └── queries/ # per-feature query hooks: keys, options, `useInvalidate` helpers ├── 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 +├── routes/ +│ ├── __root.tsx # root route + RootDocument shell +│ ├── index.tsx # Todos UI +│ ├── health.ts # GET /health → "ok" (no DB) +│ └── api/ +│ ├── $.ts # OpenAPI + Scalar; interceptors registered here +│ └── rpc.$.ts # RPC; interceptors registered here ├── server/ +│ ├── logger.ts # the only log entrypoint — wrap before swapping to pino/otel │ ├── api/ │ │ ├── server.ts # the ONLY place to build `os` │ │ ├── context.ts # BaseContext (add per-request fields when you add middlewares) -│ │ ├── interceptors.ts # logError, handleValidationError +│ │ ├── interceptors.ts # logError (→ logger), handleValidationError │ │ ├── types.ts # Router{Client,Inputs,Outputs} derived from Contract -│ │ ├── contracts/ # Zod schemas from Drizzle tables (barrel: contract) +│ │ ├── contracts/ # Zod schemas from Drizzle tables (barrel: contract); colocated *.test.ts │ │ └── routers/ # os.* handlers (barrel: router) — import db directly │ ├── db/ │ │ ├── index.ts # module-level `export const db = drizzle({...})` │ │ ├── fields.ts # generatedFields (id/createdAt/updatedAt) + generatedFieldKeys │ │ └── schema/ # pgTable definitions; also put `relations()` here when adding │ └── plugins/ -│ └── shutdown.ts # SIGINT/SIGTERM → db.$client.end() with 500ms delay +│ └── shutdown.ts # SIGINT/SIGTERM → db.$client.end() with 500ms delay (prod only) +├── components/ # non-route UI primitives (PascalCase, arrow const) ├── env.ts # t3-oss env validation ├── router.tsx # QueryClient + setupRouterSsrQueryIntegration +├── styles.css # Tailwind v4 entry └── routeTree.gen.ts # auto-generated, do not edit bin.ts # citty entry (root) — keep imports minimal (see "CLI" section) +compile.ts # `bun build --compile` driver; resolves --target +drizzle/ # SQL migrations (.gitkeep until first `bun run db:generate`) ``` Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not via a Nitro config file. @@ -154,3 +178,18 @@ Nitro plugins are wired in `vite.config.ts` (`nitro({ plugins: [...] })`), not v - Don't use `drizzle-orm/bun-sql`. - Don't use `@/*` aliases in `drizzle.config.ts`. - Don't commit `.env`. + +## Room-to-grow rules (discipline for the first real feature) + +These keep the starter from setting bad precedents as it grows. Append, don't restructure. + +1. Per-feature client query code — keys, options, `useInvalidate` helpers — lives in `src/client/queries/.ts`. Routes/components compose these hooks; they don't hold query keys inline. +2. Mutation invalidation stays explicit at the mutation call site (`mutationOptions({ onSuccess })`) or in a feature query helper. Do not reintroduce global `experimental_defaults` or any implicit cache policy. +3. Client state defaults to route/component local state. Create a store (zustand or equivalent) only when state is shared across routes or needs persistence. +4. Middlewares (`src/server/api/middlewares/.middleware.ts`) derive request-scoped context or gate access. They do NOT orchestrate business flow, hold side effects, or replace handlers/services. +5. Interceptors (`src/server/api/interceptors.ts`) do cross-cutting error logging, transport normalization, and validation rewrites. They do NOT read business data. +6. One file per Drizzle table. Relations live in the same file and are exported as `Relations`. No global `relations.ts`. +7. One router file per feature (`routers/.router.ts`). Only introduce `routers//index.ts` when a domain grows past ~5 router files or needs shared domain helpers. +8. All server-side logging goes through `src/server/logger.ts`. Do not call `console.error/info/warn` directly from business code. +9. CLI subcommand modules keep top-level imports to `citty` + Node built-ins. Env, db, and server code are `await import(...)`-ed inside `run()` (see `bin.ts` comment for why). +10. Every new business feature ships with at least one `bun test` covering a contract schema, a pure helper, or a router behavior. diff --git a/README.md b/README.md new file mode 100644 index 0000000..0983b48 --- /dev/null +++ b/README.md @@ -0,0 +1,61 @@ +# 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](./AGENTS.md). Read it before making structural changes. + +## Quick start + +```bash +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-` via `bun build --compile` | +| `bun run cli ` | 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: + +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/routes/.tsx` — UI with `useSuspenseQuery` + loader `ensureQueryData`; invalidate affected list queries in mutation `onSuccess` handlers. +8. `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. + +```bash +./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. + +```bash +docker compose up --build +```