@alxia/create 0.1.4 → 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.
Files changed (44) hide show
  1. package/README.md +81 -24
  2. package/dist/copy.d.ts +11 -3
  3. package/dist/copy.d.ts.map +1 -1
  4. package/dist/index.js +51 -23
  5. package/dist/index.js.map +8 -7
  6. package/dist/main.d.ts +1 -1
  7. package/dist/main.d.ts.map +1 -1
  8. package/dist/packument.d.ts +18 -0
  9. package/dist/packument.d.ts.map +1 -0
  10. package/dist/registry.d.ts +29 -10
  11. package/dist/registry.d.ts.map +1 -1
  12. package/dist/versions.d.ts +1 -1
  13. package/dist/versions.d.ts.map +1 -1
  14. package/docs/README.md +6 -5
  15. package/docs/guide.md +503 -59
  16. package/docs/roadmap.md +49 -4
  17. package/docs/troubleshooting.md +249 -4
  18. package/package.json +5 -4
  19. package/templates/api/.vscode/extensions.json +3 -0
  20. package/templates/api/.vscode/settings.json +8 -0
  21. package/templates/api/README.md +78 -6
  22. package/templates/api/_biome.json +32 -0
  23. package/templates/api/openapi-codegen.config.ts +11 -0
  24. package/templates/api/openapi.yaml +116 -0
  25. package/templates/api/package.json +27 -19
  26. package/templates/api/src/app.spec.ts +57 -38
  27. package/templates/api/src/app.ts +5 -30
  28. package/templates/api/src/context.ts +19 -0
  29. package/templates/api/src/generated/alxia.ts +61 -0
  30. package/templates/api/src/generated/operations.ts +133 -0
  31. package/templates/api/src/generated/paths.ts +170 -0
  32. package/templates/api/src/generated/types.ts +170 -0
  33. package/templates/api/src/generated/zod.ts +31 -0
  34. package/templates/api/src/routes/todos.ts +31 -0
  35. package/templates/api/src/server.ts +12 -12
  36. package/templates/api/tsconfig.json +23 -23
  37. package/templates/react-router/.vscode/extensions.json +3 -0
  38. package/templates/react-router/.vscode/settings.json +8 -0
  39. package/templates/react-router/README.md +27 -0
  40. package/templates/react-router/_biome.json +49 -0
  41. package/templates/react-router/app/app.css +3 -2
  42. package/templates/react-router/app/routes/home.tsx +1 -1
  43. package/templates/react-router/app/routes.ts +1 -1
  44. package/templates/react-router/package.json +7 -1
