@alxia/create 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/guide.md CHANGED
@@ -1,10 +1,12 @@
1
1
  # Guide
2
2
 
3
- How `bun create @alxia` asks, what each template writes, and how it
4
- chooses the versions it writes.
3
+ How `bun create @alxia` asks, what each template writes, how the `api`
4
+ project grows from its OpenAPI document, and how the command chooses the
5
+ versions it writes.
5
6
 
6
7
  - [Running it](#running-it)
7
8
  - [The `api` template](#the-api-template)
9
+ - [Adding an operation](#adding-an-operation)
8
10
  - [The `react-router` template](#the-react-router-template)
9
11
  - [Lint and format](#lint-and-format)
10
12
  - [Docker](#docker)
@@ -71,89 +73,399 @@ repository ([Lint and format](#lint-and-format)).
71
73
 
72
74
  ```
73
75
  my-api/
76
+ ├── openapi.yaml the contract: every operation, its parameters, body and replies
77
+ ├── openapi-codegen.config.ts how `bun run generate` reads it
74
78
  ├── src/
75
- │ ├── app.ts the app, and its type
76
- │ ├── app.spec.ts bun test: app.request() and @alxia/client
77
- │ └── server.ts app.listen(PORT), stopped on SIGTERM
79
+ │ ├── generated/ what `bun run generate` writes: committed, never edited
80
+ │ ├── context.ts the base: what every route reads, and its Register
81
+ │ ├── routes/todos.ts defineRoutes(): one route per operation
82
+ │ ├── app.ts the app: the base, then the routes, and its type
83
+ │ ├── app.spec.ts bun test: app.request(), no port, and matchesSpec
84
+ │ └── server.ts app.listen(PORT), stopped on SIGTERM
78
85
  ├── package.json
79
86
  ├── tsconfig.json
80
- ├── biome.json Biome: lint, format, imports sorted
81
- ├── .vscode/ Biome's extension recommended, format on save
82
- ├── Dockerfile bun run build, then dist/ alone, on oven/bun:1-alpine
87
+ ├── biome.json Biome: lint, format, imports sorted
88
+ ├── .vscode/ Biome's extension recommended, format on save
89
+ ├── Dockerfile bun run build, then dist/ alone, on oven/bun:1-alpine
83
90
  ├── .dockerignore
84
- ├── .env.example PORT and API_KEY, for a .env Bun loads
91
+ ├── .env.example PORT and API_KEY, for a .env Bun loads
85
92
  ├── .gitignore
86
93
  └── README.md
87
94
  ```
88
95
 
89
- `src/app.ts` is one route, `POST /todos`, with what a real one needs: a
90
- body validated by a Zod schema, a declared reply, and a hook of its own.
96
+ The project is OpenAPI spec first: `openapi.yaml` is written first, the
97
+ code is generated from it, and the app binds a handler to each generated
98
+ operation. A client in another project is generated from the same file.
99
+
100
+ ### `openapi.yaml`
101
+
102
+ Three operations, each with an `operationId`, which names it everywhere
103
+ after:
104
+
105
+ | operation | `operationId` | replies |
106
+ | --- | --- | --- |
107
+ | `GET /todos` | `listTodos` | 200, the todos |
108
+ | `POST /todos` | `createTodo` | 201, the todo; 400; 401 without the `x-api-key` header (`security: apiKey`) |
109
+ | `GET /todos/{id}` | `getTodo` | 200; 400, an `id` that is not a whole number of 1 or more; 404 |
110
+
111
+ ```yaml
112
+ # openapi.yaml, in part
113
+ /todos/{id}:
114
+ get:
115
+ operationId: getTodo
116
+ summary: One todo
117
+ parameters:
118
+ - name: id
119
+ in: path
120
+ required: true
121
+ schema: { type: integer, minimum: 1 }
122
+ responses:
123
+ "200":
124
+ description: The todo
125
+ content:
126
+ application/json:
127
+ schema: { $ref: "#/components/schemas/Todo" }
128
+ "400":
129
+ $ref: "#/components/responses/ValidationError"
130
+ "404":
131
+ description: No todo has this id
132
+ content:
133
+ application/json:
134
+ schema: { $ref: "#/components/schemas/NotFound" }
135
+ ```
136
+
137
+ The 400 is declared once, as `components.responses.ValidationError`, and
138
+ is the body alxia itself sends when a request breaks the operation's
139
+ schemas, `@alxia/core`'s `ValidationErrorBody`:
140
+
141
+ ```json
142
+ { "error": "validation", "issues": [{ "target": "body", "path": ["title"], "code": "too_small", "message": "…" }] }
143
+ ```
144
+
145
+ Declared in the spec, it is in every generated client's types, and the
146
+ app checks its own refusals against it like any other reply.
147
+
148
+ ### `openapi-codegen.config.ts`
149
+
150
+ ```ts
151
+ import { defineConfig } from "@nxgt/openapi-codegen";
152
+
153
+ export default defineConfig({
154
+ input: "openapi.yaml",
155
+ output: "src/generated",
156
+ alxia: true,
157
+ validationErrors: false,
158
+ });
159
+ ```
160
+
161
+ | option | value | effect |
162
+ | --- | --- | --- |
163
+ | `input` | `"openapi.yaml"` | the spec |
164
+ | `output` | `"src/generated"` | where the files go |
165
+ | `alxia` | `true` | adds `alxia.ts`: each operation as the data `app.route()` takes |
166
+ | `validationErrors` | `false` | declares no 400 of the generator's own (below) |
167
+
168
+ `validationErrors` is `true` by default, and then declares another
169
+ server's 400 body, `{ status, message, timestamp, issues }`, in the
170
+ files a client reads (`types.ts`, `zod.ts`, `operations.ts`,
171
+ `paths.ts`). alxia never sends that body. Turned off, the generated files
172
+ declare only the spec's own 400, which is the one alxia sends.
173
+
174
+ ### `src/generated/`
175
+
176
+ `bun run generate` runs `nxgt-openapi generate`, the bin of
177
+ [`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen):
178
+
179
+ ```
180
+ openapi.yaml → src/generated: 5 written, 0 unchanged
181
+ ```
182
+
183
+ | file | holds |
184
+ | --- | --- |
185
+ | `alxia.ts` | one `as const` constant per operation, `{ method, path, schema }`, with the path in alxia's form (`/todos/:id`), the request's Zod schemas, a schema per response status and the `operationId`; and `operations`, all of them by `operationId` |
186
+ | `zod.ts` | a Zod schema per component schema: `zTodo`, `zNewTodo`, … |
187
+ | `types.ts` | a TypeScript type per component schema: `Todo`, `NewTodo`, … |
188
+ | `operations.ts`, `paths.ts` | the operations and paths as types, for a typed client |
91
189
 
92
190
  ```ts
93
- import { alxia, defineHook } from "@alxia/core";
94
- import { z } from "zod";
191
+ // src/generated/alxia.ts, in part
192
+ export const createTodo = {
193
+ method: "POST",
194
+ path: "/todos",
195
+ schema: {
196
+ body: zNewTodo,
197
+ response: { 201: zTodo, 400: zValidationError, 401: zUnauthorized },
198
+ detail: { operationId: "createTodo", summary: "Add a todo" },
199
+ },
200
+ } as const;
201
+ ```
202
+
203
+ **The folder is committed.** Nothing is generated at install or at build:
204
+
205
+ - `bun install` runs no script, and `bun dev`, `bun test` and
206
+ `bun run build` read the files as they are;
207
+ - the `Dockerfile` is the same as without a spec: its build stage runs
208
+ `bun run build`, and `openapi.yaml` is not read;
209
+ - a clone builds offline, and a review shows what a change to
210
+ `openapi.yaml` changed in the code.
95
211
 
96
- const Todo = z.object({ id: z.number(), title: z.string(), done: z.boolean() });
97
- const NewTodo = z.object({ title: z.string().min(1) });
212
+ The cost is that the files can drift from the spec: `openapi.yaml` edited
213
+ and `bun run generate` forgotten. `bun run verify` runs
214
+ `bun run generate --check` first, which writes nothing, lists each stale
215
+ file and exits 1
216
+ ([troubleshooting](troubleshooting.md#openapiyaml--srcgenerated-out-of-date-run-nxgt-openapi-generate)).
217
+
218
+ `biome.json` skips `src/generated/`, `"!!**/src/generated"` in its
219
+ `files.includes`, as it skips `dist/`: the generator writes its own
220
+ style, and `bun run check` would otherwise rewrite the files and make
221
+ `generate --check` fail.
222
+
223
+ `@nxgt/openapi-codegen` is a devDependency pinned exactly, since another
224
+ release may write the files differently. The command keeps the version
225
+ the template ships, never moving it to a newer patch ([Versions](#versions)),
226
+ so `bun run verify` passes in a fresh project whatever a later release
227
+ writes. Moving it is a change to review:
228
+
229
+ ```sh
230
+ bun add --dev --exact @nxgt/openapi-codegen@latest
231
+ bun run generate
232
+ git diff src/generated
233
+ ```
234
+
235
+ What the generator does not write, in 0.6.0, and how the app does it
236
+ instead:
237
+
238
+ - **`security`**: no middleware is generated from it. Authentication is
239
+ a middleware the app writes, `requireKey` here, given to the routes
240
+ that need it.
241
+ - **A cookie parameter**: the generator refuses the whole spec
242
+ ([troubleshooting](troubleshooting.md#cookie-parameter-session-is-not-supported-unsupported_parameter)).
243
+ Read the cookie in a middleware, or validate it with `validate({ cookies })`
244
+ by hand.
245
+ - **Named server-sent events** (an `itemSchema` with `event` names): the
246
+ operation is left out of `alxia.ts` with a warning; declare that route
247
+ by hand with `@alxia/core`'s `eventStream`.
248
+
249
+ ### `src/context.ts`
250
+
251
+ ```ts
252
+ import { alxia } from "@alxia/core";
253
+ import type { Todo } from "./generated/types";
98
254
 
99
255
  /** Set API_KEY in the environment: this default is for development. */
100
256
  export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
101
257
 
102
- const requireKey = defineHook(({ request, reply }) =>
258
+ const todos: Todo[] = [];
259
+
260
+ // The base: what every route reads, decorated or derived here. It is
261
+ // registered below, so a route file reads it with no import of the app.
262
+ export const base = alxia().decorate({ todos });
263
+
264
+ // Register the base, never the app: the app mounts the route files, whose
265
+ // type reads this, and would then be typed by itself.
266
+ declare module "@alxia/core" {
267
+ interface Register {
268
+ context: typeof base;
269
+ }
270
+ }
271
+ ```
272
+
273
+ The base is what every route reads: here the todos, decorated. Register it
274
+ once, and each route file reads that context with no import of the app
275
+ ([Register and AppContext](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/types.md#register-and-appcontext)).
276
+ Register `base`, never `app`: `app` mounts the route files, whose type
277
+ reads `Register`, so it would be typed by itself, `TS7022`. A `derive`
278
+ for a `user` from a session goes here too, and every route then reads
279
+ `user` typed.
280
+
281
+ ### `src/routes/todos.ts`
282
+
283
+ ```ts
284
+ import { defineMiddleware, defineRoutes } from "@alxia/core";
285
+ import { apiKey } from "../context";
286
+ import { operations } from "../generated/alxia";
287
+
288
+ // A middleware of the routes it is given to: it answers 401 without the key,
289
+ // before the body is read. openapi.yaml declares that 401.
290
+ const requireKey = defineMiddleware(({ request, reply }, next) =>
103
291
  request.headers.get("x-api-key") === apiKey
104
- ? undefined
292
+ ? next()
105
293
  : reply(401, { error: "unauthorized" as const }),
106
294
  );
107
295
 
108
- const todos: z.infer<typeof Todo>[] = [];
109
-
110
- export const app = alxia()
111
- .decorate({ todos })
112
- .post(
113
- "/todos",
114
- [requireKey],
115
- { body: NewTodo, response: { 201: Todo } },
116
- ({ body, todos, reply }) => {
117
- const todo = { id: todos.length + 1, title: body.title, done: false };
118
- todos.push(todo);
119
- return reply.created(todo);
120
- },
121
- );
296
+ // Each route is an operation of openapi.yaml, generated into
297
+ // src/generated/alxia.ts: its method, path and schemas come from the spec,
298
+ // so the handler is all that is written here. The request is validated
299
+ // just before the handler, and its reply against the spec's responses.
300
+ // `todos` is the registered context's: defineRoutes() reads it, and the
301
+ // app that mounts these routes must give it.
302
+ export const todoRoutes = defineRoutes()
303
+ .route(operations.listTodos, ({ todos, reply }) => reply.ok(todos))
304
+ .route(operations.createTodo, requireKey, ({ body, todos, reply }) => {
305
+ const todo = { id: todos.length + 1, title: body.title, done: false };
306
+ todos.push(todo);
307
+ return reply.created(todo);
308
+ })
309
+ .route(operations.getTodo, ({ params, todos, reply }) => {
310
+ const todo = todos.find(({ id }) => id === params.id);
311
+ return todo
312
+ ? reply.ok(todo)
313
+ : reply.notFound({ error: "not_found" as const });
314
+ });
315
+ ```
316
+
317
+ `defineRoutes()` is a plugin, `alxia()` at runtime, typed with the
318
+ registered context: the handlers read `todos`. It requires that context
319
+ of the app that mounts it, so `alxia().plugin(todoRoutes)` is a compile
320
+ error. It takes no prefix here: an operation's path is already whole.
321
+
322
+ ### `src/app.ts`
323
+
324
+ ```ts
325
+ import { base } from "./context";
326
+ import { todoRoutes } from "./routes/todos";
327
+
328
+ // The base, then the route files: each requires the base's context, so
329
+ // mounting one before it is a compile error.
330
+ export const app = base.plugin(todoRoutes);
122
331
 
123
332
  export type App = typeof app;
124
333
  ```
125
334
 
126
- - `requireKey` runs before the body is read: a request without the key is a
127
- 401 whatever its body, and that 401 joins the route's type
128
- ([Hooks on one route](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md#hooks-on-one-route)).
129
- - An empty `title` is a 400 naming `title`, before the handler runs.
130
- - `todos` lives in memory: replace the array with your database, given to
131
- the routes the same way, by `decorate`.
335
+ ```ts
336
+ route(operation, ...middlewares, handler)
337
+ ```
132
338
 
133
- `src/app.spec.ts` calls the app in process, no port: `app.request()` with a
134
- JSON body, then `@alxia/client` given the app itself, whose result is typed
135
- by status:
339
+ - **The operation gives the method, the path and the schemas.** The
340
+ handler is all the route writes; its `params`, `body` and `reply` are
341
+ typed by the spec: `params.id` is a number, as `openapi.yaml` declares
342
+ it, and `reply` takes only the statuses the operation declares.
343
+ - **The middlewares run in the order given.** `requireKey` comes first,
344
+ so a request without the key is a 401 before its body is read, whatever
345
+ the body
346
+ ([A route's middlewares](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md#a-routes-middlewares)).
347
+ - **The request is validated just before the handler**: an empty
348
+ `title` is a 400 naming `title`, `/todos/first` a 400 naming `id`, and
349
+ the handler never runs. To validate before a middleware instead, place
350
+ `validate(operations.createTodo)` among the middlewares.
351
+ - **The handler's reply is checked against the spec's responses**: a
352
+ reply the spec refuses is not sent; the client gets a 500
353
+ ([troubleshooting](troubleshooting.md#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)).
354
+ A middleware's own reply, `requireKey`'s 401, is sent as it is; to check
355
+ it against `Unauthorized` too, place `responds(operations.createTodo)`
356
+ before `requireKey`.
357
+ - **`todos` lives in memory**: replace the array with your database,
358
+ given to the routes the same way, by `decorate`.
359
+
360
+ ### `src/app.spec.ts`
136
361
 
137
362
  ```ts
138
- const api = client(app, { headers: { "x-api-key": apiKey } });
139
- const created = await api.post("/todos", { body: { title: "Call it typed" } });
140
- if (created.status !== 201) throw new Error(`got ${created.status}`);
141
- expect(created.data.title).toBe("Call it typed"); // data is the Todo schema's type
363
+ import { expect, test } from "bun:test";
364
+ import { matchesSpec } from "@alxia/openapi";
365
+ import { app } from "./app";
366
+ import { apiKey } from "./context";
367
+ import { operations } from "./generated/alxia";
368
+
369
+ test("routes every operation of openapi.yaml, and nothing else", () => {
370
+ matchesSpec(app, operations);
371
+ });
372
+
373
+ test("creates a todo from JSON", async () => {
374
+ const response = await app.request("/todos", {
375
+ method: "POST",
376
+ headers: { "content-type": "application/json", "x-api-key": apiKey },
377
+ body: JSON.stringify({ title: "Write a route" }),
378
+ });
379
+ expect(response.status).toBe(201);
380
+ });
142
381
  ```
143
382
 
383
+ `matchesSpec(app, operations)`, from
384
+ [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi), throws
385
+ when an operation has no route, or a route has no operation, naming each.
386
+ The spec also checks the 400, the 401 before the body and the 404, each
387
+ with `app.request()`, in process, with no port.
388
+
389
+ ### Adding an operation
390
+
391
+ A route starts in `openapi.yaml`. To add `DELETE /todos/{id}`:
392
+
393
+ 1. Declare it, with an `operationId`:
394
+
395
+ ```yaml
396
+ # openapi.yaml, under /todos/{id}, beside get
397
+ delete:
398
+ operationId: deleteTodo
399
+ security:
400
+ - apiKey: []
401
+ parameters:
402
+ - name: id
403
+ in: path
404
+ required: true
405
+ schema: { type: integer, minimum: 1 }
406
+ responses:
407
+ "204":
408
+ description: The todo, removed
409
+ "400":
410
+ $ref: "#/components/responses/ValidationError"
411
+ "401":
412
+ description: No x-api-key header, or not the key
413
+ content:
414
+ application/json:
415
+ schema: { $ref: "#/components/schemas/Unauthorized" }
416
+ "404":
417
+ description: No todo has this id
418
+ content:
419
+ application/json:
420
+ schema: { $ref: "#/components/schemas/NotFound" }
421
+ ```
422
+
423
+ 2. Generate:
424
+
425
+ ```sh
426
+ bun run generate
427
+ ```
428
+
429
+ `src/generated/alxia.ts` now exports `operations.deleteTodo`. Until
430
+ the app routes it, `bun test` fails:
431
+
432
+ ```
433
+ TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)
434
+ ```
435
+
436
+ 3. Bind it in `src/routes/todos.ts`, after the `getTodo` route:
437
+
438
+ ```ts
439
+ .route(operations.deleteTodo, requireKey, ({ params, todos, reply }) => {
440
+ const index = todos.findIndex(({ id }) => id === params.id);
441
+ if (index === -1) return reply.notFound({ error: "not_found" as const });
442
+ todos.splice(index, 1);
443
+ return reply.noContent();
444
+ });
445
+ ```
446
+
447
+ 4. Check, and commit `openapi.yaml` with `src/generated/`:
448
+
449
+ ```sh
450
+ bun run verify
451
+ ```
452
+
453
+ ### The rest
454
+
144
455
  The scripts:
145
456
 
146
457
  | script | runs |
147
458
  | --- | --- |
148
459
  | `bun dev` | `bun --watch src/server.ts`: restarted on every change, on `PORT` or 3000 |
149
460
  | `bun test` | the spec |
461
+ | `bun run generate` | `nxgt-openapi generate`: `src/generated/` from `openapi.yaml`. `bun run generate --check` writes nothing and exits 1 when a file is stale |
150
462
  | `bun run typecheck` | `tsc --noEmit` |
151
463
  | `bun run build` | `bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked`: one file, its dependencies bundled |
152
464
  | `bun start` | `bun dist/server.js`: the build, after `bun run build` |
153
465
  | `bun run check` | `biome check --write`: lint, format, sort imports, fixing what it can |
154
466
  | `bun run lint`, `bun run format` | `biome lint`, `biome format --write` |
155
467
  | `bun run check:ci` | `biome ci`: read-only, for CI |
156
- | `bun run verify` | `check:ci`, `typecheck`, then `test` |
468
+ | `bun run verify` | `generate --check`, `check:ci`, `typecheck`, then `test` |
157
469
 
158
470
  `start` runs what `build` wrote, as production and the image do:
159
471
 
@@ -178,7 +490,8 @@ keeps out of git and `.dockerignore` out of the image.
178
490
  `noUnusedLocals` and the rest. Hence `Bun.env["API_KEY"]` and not
179
491
  `Bun.env.API_KEY`, and Biome's `useLiteralKeys`, which would ask for the
180
492
  second, is off in `biome.json`. Loosen what you would rather not keep:
181
- alxia's types compile under each one, and under none.
493
+ alxia's types, and the generated files, compile under each one, and under
494
+ none.
182
495
 
183
496
  ## The `react-router` template
184
497
 
@@ -250,7 +563,7 @@ files are what `create-react-router` wrote when the template was last
250
563
  generated (React Router 8.4.0 in this release), and the versions are the newest of that major.
251
564
 
252
565
  There is no `app/server.ts`: the plugin's default server serves the pages
253
- in `bun dev` and from the build. To put alxia's hooks or `/api` routes in
566
+ in `bun dev` and from the build. To put alxia's middlewares or `/api` routes in
254
567
  front of the pages, write it out and edit it:
255
568
 
256
569
  ```sh
@@ -294,7 +607,8 @@ configuration of its own, extending nothing:
294
607
  ```
295
608
 
296
609
  That is the `react-router` project's, written here compact. The `api`
297
- project's skips `dist/` instead of `build/` and `.react-router/`, has no
610
+ project's skips `dist/` and `src/generated/` instead of `build/` and
611
+ `.react-router/`, has no
298
612
  CSS settings and no overrides, and turns `complexity.useLiteralKeys` off
299
613
  in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
300
614
 
@@ -306,8 +620,8 @@ in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
306
620
  - **`$schema` is the installed Biome's own schema**, so an editor checks
307
621
  the file against the version `bun install` put in `node_modules`,
308
622
  whichever the command wrote.
309
- - **What is generated is skipped.** `files.includes` leaves `dist/`, or
310
- `build/` and `.react-router/`, out, and `vcs.useIgnoreFile` every path
623
+ - **What is generated is skipped.** `files.includes` leaves `dist/` and
624
+ `src/generated/`, or `build/` and `.react-router/`, out, and `vcs.useIgnoreFile` every path
311
625
  `.gitignore` names, the project in a git repository or not (with no
312
626
  `.gitignore` and no git repository, Biome refuses to run:
313
627
  [troubleshooting](troubleshooting.md#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)).
@@ -336,7 +650,7 @@ bunx biome migrate --write
336
650
  | `bun run lint` | `biome lint` |
337
651
  | `bun run format` | `biome format --write` |
338
652
  | `bun run check:ci` | `biome ci`: changes nothing, and fails on any error |
339
- | `bun run verify` | `check:ci`, `typecheck`, then `test` (`api`) or `build` (`react-router`) |
653
+ | `bun run verify` | `api`: `generate --check`, `check:ci`, `typecheck`, then `test`; `react-router`: `check:ci`, `typecheck`, then `build` |
340
654
 
341
655
  The read-only one is `check:ci`, not `ci`: `bun ci` is Bun's
342
656
  `bun install --frozen-lockfile`, and a script named `ci` would only run
@@ -386,6 +700,9 @@ Bun's `--no-install` (not create-alxia's option of the same name), so that a pac
386
700
  startup rather than being fetched from npm, written out so that Bun
387
701
  is the container's process. `src/server.ts` stops the app on `SIGTERM`:
388
702
  as process 1, Bun would otherwise ignore it, and `docker stop` would wait.
703
+ Nothing is generated in the image: `src/generated/` is committed, and
704
+ `COPY . .` brings it with the rest, so the build stage runs no
705
+ `bun run generate` and needs no `openapi.yaml`.
389
706
 
390
707
  ```dockerfile
391
708
  FROM oven/bun:1 AS build
@@ -448,12 +765,13 @@ template pins exactly:
448
765
 
449
766
  | dependency | moved to the newest within |
450
767
  | --- | --- |
451
- | `@alxia/core`, `@alxia/client`, `@alxia/react-router` | the ranges this `@alxia/create` was published with, such as `^0.3.1`; while the registry does not serve that version yet, the newest of its minor, `~0.3.0` |
768
+ | `@alxia/core`, `@alxia/openapi`, `@alxia/react-router` | the ranges this `@alxia/create` was published with, such as `^0.3.1`; while the registry does not serve that version yet, the newest of its minor, `~0.3.0` |
452
769
  | `typescript` | `^6.0.3 \|\| ^7.0.0`, every alxia package's peer range |
453
770
  | `zod` | `^4.2.0`, `@alxia/zod`'s |
454
771
  | `vite` | `^7.0.0 \|\| ^8.0.0`, `@alxia/react-router`'s |
455
772
  | `react-router`, `@react-router/*` | `^8.0.0`, `@alxia/react-router`'s; the `@react-router/*` packages take `react-router`'s version, which `@react-router/node` pins exactly |
456
- | `@biomejs/biome` | its own minor, from the exact version the template pins (`~2.5.15`): written exactly, `2.5.16`, never `^` |
773
+ | `@biomejs/biome` | its own minor, from the exact version the template pins (`~2.5.15`): written exactly, `2.5.16`, never `^`. A minor of Biome may add a recommended rule |
774
+ | `@nxgt/openapi-codegen` | none: the template's exact version, `0.6.0`, is kept. Any release may write `src/generated/` differently, and `bun run verify` checks it with `generate --check` |
457
775
  | anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
458
776
 
459
777
  The command prints each move, and each newer major it left out:
package/docs/roadmap.md CHANGED
@@ -7,7 +7,11 @@ number on it. Every release, with each change it made, is in
7
7
 
8
8
  ## Now
9
9
 
10
- Nothing scheduled yet.
10
+ - **The `api` project split across files.** `src/context.ts` holds the
11
+ base the routes read and registers it with `@alxia/core`'s `Register`;
12
+ `src/routes/todos.ts` binds the operations with `defineRoutes()`,
13
+ reading that context with no import of the app; `src/app.ts` mounts
14
+ them, `base.plugin(todoRoutes)`.
11
15
 
12
16
  ## Next
13
17
 
@@ -23,12 +27,40 @@ Nothing scheduled yet.
23
27
  output, committed and copied: a new project needs nothing but the
24
28
  registry, and no change upstream can stop the command. It is generated
25
29
  again from the scaffold when React Router ships a new major.
30
+ - **Generating the `api` project's code at install or build.**
31
+ `src/generated/` is committed: `bun install` runs no script, the
32
+ `Dockerfile` needs no generation step, a clone builds offline, and a
33
+ review shows what a change to `openapi.yaml` changed in the code.
34
+ `bun run verify`'s `generate --check` keeps the files equal to the spec.
35
+ - **Generating the OpenAPI document from the app.** The document is
36
+ written first and the routes are bound to it; a spec read back from the
37
+ code would describe whatever the code does.
26
38
  - **A runtime dependency.** The prompts are Bun's `prompt()`, the registry
27
39
  is read with `fetch`, versions are compared with `Bun.semver`.
28
40
 
29
41
  ## Shipped
30
42
 
31
- ### Next release
43
+ ### 0.1.6
44
+
45
+ - **The `api` project is OpenAPI spec first.** `openapi.yaml` declares
46
+ its operations; `bun run generate` writes `src/generated/` from it with
47
+ `@nxgt/openapi-codegen`, committed, so the project and its image build
48
+ with no generation step and offline; `src/app.ts` binds each operation
49
+ with `route(operations.createTodo, requireKey, handler)`, which
50
+ validates the request and checks the handler's reply against the spec; the
51
+ spec asserts `matchesSpec` from `@alxia/openapi`, so no operation lacks
52
+ a route; and `bun run verify` starts with `generate --check`, which
53
+ fails when `src/generated/` drifts from `openapi.yaml`. New projects
54
+ install `@alxia/openapi` at the version this release was published
55
+ beside, and `@nxgt/openapi-codegen` pinned exactly, at the version the template ships.
56
+ - **The `api` project is written in `@alxia/core`'s middleware model.**
57
+ `requireKey` is a `defineMiddleware` that answers 401 before the body
58
+ is read, given to the route among its middlewares.
59
+ - **No client package in a new project.** The `api` template's spec calls
60
+ the app with `app.request()`; a typed client is generated from
61
+ `openapi.yaml`, with a generator such as `@nxgt/openapi-codegen`.
62
+
63
+ ### 0.1.5
32
64
 
33
65
  - **Both projects lint and format with Biome.** Each has a `biome.json`
34
66
  of its own (recommended rules, spaces and double quotes, imports
@@ -78,8 +110,8 @@ Nothing scheduled yet.
78
110
  template ships inside `@alxia/create`, with alxia's layer, and is copied
79
111
  as it is: no `create-react-router` runs, and no change in it can make the
80
112
  command refuse.
81
- - **alxia's packages resolve at creation too.** `@alxia/core`,
82
- `@alxia/client` and `@alxia/react-router` move to the newest version
113
+ - **alxia's packages resolve at creation too.** `@alxia/core`
114
+ and `@alxia/react-router` move to the newest version
83
115
  within the ranges `@alxia/create` was published with. Right after a
84
116
  release, while the registry does not serve that version yet, the newest
85
117
  of the same minor is written, so `bun install` no longer fails with