@alxia/create 0.1.5 → 0.1.7

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,400 @@ 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.7.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 in the client files**: `alxia.ts` validates it as
242
+ the route's `cookies`; `types.ts`, `zod.ts`, `operations.ts` and
243
+ `paths.ts` leave it out with an `ignored` warning, since a client does not
244
+ set cookies.
245
+ - **Server-sent events with text data**: the operation is left out of
246
+ `alxia.ts` with a warning; give each event's data a JSON `contentSchema`,
247
+ or declare that route by hand with `@alxia/core`'s `eventStream`. Named
248
+ events whose data is JSON are generated.
249
+
250
+ ### `src/context.ts`
251
+
252
+ ```ts
253
+ import { alxia } from "@alxia/core";
254
+ import type { Todo } from "./generated/types";
98
255
 
99
256
  /** Set API_KEY in the environment: this default is for development. */
100
257
  export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
101
258
 
102
- const requireKey = defineHook(({ request, reply }) =>
259
+ const todos: Todo[] = [];
260
+
261
+ // The base: what every route reads, decorated or derived here. It is
262
+ // registered below, so a route file reads it with no import of the app.
263
+ export const base = alxia().decorate({ todos });
264
+
265
+ // Register the base, never the app: the app mounts the route files, whose
266
+ // type reads this, and would then be typed by itself.
267
+ declare module "@alxia/core" {
268
+ interface Register {
269
+ context: typeof base;
270
+ }
271
+ }
272
+ ```
273
+
274
+ The base is what every route reads: here the todos, decorated. Register it
275
+ once, and each route file reads that context with no import of the app
276
+ ([Register and AppContext](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/types.md#register-and-appcontext)).
277
+ Register `base`, never `app`: `app` mounts the route files, whose type
278
+ reads `Register`, so it would be typed by itself, `TS7022`. A `derive`
279
+ for a `user` from a session goes here too, and every route then reads
280
+ `user` typed.
281
+
282
+ ### `src/routes/todos.ts`
283
+
284
+ ```ts
285
+ import { defineMiddleware, defineRoutes } from "@alxia/core";
286
+ import { apiKey } from "../context";
287
+ import { operations } from "../generated/alxia";
288
+
289
+ // A middleware of the routes it is given to: it answers 401 without the key,
290
+ // before the body is read. openapi.yaml declares that 401.
291
+ const requireKey = defineMiddleware(({ request, reply }, next) =>
103
292
  request.headers.get("x-api-key") === apiKey
104
- ? undefined
293
+ ? next()
105
294
  : reply(401, { error: "unauthorized" as const }),
106
295
  );
107
296
 
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
- );
297
+ // Each route is an operation of openapi.yaml, generated into
298
+ // src/generated/alxia.ts: its method, path and schemas come from the spec,
299
+ // so the handler is all that is written here. The request is validated
300
+ // just before the handler, and its reply against the spec's responses.
301
+ // `todos` is the registered context's: defineRoutes() reads it, and the
302
+ // app that mounts these routes must give it.
303
+ export const todoRoutes = defineRoutes()
304
+ .route(operations.listTodos, ({ todos, reply }) => reply.ok(todos))
305
+ .route(operations.createTodo, requireKey, ({ body, todos, reply }) => {
306
+ const todo = { id: todos.length + 1, title: body.title, done: false };
307
+ todos.push(todo);
308
+ return reply.created(todo);
309
+ })
310
+ .route(operations.getTodo, ({ params, todos, reply }) => {
311
+ const todo = todos.find(({ id }) => id === params.id);
312
+ return todo
313
+ ? reply.ok(todo)
314
+ : reply.notFound({ error: "not_found" as const });
315
+ });
316
+ ```
317
+
318
+ `defineRoutes()` is a plugin, `alxia()` at runtime, typed with the
319
+ registered context: the handlers read `todos`. It requires that context
320
+ of the app that mounts it, so `alxia().plugin(todoRoutes)` is a compile
321
+ error. It takes no prefix here: an operation's path is already whole.
322
+
323
+ ### `src/app.ts`
324
+
325
+ ```ts
326
+ import { base } from "./context";
327
+ import { todoRoutes } from "./routes/todos";
328
+
329
+ // The base, then the route files: each requires the base's context, so
330
+ // mounting one before it is a compile error.
331
+ export const app = base.plugin(todoRoutes);
122
332
 
123
333
  export type App = typeof app;
124
334
  ```
125
335
 
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`.
336
+ ```ts
337
+ route(operation, ...middlewares, handler)
338
+ ```
132
339
 
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:
340
+ - **The operation gives the method, the path and the schemas.** The
341
+ handler is all the route writes; its `params`, `body` and `reply` are
342
+ typed by the spec: `params.id` is a number, as `openapi.yaml` declares
343
+ it, and `reply` takes only the statuses the operation declares.
344
+ - **The middlewares run in the order given.** `requireKey` comes first,
345
+ so a request without the key is a 401 before its body is read, whatever
346
+ the body
347
+ ([A route's middlewares](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/middleware.md#a-routes-middlewares)).
348
+ - **The request is validated just before the handler**: an empty
349
+ `title` is a 400 naming `title`, `/todos/first` a 400 naming `id`, and
350
+ the handler never runs. To validate before a middleware instead, place
351
+ `validate(operations.createTodo)` among the middlewares.
352
+ - **The handler's reply is checked against the spec's responses**: a
353
+ reply the spec refuses is not sent; the client gets a 500
354
+ ([troubleshooting](troubleshooting.md#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)).
355
+ A middleware's own reply, `requireKey`'s 401, is sent as it is; to check
356
+ it against `Unauthorized` too, place `responds(operations.createTodo)`
357
+ before `requireKey`.
358
+ - **`todos` lives in memory**: replace the array with your database,
359
+ given to the routes the same way, by `decorate`.
360
+
361
+ ### `src/app.spec.ts`
136
362
 
137
363
  ```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
364
+ import { expect, test } from "bun:test";
365
+ import { matchesSpec } from "@alxia/openapi";
366
+ import { app } from "./app";
367
+ import { apiKey } from "./context";
368
+ import { operations } from "./generated/alxia";
369
+
370
+ test("routes every operation of openapi.yaml, and nothing else", () => {
371
+ matchesSpec(app, operations);
372
+ });
373
+
374
+ test("creates a todo from JSON", async () => {
375
+ const response = await app.request("/todos", {
376
+ method: "POST",
377
+ headers: { "content-type": "application/json", "x-api-key": apiKey },
378
+ body: JSON.stringify({ title: "Write a route" }),
379
+ });
380
+ expect(response.status).toBe(201);
381
+ });
142
382
  ```
143
383
 
384
+ `matchesSpec(app, operations)`, from
385
+ [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi), throws
386
+ when an operation has no route, or a route has no operation, naming each.
387
+ The spec also checks the 400, the 401 before the body and the 404, each
388
+ with `app.request()`, in process, with no port.
389
+
390
+ ### Adding an operation
391
+
392
+ A route starts in `openapi.yaml`. To add `DELETE /todos/{id}`:
393
+
394
+ 1. Declare it, with an `operationId`:
395
+
396
+ ```yaml
397
+ # openapi.yaml, under /todos/{id}, beside get
398
+ delete:
399
+ operationId: deleteTodo
400
+ security:
401
+ - apiKey: []
402
+ parameters:
403
+ - name: id
404
+ in: path
405
+ required: true
406
+ schema: { type: integer, minimum: 1 }
407
+ responses:
408
+ "204":
409
+ description: The todo, removed
410
+ "400":
411
+ $ref: "#/components/responses/ValidationError"
412
+ "401":
413
+ description: No x-api-key header, or not the key
414
+ content:
415
+ application/json:
416
+ schema: { $ref: "#/components/schemas/Unauthorized" }
417
+ "404":
418
+ description: No todo has this id
419
+ content:
420
+ application/json:
421
+ schema: { $ref: "#/components/schemas/NotFound" }
422
+ ```
423
+
424
+ 2. Generate:
425
+
426
+ ```sh
427
+ bun run generate
428
+ ```
429
+
430
+ `src/generated/alxia.ts` now exports `operations.deleteTodo`. Until
431
+ the app routes it, `bun test` fails:
432
+
433
+ ```
434
+ TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)
435
+ ```
436
+
437
+ 3. Bind it in `src/routes/todos.ts`, after the `getTodo` route:
438
+
439
+ ```ts
440
+ .route(operations.deleteTodo, requireKey, ({ params, todos, reply }) => {
441
+ const index = todos.findIndex(({ id }) => id === params.id);
442
+ if (index === -1) return reply.notFound({ error: "not_found" as const });
443
+ todos.splice(index, 1);
444
+ return reply.noContent();
445
+ });
446
+ ```
447
+
448
+ 4. Check, and commit `openapi.yaml` with `src/generated/`:
449
+
450
+ ```sh
451
+ bun run verify
452
+ ```
453
+
454
+ ### The rest
455
+
144
456
  The scripts:
145
457
 
146
458
  | script | runs |
147
459
  | --- | --- |
148
460
  | `bun dev` | `bun --watch src/server.ts`: restarted on every change, on `PORT` or 3000 |
149
461
  | `bun test` | the spec |
462
+ | `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
463
  | `bun run typecheck` | `tsc --noEmit` |
151
464
  | `bun run build` | `bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked`: one file, its dependencies bundled |
152
465
  | `bun start` | `bun dist/server.js`: the build, after `bun run build` |
153
466
  | `bun run check` | `biome check --write`: lint, format, sort imports, fixing what it can |
154
467
  | `bun run lint`, `bun run format` | `biome lint`, `biome format --write` |
155
468
  | `bun run check:ci` | `biome ci`: read-only, for CI |
156
- | `bun run verify` | `check:ci`, `typecheck`, then `test` |
469
+ | `bun run verify` | `generate --check`, `check:ci`, `typecheck`, then `test` |
157
470
 
158
471
  `start` runs what `build` wrote, as production and the image do:
159
472
 
@@ -178,7 +491,8 @@ keeps out of git and `.dockerignore` out of the image.
178
491
  `noUnusedLocals` and the rest. Hence `Bun.env["API_KEY"]` and not
179
492
  `Bun.env.API_KEY`, and Biome's `useLiteralKeys`, which would ask for the
180
493
  second, is off in `biome.json`. Loosen what you would rather not keep:
181
- alxia's types compile under each one, and under none.
494
+ alxia's types, and the generated files, compile under each one, and under
495
+ none.
182
496
 
183
497
  ## The `react-router` template
184
498
 
@@ -250,7 +564,7 @@ files are what `create-react-router` wrote when the template was last
250
564
  generated (React Router 8.4.0 in this release), and the versions are the newest of that major.
251
565
 
252
566
  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
567
+ in `bun dev` and from the build. To put alxia's middlewares or `/api` routes in
254
568
  front of the pages, write it out and edit it:
255
569
 
256
570
  ```sh
@@ -294,7 +608,8 @@ configuration of its own, extending nothing:
294
608
  ```
295
609
 
296
610
  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
611
+ project's skips `dist/` and `src/generated/` instead of `build/` and
612
+ `.react-router/`, has no
298
613
  CSS settings and no overrides, and turns `complexity.useLiteralKeys` off
299
614
  in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
300
615
 
@@ -306,8 +621,8 @@ in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
306
621
  - **`$schema` is the installed Biome's own schema**, so an editor checks
307
622
  the file against the version `bun install` put in `node_modules`,
308
623
  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
624
+ - **What is generated is skipped.** `files.includes` leaves `dist/` and
625
+ `src/generated/`, or `build/` and `.react-router/`, out, and `vcs.useIgnoreFile` every path
311
626
  `.gitignore` names, the project in a git repository or not (with no
312
627
  `.gitignore` and no git repository, Biome refuses to run:
313
628
  [troubleshooting](troubleshooting.md#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)).
@@ -336,7 +651,7 @@ bunx biome migrate --write
336
651
  | `bun run lint` | `biome lint` |
337
652
  | `bun run format` | `biome format --write` |
338
653
  | `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`) |
654
+ | `bun run verify` | `api`: `generate --check`, `check:ci`, `typecheck`, then `test`; `react-router`: `check:ci`, `typecheck`, then `build` |
340
655
 
341
656
  The read-only one is `check:ci`, not `ci`: `bun ci` is Bun's
342
657
  `bun install --frozen-lockfile`, and a script named `ci` would only run
@@ -386,6 +701,9 @@ Bun's `--no-install` (not create-alxia's option of the same name), so that a pac
386
701
  startup rather than being fetched from npm, written out so that Bun
387
702
  is the container's process. `src/server.ts` stops the app on `SIGTERM`:
388
703
  as process 1, Bun would otherwise ignore it, and `docker stop` would wait.
704
+ Nothing is generated in the image: `src/generated/` is committed, and
705
+ `COPY . .` brings it with the rest, so the build stage runs no
706
+ `bun run generate` and needs no `openapi.yaml`.
389
707
 
390
708
  ```dockerfile
391
709
  FROM oven/bun:1 AS build
@@ -448,12 +766,13 @@ template pins exactly:
448
766
 
449
767
  | dependency | moved to the newest within |
450
768
  | --- | --- |
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` |
769
+ | `@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
770
  | `typescript` | `^6.0.3 \|\| ^7.0.0`, every alxia package's peer range |
453
771
  | `zod` | `^4.2.0`, `@alxia/zod`'s |
454
772
  | `vite` | `^7.0.0 \|\| ^8.0.0`, `@alxia/react-router`'s |
455
773
  | `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 `^` |
774
+ | `@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 |
775
+ | `@nxgt/openapi-codegen` | none: the template's exact version, `0.7.0`, is kept. Any release may write `src/generated/` differently, and `bun run verify` checks it with `generate --check` |
457
776
  | anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
458
777
 
459
778
  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