package/docs/guide.md CHANGED
@@ -1,11 +1,14 @@
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)
11
+ - [Lint and format](#lint-and-format)
9
12
  - [Docker](#docker)
10
13
  - [Versions](#versions)
11
14
  - [In a script or CI](#in-a-script-or-ci)
@@ -45,7 +48,10 @@ What the command line gives is not asked: `bun create @alxia my-app
45
48
  --template react-router` asks nothing. The directory must be empty or not
46
49
  exist yet; `.` writes into the current one, when it is empty, and the next
47
50
  steps then start at `bun dev`. The package name in `package.json` is the
48
- directory's name, lowercased, with `-` for anything npm refuses.
51
+ directory's name, lowercased, with `-` for anything npm refuses, and the
52
+ same name replaces the template's own (`my-api`, `my-app`) in its other
53
+ files, as the README's `docker build -t` and `docker run`: `bun create
54
+ @alxia "Mon Super Projet"` writes `mon-super-projet` in both.
49
55
 
50
56
  `bun create @alxia` is `bunx @alxia/create`: Bun maps `bun create @scope`
51
57
  to the package `@scope/create`, and npm maps `npm create @scope` the same
@@ -53,94 +59,413 @@ way. Any of the three runs the same bin, on Bun.
53
59
 
54
60
  Both templates are files shipped in this package, under
55
61
  `templates/api/` and `templates/react-router/`, and copied as they are:
56
- nothing is downloaded but the dependencies, and only `package.json` is
57
- written again, with the directory's name, alxia's versions and the newest
58
- of the others ([Versions](#versions)). Two files are stored under another
59
- name, since `bun publish` leaves them out of a tarball, and take theirs
60
- back on the copy: `gitignore` is written as `.gitignore`, `_bunfig.toml`
61
- as `bunfig.toml`.
62
+ nothing is downloaded but the dependencies. `package.json` is written
63
+ again, with the directory's name, alxia's versions and the newest of the
64
+ others ([Versions](#versions)); in every other text file, the template's
65
+ own name, as a whole word, becomes the project's. Three files are stored
66
+ under another name and take theirs back on the copy: `gitignore` is
67
+ written as `.gitignore` and `_bunfig.toml` as `bunfig.toml`, since `bun
68
+ publish` leaves those out of a tarball, and `_biome.json` as `biome.json`,
69
+ since alxia's own Biome refuses a second root configuration inside its
70
+ repository ([Lint and format](#lint-and-format)).
62
71
 
63
72
  ## The `api` template
64
73
 
65
74
  ```
66
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
67
78
  ├── src/
68
- │ ├── app.ts the app, and its type
69
- │ ├── app.spec.ts bun test: app.request() and @alxia/client
70
- │ └── 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
71
85
  ├── package.json
72
86
  ├── tsconfig.json
73
- ├── 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
74
90
  ├── .dockerignore
75
- ├── .env.example PORT and API_KEY, for a .env Bun loads
91
+ ├── .env.example PORT and API_KEY, for a .env Bun loads
76
92
  ├── .gitignore
77
93
  └── README.md
78
94
  ```
79
95
 
80
- `src/app.ts` is one route, `POST /todos`, with what a real one needs: a
81
- 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 |
82
189
 
83
190
  ```ts
84
- import { alxia, defineHook } from '@alxia/core';
85
- 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.
211
+
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)).
86
217
 
87
- const Todo = z.object({ id: z.number(), title: z.string(), done: z.boolean() });
88
- const NewTodo = z.object({ title: z.string().min(1) });
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";
89
254
 
90
255
  /** Set API_KEY in the environment: this default is for development. */
91
- export const apiKey = Bun.env['API_KEY'] ?? 'dev-key';
256
+ export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
92
257
 
93
- const requireKey = defineHook(({ request, reply }) =>
94
- request.headers.get('x-api-key') === apiKey
95
- ? undefined
96
- : reply(401, { error: 'unauthorized' as const }),
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) =>
291
+ request.headers.get("x-api-key") === apiKey
292
+ ? next()
293
+ : reply(401, { error: "unauthorized" as const }),
97
294
  );
98
295
 
99
- const todos: z.infer<typeof Todo>[] = [];
100
-
101
- export const app = alxia()
102
- .decorate({ todos })
103
- .post(
104
- '/todos',
105
- [requireKey],
106
- { body: NewTodo, response: { 201: Todo } },
107
- ({ body, todos, reply }) => {
108
- const todo = { id: todos.length + 1, title: body.title, done: false };
109
- todos.push(todo);
110
- return reply.created(todo);
111
- },
112
- );
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);
113
331
 
114
332
  export type App = typeof app;
115
333
  ```
116
334
 
117
- - `requireKey` runs before the body is read: a request without the key is a
118
- 401 whatever its body, and that 401 joins the route's type
119
- ([Hooks on one route](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/hooks.md#hooks-on-one-route)).
120
- - An empty `title` is a 400 naming `title`, before the handler runs.
121
- - `todos` lives in memory: replace the array with your database, given to
122
- the routes the same way, by `decorate`.
335
+ ```ts
336
+ route(operation, ...middlewares, handler)
337
+ ```
123
338
 
124
- `src/app.spec.ts` calls the app in process, no port: `app.request()` with a
125
- JSON body, then `@alxia/client` given the app itself, whose result is typed
126
- 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`
127
361
 
128
362
  ```ts
129
- const api = client(app, { headers: { 'x-api-key': apiKey } });
130
- const created = await api.post('/todos', { body: { title: 'Call it typed' } });
131
- if (created.status !== 201) throw new Error(`got ${created.status}`);
132
- 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
+ });
133
381
  ```
134
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
+
135
455
  The scripts:
136
456
 
137
457
  | script | runs |
138
458
  | --- | --- |
139
459
  | `bun dev` | `bun --watch src/server.ts`: restarted on every change, on `PORT` or 3000 |
140
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 |
141
462
  | `bun run typecheck` | `tsc --noEmit` |
142
463
  | `bun run build` | `bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked`: one file, its dependencies bundled |
143
464
  | `bun start` | `bun dist/server.js`: the build, after `bun run build` |
465
+ | `bun run check` | `biome check --write`: lint, format, sort imports, fixing what it can |
466
+ | `bun run lint`, `bun run format` | `biome lint`, `biome format --write` |
467
+ | `bun run check:ci` | `biome ci`: read-only, for CI |
468
+ | `bun run verify` | `generate --check`, `check:ci`, `typecheck`, then `test` |
144
469
 
145
470
  `start` runs what `build` wrote, as production and the image do:
146
471
 
@@ -162,9 +487,11 @@ keeps out of git and `.dockerignore` out of the image.
162
487
  `tsconfig.json` holds the settings alxia's own packages are checked under:
163
488
  `strict`, and past it `exactOptionalPropertyTypes`,
164
489
  `noUncheckedIndexedAccess`, `noPropertyAccessFromIndexSignature`,
165
- `noUnusedLocals` and the rest. Hence `Bun.env['API_KEY']` and not
166
- `Bun.env.API_KEY`. Loosen what you would rather not keep: alxia's types
167
- compile under each one, and under none.
490
+ `noUnusedLocals` and the rest. Hence `Bun.env["API_KEY"]` and not
491
+ `Bun.env.API_KEY`, and Biome's `useLiteralKeys`, which would ask for the
492
+ second, is off in `biome.json`. Loosen what you would rather not keep:
493
+ alxia's types, and the generated files, compile under each one, and under
494
+ none.
168
495
 
169
496
  ## The `react-router` template
170
497
 
@@ -195,6 +522,19 @@ before `bun install`. The change, against React Router's files:
195
522
  + plugins: [tailwindcss(), reactRouter(), alxia()],
196
523
  ```
197
524
 
525
+ ```diff
526
+ // package.json
527
+ "scripts": {
528
+ + "lint": "biome lint",
529
+ + "format": "biome format --write",
530
+ + "check": "biome check --write",
531
+ + "check:ci": "biome ci",
532
+ + "verify": "bun run check:ci && bun run typecheck && bun run build"
533
+ },
534
+ "devDependencies": {
535
+ + "@biomejs/biome": "2.5.15",
536
+ ```
537
+
198
538
  ```toml
199
539
  # bunfig.toml, new
200
540
  [run]
@@ -204,7 +544,12 @@ bun = true
204
544
  ```
205
545
 
206
546
  The `Dockerfile` is alxia's, in place of React Router's, which builds and
207
- runs on Node ([Docker](#docker)). Every other file is React Router's:
547
+ runs on Node ([Docker](#docker)). `biome.json` and `.vscode/` are new,
548
+ and the README gains a Lint and format section
549
+ ([Lint and format](#lint-and-format)); Biome formatted the scaffold once,
550
+ which changed three of its files: `app/app.css`'s font list wraps
551
+ differently, and `app/routes.ts` and `app/routes/home.tsx` have their
552
+ imports sorted. Every other file is React Router's:
208
553
  `app/`, `public/`, `tsconfig.json`, `react-router.config.ts`, its
209
554
  `README.md` (with Bun's commands where it wrote npm's: `bun install`,
210
555
  `bun dev`, `bun run build`), `.gitignore` and `.dockerignore`. `package.json` takes the directory's name, and its
@@ -218,7 +563,7 @@ files are what `create-react-router` wrote when the template was last
218
563
  generated (React Router 8.4.0 in this release), and the versions are the newest of that major.
219
564
 
220
565
  There is no `app/server.ts`: the plugin's default server serves the pages
221
- 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
222
567
  front of the pages, write it out and edit it:
223
568
 
224
569
  ```sh
@@ -228,6 +573,99 @@ bunx alxia-react-router reveal
228
573
  The [`@alxia/react-router` guide](https://github.com/softistx/alxia/blob/develop/packages/react-router/docs/guide.md)
229
574
  goes from there.
230
575
 
576
+ ## Lint and format
577
+
578
+ Both projects lint and format with [Biome](https://biomejs.dev), in one
579
+ style whichever template wrote them. Their `biome.json` is a root
580
+ configuration of its own, extending nothing:
581
+
582
+ ```json
583
+ {
584
+ "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
585
+ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
586
+ "files": { "includes": ["**", "!!**/build", "!!**/.react-router"] },
587
+ "formatter": { "enabled": true, "indentStyle": "space" },
588
+ "css": { "parser": { "tailwindDirectives": true } },
589
+ "linter": {
590
+ "enabled": true,
591
+ "rules": {
592
+ "preset": "recommended",
593
+ "correctness": { "noEmptyPattern": "off" }
594
+ }
595
+ },
596
+ "assist": {
597
+ "enabled": true,
598
+ "actions": { "source": { "organizeImports": "on" } }
599
+ },
600
+ "overrides": [
601
+ {
602
+ "includes": ["**/app/welcome/**"],
603
+ "linter": { "rules": { "a11y": { "noSvgWithoutTitle": "off" } } }
604
+ }
605
+ ]
606
+ }
607
+ ```
608
+
609
+ That is the `react-router` project's, written here compact. The `api`
610
+ project's skips `dist/` and `src/generated/` instead of `build/` and
611
+ `.react-router/`, has no
612
+ CSS settings and no overrides, and turns `complexity.useLiteralKeys` off
613
+ in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
614
+
615
+ - **The style is Biome's default but for spaces**: two spaces, double
616
+ quotes, 80 columns. React Router's scaffold is written so, and so is
617
+ the `package.json` the command writes: formatting the scaffold once
618
+ changed three of its files, where tabs would change every line. The
619
+ `api` project takes the same style, so the two read alike.
620
+ - **`$schema` is the installed Biome's own schema**, so an editor checks
621
+ the file against the version `bun install` put in `node_modules`,
622
+ whichever the command wrote.
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
625
+ `.gitignore` names, the project in a git repository or not (with no
626
+ `.gitignore` and no git repository, Biome refuses to run:
627
+ [troubleshooting](troubleshooting.md#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)).
628
+ - **Two rules are off in the `react-router` project, for the scaffold's
629
+ own code.** `noEmptyPattern`: `meta({}: Route.MetaArgs)` is React
630
+ Router's idiom for a route module's function that reads none of its
631
+ arguments. `noSvgWithoutTitle`, under `app/welcome/` alone: the welcome
632
+ page's logos, which a project replaces.
633
+ - **`css.parser.tailwindDirectives`** lets Biome read Tailwind v4's
634
+ `@import "tailwindcss"` and `@theme` in `app/app.css`.
635
+
636
+ `@biomejs/biome` is a devDependency pinned exactly, as Biome recommends,
637
+ since a release may format differently. The command moves it to the
638
+ newest patch of the same minor and keeps it exact: a minor may add a
639
+ recommended rule the template was not checked against
640
+ ([Versions](#versions)). To move it later:
641
+
642
+ ```sh
643
+ bun add --dev --exact @biomejs/biome@latest
644
+ bunx biome migrate --write
645
+ ```
646
+
647
+ | script | runs |
648
+ | --- | --- |
649
+ | `bun run check` | `biome check --write`: lint, format and sort imports, fixing what it can |
650
+ | `bun run lint` | `biome lint` |
651
+ | `bun run format` | `biome format --write` |
652
+ | `bun run check:ci` | `biome ci`: changes nothing, and fails on any error |
653
+ | `bun run verify` | `api`: `generate --check`, `check:ci`, `typecheck`, then `test`; `react-router`: `check:ci`, `typecheck`, then `build` |
654
+
655
+ The read-only one is `check:ci`, not `ci`: `bun ci` is Bun's
656
+ `bun install --frozen-lockfile`, and a script named `ci` would only run
657
+ as `bun run ci`. A CI job runs:
658
+
659
+ ```sh
660
+ bun install --frozen-lockfile
661
+ bun run verify
662
+ ```
663
+
664
+ `.vscode/extensions.json` recommends Biome's extension, `biomejs.biome`,
665
+ and `.vscode/settings.json` makes it the default formatter, formatting on
666
+ save. Another editor reads `biome.json` through Biome's own extension for
667
+ it.
668
+
231
669
  ## Docker
232
670
 
233
671
  Each project's `Dockerfile` builds it on Bun's official `oven/bun:1`
@@ -262,6 +700,9 @@ Bun's `--no-install` (not create-alxia's option of the same name), so that a pac
262
700
  startup rather than being fetched from npm, written out so that Bun
263
701
  is the container's process. `src/server.ts` stops the app on `SIGTERM`:
264
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`.
265
706
 
266
707
  ```dockerfile
267
708
  FROM oven/bun:1 AS build
@@ -319,15 +760,18 @@ are in
319
760
  A template ships the versions it was generated with, and React Router's
320
761
  lags behind its own releases. So before installing, the command
321
762
  asks the registry for every dependency's versions, and writes `^` the
322
- newest one alxia accepts:
763
+ newest one alxia accepts, or the version alone for a dependency the
764
+ template pins exactly:
323
765
 
324
766
  | dependency | moved to the newest within |
325
767
  | --- | --- |
326
- | `@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` |
327
769
  | `typescript` | `^6.0.3 \|\| ^7.0.0`, every alxia package's peer range |
328
770
  | `zod` | `^4.2.0`, `@alxia/zod`'s |
329
771
  | `vite` | `^7.0.0 \|\| ^8.0.0`, `@alxia/react-router`'s |
330
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 |
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` |
331
775
  | anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
332
776
 
333
777
  The command prints each move, and each newer major it left out: