@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.
- package/README.md +81 -24
- package/dist/copy.d.ts +11 -3
- package/dist/copy.d.ts.map +1 -1
- package/dist/index.js +51 -23
- package/dist/index.js.map +8 -7
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/packument.d.ts +18 -0
- package/dist/packument.d.ts.map +1 -0
- package/dist/registry.d.ts +29 -10
- package/dist/registry.d.ts.map +1 -1
- package/dist/versions.d.ts +1 -1
- package/dist/versions.d.ts.map +1 -1
- package/docs/README.md +6 -5
- package/docs/guide.md +503 -59
- package/docs/roadmap.md +49 -4
- package/docs/troubleshooting.md +249 -4
- package/package.json +5 -4
- package/templates/api/.vscode/extensions.json +3 -0
- package/templates/api/.vscode/settings.json +8 -0
- package/templates/api/README.md +78 -6
- package/templates/api/_biome.json +32 -0
- package/templates/api/openapi-codegen.config.ts +11 -0
- package/templates/api/openapi.yaml +116 -0
- package/templates/api/package.json +27 -19
- package/templates/api/src/app.spec.ts +57 -38
- package/templates/api/src/app.ts +5 -30
- package/templates/api/src/context.ts +19 -0
- package/templates/api/src/generated/alxia.ts +61 -0
- package/templates/api/src/generated/operations.ts +133 -0
- package/templates/api/src/generated/paths.ts +170 -0
- package/templates/api/src/generated/types.ts +170 -0
- package/templates/api/src/generated/zod.ts +31 -0
- package/templates/api/src/routes/todos.ts +31 -0
- package/templates/api/src/server.ts +12 -12
- package/templates/api/tsconfig.json +23 -23
- package/templates/react-router/.vscode/extensions.json +3 -0
- package/templates/react-router/.vscode/settings.json +8 -0
- package/templates/react-router/README.md +27 -0
- package/templates/react-router/_biome.json +49 -0
- package/templates/react-router/app/app.css +3 -2
- package/templates/react-router/app/routes/home.tsx +1 -1
- package/templates/react-router/app/routes.ts +1 -1
- package/templates/react-router/package.json +7 -1
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
|
-
|
|
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,53 @@ 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
|
-
###
|
|
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
|
|
64
|
+
|
|
65
|
+
- **Both projects lint and format with Biome.** Each has a `biome.json`
|
|
66
|
+
of its own (recommended rules, spaces and double quotes, imports
|
|
67
|
+
sorted, the build output skipped), `@biomejs/biome` pinned exactly,
|
|
68
|
+
the scripts `lint`, `format`, `check`, `check:ci` and `verify`, and
|
|
69
|
+
`.vscode/` recommending Biome's extension. A new project passes
|
|
70
|
+
`bun run check:ci` with no finding.
|
|
71
|
+
- **The project's name in its README.** The name given to the command,
|
|
72
|
+
normalised, replaces the template's own, as a whole word, in every text
|
|
73
|
+
file, as the README's
|
|
74
|
+
`docker build -t` and `docker run`.
|
|
75
|
+
|
|
76
|
+
### 0.1.4
|
|
32
77
|
|
|
33
78
|
- **The images run on Alpine.** Every `Dockerfile`'s final stage is
|
|
34
79
|
`oven/bun:1-alpine`, the build stages staying on `oven/bun:1`: each
|
|
@@ -65,8 +110,8 @@ Nothing scheduled yet.
|
|
|
65
110
|
template ships inside `@alxia/create`, with alxia's layer, and is copied
|
|
66
111
|
as it is: no `create-react-router` runs, and no change in it can make the
|
|
67
112
|
command refuse.
|
|
68
|
-
- **alxia's packages resolve at creation too.** `@alxia/core
|
|
69
|
-
|
|
113
|
+
- **alxia's packages resolve at creation too.** `@alxia/core`
|
|
114
|
+
and `@alxia/react-router` move to the newest version
|
|
70
115
|
within the ranges `@alxia/create` was published with. Right after a
|
|
71
116
|
release, while the registry does not serve that version yet, the newest
|
|
72
117
|
of the same minor is written, so `bun install` no longer fails with
|
package/docs/troubleshooting.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# Troubleshooting
|
|
2
2
|
|
|
3
3
|
Each entry is headed by the text you see: what `create-alxia` printed, what
|
|
4
|
-
Bun or the shell printed before it ran,
|
|
5
|
-
nothing — the symptom.
|
|
4
|
+
Bun or the shell printed before it ran, what a new project's own commands
|
|
5
|
+
print, or — for a trap that prints nothing — the symptom.
|
|
6
6
|
|
|
7
7
|
**Before it runs**
|
|
8
8
|
|
|
@@ -32,6 +32,7 @@ nothing — the symptom.
|
|
|
32
32
|
- [`zod: no release within ^4.2.0; kept ^4.2.0`](#zod-no-release-within-420-kept-420)
|
|
33
33
|
- [`@alxia/core: the registry has no release within ^0.3.1 yet; wrote ^0.3.0, the newest of ~0.3.0`](#alxiacore-the-registry-has-no-release-within-031-yet-wrote-030-the-newest-of-030)
|
|
34
34
|
- [`create-alxia: bun install failed; the files are written.`](#create-alxia-bun-install-failed-the-files-are-written)
|
|
35
|
+
- [`warn: incorrect peer dependency "typescript@7.0.2"`](#warn-incorrect-peer-dependency-typescript702)
|
|
35
36
|
|
|
36
37
|
**After**
|
|
37
38
|
|
|
@@ -41,6 +42,20 @@ nothing — the symptom.
|
|
|
41
42
|
- [`error: … is linked against glibc (DT_NEEDED libm.so.6), but this Bun build uses musl.`](#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)
|
|
42
43
|
- [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
|
|
43
44
|
|
|
45
|
+
**The `api` project's spec**
|
|
46
|
+
|
|
47
|
+
- [`openapi.yaml → src/generated: out of date, run nxgt-openapi generate`](#openapiyaml--srcgenerated-out-of-date-run-nxgt-openapi-generate)
|
|
48
|
+
- [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
|
|
49
|
+
- [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
|
|
50
|
+
- [`ResponseValidationError: POST /todos: the 201 reply does not match its schema`](#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)
|
|
51
|
+
- [``cookie parameter `session` is not supported [unsupported_parameter]``](#cookie-parameter-session-is-not-supported-unsupported_parameter)
|
|
52
|
+
|
|
53
|
+
**Biome**
|
|
54
|
+
|
|
55
|
+
- [`bun ci` installs, and checks nothing](#bun-ci-installs-and-checks-nothing)
|
|
56
|
+
- [`× Found a nested root configuration, but there's already a root configuration.`](#-found-a-nested-root-configuration-but-theres-already-a-root-configuration)
|
|
57
|
+
- [`× Biome couldn't find an ignore file in the following folder: …`](#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)
|
|
58
|
+
|
|
44
59
|
## Before it runs
|
|
45
60
|
|
|
46
61
|
### `error: GET https://registry.npmjs.org/@alxia%2fcreate - 404`
|
|
@@ -221,7 +236,7 @@ hand after the project is created.
|
|
|
221
236
|
|
|
222
237
|
**When:** a notice, not an error, right after an alxia release: the
|
|
223
238
|
registry lists `@alxia/create`'s new version but not yet the
|
|
224
|
-
`@alxia/core` (or `@alxia/
|
|
239
|
+
`@alxia/core` (or `@alxia/react-router`) published beside
|
|
225
240
|
it. npm can take a few minutes to serve a version everywhere.
|
|
226
241
|
|
|
227
242
|
**Why:** a project written with `^0.3.1` would fail its `bun install` with
|
|
@@ -240,6 +255,23 @@ the next steps.
|
|
|
240
255
|
**Fix:** what its output says, then `cd my-app && bun install`. The
|
|
241
256
|
project is complete; only `node_modules` is missing.
|
|
242
257
|
|
|
258
|
+
### `warn: incorrect peer dependency "typescript@7.0.2"`
|
|
259
|
+
|
|
260
|
+
**When:** `bun install` in a new `api` project, the one `bun create @alxia`
|
|
261
|
+
runs included, prints it once and finishes.
|
|
262
|
+
|
|
263
|
+
**Why:** the project gets the newest TypeScript alxia's packages accept,
|
|
264
|
+
`^6.0.3 || ^7.0.0`, and `@nxgt/openapi-codegen` 0.6.0, the generator the
|
|
265
|
+
template pins, declares `typescript` `^6.0.3` alone. The generator never
|
|
266
|
+
loads TypeScript, so nothing fails: `bun run generate`, `typecheck`, `test`
|
|
267
|
+
and `build` all pass.
|
|
268
|
+
|
|
269
|
+
**Fix:** none is needed. To silence it, hold the project to TypeScript 6:
|
|
270
|
+
|
|
271
|
+
```sh
|
|
272
|
+
bun add -d typescript@^6.0.3
|
|
273
|
+
```
|
|
274
|
+
|
|
243
275
|
## After
|
|
244
276
|
|
|
245
277
|
### `error: lockfile had changes, but lockfile is frozen`
|
|
@@ -368,7 +400,220 @@ new `@alxia/create`.
|
|
|
368
400
|
|
|
369
401
|
**Fix:** `bunx @alxia/create@latest` for the newest `@alxia/create`, and in
|
|
370
402
|
an existing project
|
|
371
|
-
`bun add @alxia/core@latest @alxia/
|
|
403
|
+
`bun add @alxia/core@latest && bun add --dev @alxia/openapi@latest` (`api`) or
|
|
372
404
|
`bun add @alxia/core@latest @alxia/react-router@latest` (`react-router`), reading
|
|
373
405
|
[`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
|
|
374
406
|
for what a minor changed.
|
|
407
|
+
|
|
408
|
+
## The `api` project's spec
|
|
409
|
+
|
|
410
|
+
### `openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
411
|
+
|
|
412
|
+
`bun run verify` stops at its first step, with the stale files listed
|
|
413
|
+
below the line:
|
|
414
|
+
|
|
415
|
+
```
|
|
416
|
+
openapi.yaml → src/generated: out of date, run nxgt-openapi generate
|
|
417
|
+
src/generated/types.ts
|
|
418
|
+
src/generated/operations.ts
|
|
419
|
+
src/generated/paths.ts
|
|
420
|
+
src/generated/alxia.ts
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
**When:** `bun run generate --check`, alone or as `verify`'s first step,
|
|
424
|
+
after `openapi.yaml` changed and `bun run generate` was not run, or after
|
|
425
|
+
a file of `src/generated/` was edited by hand. It writes nothing and exits 1.
|
|
426
|
+
|
|
427
|
+
**Why:** `src/generated/` is committed, so that nothing is generated at
|
|
428
|
+
install or build ([the `api` template](guide.md#srcgenerated)); the check
|
|
429
|
+
is what keeps it equal to `openapi.yaml`.
|
|
430
|
+
|
|
431
|
+
**Fix:** generate, then commit the files with the spec:
|
|
432
|
+
|
|
433
|
+
```sh
|
|
434
|
+
bun run generate
|
|
435
|
+
git add openapi.yaml src/generated
|
|
436
|
+
```
|
|
437
|
+
|
|
438
|
+
A change made by hand in `src/generated/` is lost: make it in
|
|
439
|
+
`openapi.yaml`.
|
|
440
|
+
|
|
441
|
+
### `src/generated/` changes after moving `@nxgt/openapi-codegen`
|
|
442
|
+
|
|
443
|
+
**Symptom:** `bun run verify` fails with
|
|
444
|
+
`openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
445
|
+
right after `bun add --dev --exact @nxgt/openapi-codegen@…`, with no
|
|
446
|
+
change to `openapi.yaml`.
|
|
447
|
+
|
|
448
|
+
**When:** the generator moved to another minor, `0.6.x` to `0.7.0`. A new
|
|
449
|
+
project never hits it: the command keeps the template's version
|
|
450
|
+
([Versions](guide.md#versions)).
|
|
451
|
+
|
|
452
|
+
**Why:** the generated files are the output of one release of the
|
|
453
|
+
generator, and another minor may write them differently: an option's
|
|
454
|
+
default, a new file, another form for a schema. That is why the template
|
|
455
|
+
pins it exactly.
|
|
456
|
+
|
|
457
|
+
**Fix:** generate again, then read what changed before committing it:
|
|
458
|
+
|
|
459
|
+
```sh
|
|
460
|
+
bun run generate
|
|
461
|
+
git diff src/generated
|
|
462
|
+
bun run verify
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
The diff is what the new release writes differently; `bun run verify`
|
|
466
|
+
tells whether the app still compiles and passes against it. To stay
|
|
467
|
+
where you were, pin the previous version again:
|
|
468
|
+
`bun add --dev --exact @nxgt/openapi-codegen@0.6.0`.
|
|
469
|
+
|
|
470
|
+
### `TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`
|
|
471
|
+
|
|
472
|
+
With several, `2 operations have no route: …`; a route outside the spec
|
|
473
|
+
reads `1 route has no operation: …`, after a `;` when both happen.
|
|
474
|
+
|
|
475
|
+
**When:** `bun test`, in `src/app.spec.ts`, after an operation was added
|
|
476
|
+
to `openapi.yaml` and `bun run generate` run, before `src/routes/todos.ts` routes
|
|
477
|
+
it. The path is in alxia's form, `/todos/:id`, and the `operationId` is
|
|
478
|
+
in parentheses.
|
|
479
|
+
|
|
480
|
+
**Why:** `matchesSpec(app, operations)` checks both ways: every operation
|
|
481
|
+
of `src/generated/alxia.ts` has a route of its method and path, and every
|
|
482
|
+
route has an operation.
|
|
483
|
+
|
|
484
|
+
**Fix:** bind the operation in `src/routes/todos.ts`
|
|
485
|
+
([Adding an operation](guide.md#adding-an-operation)):
|
|
486
|
+
|
|
487
|
+
```ts
|
|
488
|
+
.route(operations.deleteTodo, requireKey, ({ params, todos, reply }) => {
|
|
489
|
+
const index = todos.findIndex(({ id }) => id === params.id);
|
|
490
|
+
if (index === -1) return reply.notFound({ error: "not_found" as const });
|
|
491
|
+
todos.splice(index, 1);
|
|
492
|
+
return reply.noContent();
|
|
493
|
+
});
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
For a route deliberately outside the spec, a health check say, see
|
|
497
|
+
[`@alxia/openapi`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/troubleshooting.md#typeerror-matchesspec--routes-have-no-operation-).
|
|
498
|
+
|
|
499
|
+
### `ResponseValidationError: POST /todos: the 201 reply does not match its schema`
|
|
500
|
+
|
|
501
|
+
The client gets `500 {"error":"internal"}`, and the server prints the
|
|
502
|
+
error, with the field that broke the schema after the colon:
|
|
503
|
+
|
|
504
|
+
```text
|
|
505
|
+
ResponseValidationError: POST /todos: the 201 reply does not match its schema: title: Invalid input: expected string, received undefined
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
The method, path and status are the route's and the reply's.
|
|
509
|
+
|
|
510
|
+
**When:** the handler's reply does not match what `openapi.yaml` declares
|
|
511
|
+
for its status. A middleware's own reply, such as `requireKey`'s 401, is
|
|
512
|
+
not checked, unless `responds(operation)` stands before it. The types refuse most of
|
|
513
|
+
these, so it comes from data the types do not see (a database row,
|
|
514
|
+
`JSON.parse`, `any`, a cast), or from `openapi.yaml` changed and
|
|
515
|
+
generated while the code still sends the old shape.
|
|
516
|
+
|
|
517
|
+
**Why:** a route bound with `route(operation, …)` checks the handler's
|
|
518
|
+
reply against the operation's responses, so a client generated from the same
|
|
519
|
+
spec never reads a body it was not told about. A body the spec refuses is
|
|
520
|
+
not sent.
|
|
521
|
+
|
|
522
|
+
**Fix:** send what the spec declares, or change the spec, generate, and
|
|
523
|
+
send that:
|
|
524
|
+
|
|
525
|
+
```ts
|
|
526
|
+
reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id, title, done }
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
The other forms of the error, and how to turn the check off, are in
|
|
530
|
+
[`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#responsevalidationerror--the-200-reply-does-not-match-its-schema).
|
|
531
|
+
|
|
532
|
+
### ``cookie parameter `session` is not supported [unsupported_parameter]``
|
|
533
|
+
|
|
534
|
+
```text
|
|
535
|
+
error openapi.yaml#/paths/~1todos/get/parameters/0/in: cookie parameter `session` is not supported [unsupported_parameter]
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
**When:** `bun run generate`, once `openapi.yaml` declares a parameter
|
|
539
|
+
`in: cookie`. It writes nothing and exits 1.
|
|
540
|
+
|
|
541
|
+
**Why:** `@nxgt/openapi-codegen` 0.6.0 does not generate cookie
|
|
542
|
+
parameters, and refuses the whole spec rather than leave one out.
|
|
543
|
+
|
|
544
|
+
**Fix:** take the parameter out of `openapi.yaml`, and read the cookie in
|
|
545
|
+
the app: in a middleware, or with a `validate({ cookies })` placed among
|
|
546
|
+
the route's middlewares:
|
|
547
|
+
|
|
548
|
+
```ts
|
|
549
|
+
import { alxia, validate } from "@alxia/core";
|
|
550
|
+
import { z } from "zod";
|
|
551
|
+
import { operations } from "./generated/alxia";
|
|
552
|
+
|
|
553
|
+
export const app = alxia().route(
|
|
554
|
+
operations.listTodos,
|
|
555
|
+
validate({ cookies: z.object({ session: z.string() }) }),
|
|
556
|
+
({ cookies, reply }) => reply.ok(todosOf(cookies.session)),
|
|
557
|
+
);
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
## Biome
|
|
561
|
+
|
|
562
|
+
### `bun ci` installs, and checks nothing
|
|
563
|
+
|
|
564
|
+
**Symptom:** `bun ci` in a project prints an install, `bun install
|
|
565
|
+
v1.4.2`, and no Biome output; a CI step meant to lint passes whatever the
|
|
566
|
+
code.
|
|
567
|
+
|
|
568
|
+
**Why:** `bun ci` is Bun's own command, `bun install --frozen-lockfile`,
|
|
569
|
+
and a command Bun knows wins over a script. The projects name their
|
|
570
|
+
read-only check `check:ci` for that reason
|
|
571
|
+
([Lint and format](guide.md#lint-and-format)).
|
|
572
|
+
|
|
573
|
+
**Fix:** run the script by `bun run`:
|
|
574
|
+
|
|
575
|
+
```sh
|
|
576
|
+
bun run check:ci # biome ci alone
|
|
577
|
+
bun run verify # biome ci, typecheck, then test or build
|
|
578
|
+
```
|
|
579
|
+
|
|
580
|
+
### `× Found a nested root configuration, but there's already a root configuration.`
|
|
581
|
+
|
|
582
|
+
**When:** Biome runs from a folder above the project that has its own
|
|
583
|
+
`biome.json`: the project was created inside a monorepo, and `biome ci`
|
|
584
|
+
runs from the monorepo's root.
|
|
585
|
+
|
|
586
|
+
**Why:** the project's `biome.json` is a root configuration, so that it
|
|
587
|
+
works on its own. Biome takes one root per run; a configuration below it
|
|
588
|
+
must say it is nested.
|
|
589
|
+
|
|
590
|
+
**Fix:** to keep the monorepo's settings and add the project's, make the
|
|
591
|
+
project's nested, at the top of its `biome.json`:
|
|
592
|
+
|
|
593
|
+
```json
|
|
594
|
+
{
|
|
595
|
+
"root": false,
|
|
596
|
+
"extends": "//",
|
|
597
|
+
"$schema": "./node_modules/@biomejs/biome/configuration_schema.json"
|
|
598
|
+
}
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
and keep the rest of the file. `"extends": "//"` takes the root's
|
|
602
|
+
settings, which the project's own override. To use the monorepo's
|
|
603
|
+
settings alone, delete the project's `biome.json` and its
|
|
604
|
+
`@biomejs/biome`.
|
|
605
|
+
|
|
606
|
+
### `× Biome couldn't find an ignore file in the following folder: …`
|
|
607
|
+
|
|
608
|
+
**When:** `bun run check:ci`, `check`, `lint` or `format` in a project
|
|
609
|
+
with no `.gitignore`, deleted or renamed, and outside any git repository.
|
|
610
|
+
Inside one, Biome reads git's ignore rules and runs.
|
|
611
|
+
|
|
612
|
+
**Why:** `biome.json` sets `vcs.useIgnoreFile`, which skips what
|
|
613
|
+
`.gitignore` names. Inside a git repository Biome falls back on git's
|
|
614
|
+
own ignore rules; with no `.gitignore` and no repository, it refuses to
|
|
615
|
+
run rather than skip nothing.
|
|
616
|
+
|
|
617
|
+
**Fix:** put a `.gitignore` back, even an empty one, or set
|
|
618
|
+
`"useIgnoreFile": false` in `biome.json`'s `vcs`: `files.includes` still
|
|
619
|
+
skips the build output.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alxia/create",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.6",
|
|
4
4
|
"description": "Start an alxia app: `bun create @alxia` writes an API with Zod, or React Router's official template served by alxia",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -39,9 +39,10 @@
|
|
|
39
39
|
]
|
|
40
40
|
},
|
|
41
41
|
"devDependencies": {
|
|
42
|
-
"@alxia/
|
|
43
|
-
"@alxia/
|
|
44
|
-
"@alxia/react-router": "^0.
|
|
42
|
+
"@alxia/core": "^0.4.0",
|
|
43
|
+
"@alxia/openapi": "^0.4.0",
|
|
44
|
+
"@alxia/react-router": "^0.5.0",
|
|
45
|
+
"@nxgt/openapi-codegen": "0.6.0",
|
|
45
46
|
"@types/bun": "^1.4.2",
|
|
46
47
|
"zod": "^4.6.5"
|
|
47
48
|
}
|
package/templates/api/README.md
CHANGED
|
@@ -1,12 +1,56 @@
|
|
|
1
1
|
# An alxia API
|
|
2
2
|
|
|
3
3
|
An [alxia](https://github.com/softistx/alxia) app with
|
|
4
|
-
[Zod](https://zod.dev), made with `bun create @alxia`.
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
[Zod](https://zod.dev), made with `bun create @alxia`. It is OpenAPI spec
|
|
5
|
+
first: `openapi.yaml` is the contract, the routes are bound to the
|
|
6
|
+
operations generated from it, and a client is generated from the same file.
|
|
7
|
+
|
|
8
|
+
- `openapi.yaml`: the API's operations, `GET /todos`, `POST /todos` and
|
|
9
|
+
`GET /todos/{id}`, their bodies, parameters and replies.
|
|
10
|
+
- `src/generated/`: what `bun run generate` writes from it, with
|
|
11
|
+
[`@nxgt/openapi-codegen`](https://www.npmjs.com/package/@nxgt/openapi-codegen)
|
|
12
|
+
(`openapi-codegen.config.ts`). `alxia.ts` holds each operation as the
|
|
13
|
+
data `app.route()` takes. Never edit it: change `openapi.yaml`, then
|
|
14
|
+
generate.
|
|
15
|
+
- `src/context.ts`: the base, what every route reads (the todos), and
|
|
16
|
+
its `Register` declaration: a route file reads that context with no
|
|
17
|
+
import of the app. Register the base, never the app, which mounts the
|
|
18
|
+
route files and would be typed by itself.
|
|
19
|
+
- `src/routes/todos.ts`: the routes, `defineRoutes()`, each bound to an
|
|
20
|
+
operation. `route(operations.createTodo, requireKey, handler)` runs its
|
|
21
|
+
middlewares in order: `requireKey`, made with `defineMiddleware`,
|
|
22
|
+
answers 401 without the `x-api-key` header; the operation's body is
|
|
23
|
+
validated just before the handler, and the handler's reply checked
|
|
24
|
+
against the operation's responses.
|
|
25
|
+
- `src/app.ts`: the app, `base.plugin(todoRoutes)`. Mounting the routes on
|
|
26
|
+
an app that does not give the base's context is a compile error.
|
|
8
27
|
- `src/server.ts`: listens on `PORT`, 3000 by default.
|
|
9
|
-
- `src/app.spec.ts`: `app.request()
|
|
28
|
+
- `src/app.spec.ts`: `app.request()`, no port, and `matchesSpec` from
|
|
29
|
+
[`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every
|
|
30
|
+
operation of `openapi.yaml` has its route, and no route is outside it.
|
|
31
|
+
- `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
|
|
32
|
+
|
|
33
|
+
## The contract first
|
|
34
|
+
|
|
35
|
+
A new route starts in `openapi.yaml`:
|
|
36
|
+
|
|
37
|
+
1. Add the operation, with an `operationId`: `deleteTodo`, say.
|
|
38
|
+
2. `bun run generate`: `src/generated/alxia.ts` now exports
|
|
39
|
+
`operations.deleteTodo`.
|
|
40
|
+
3. Bind it in `src/routes/todos.ts`, with the middlewares it needs:
|
|
41
|
+
`.route(operations.deleteTodo, requireKey, ({ params, reply }) => …)`.
|
|
42
|
+
The handler's `params`, `body` and `reply` are typed by the spec.
|
|
43
|
+
4. `bun test`: `matchesSpec` fails while an operation has no route.
|
|
44
|
+
|
|
45
|
+
`src/generated/` is committed, so the project builds with no generation
|
|
46
|
+
step, in Docker too. `bun run verify` runs `bun run generate --check`
|
|
47
|
+
first: it fails when `src/generated/` is not what `openapi.yaml` gives.
|
|
48
|
+
`@nxgt/openapi-codegen` is pinned exactly, since another release may
|
|
49
|
+
write the files differently: after moving it, run `bun run generate`.
|
|
50
|
+
|
|
51
|
+
A client in another project is generated from the same `openapi.yaml`,
|
|
52
|
+
with the generator of its choice: `@nxgt/openapi-codegen` writes types,
|
|
53
|
+
Zod validators and the operations a typed client reads.
|
|
10
54
|
|
|
11
55
|
## Environment
|
|
12
56
|
|
|
@@ -33,8 +77,36 @@ curl -X POST localhost:3000/todos \
|
|
|
33
77
|
## Test
|
|
34
78
|
|
|
35
79
|
```sh
|
|
36
|
-
bun test # src/app.spec.ts: in process,
|
|
80
|
+
bun test # src/app.spec.ts: in process, no port
|
|
37
81
|
bun run typecheck
|
|
82
|
+
bun run generate # src/generated/, from openapi.yaml
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Lint and format
|
|
86
|
+
|
|
87
|
+
[Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
|
|
88
|
+
sets it: Biome's recommended rules, spaces, double quotes, imports
|
|
89
|
+
sorted. What the build writes, `dist/`, is skipped, and so is what
|
|
90
|
+
`bun run generate` writes, `src/generated/`.
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
bun run check # lint, format and sort imports, fixing what it can
|
|
94
|
+
bun run lint # lint only
|
|
95
|
+
bun run format # format only, in place
|
|
96
|
+
bun run check:ci # what CI runs: changes nothing, fails on an error
|
|
97
|
+
bun run verify # generate --check, check:ci, typecheck, then test
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
`bun run check:ci`, not `bun ci`: `bun ci` is Bun's frozen-lockfile
|
|
101
|
+
install. In VS Code, `.vscode/` recommends Biome's extension and formats
|
|
102
|
+
on save with it.
|
|
103
|
+
|
|
104
|
+
`@biomejs/biome` is pinned exactly, since a release of Biome may format
|
|
105
|
+
differently. To move it:
|
|
106
|
+
|
|
107
|
+
```sh
|
|
108
|
+
bun add --dev --exact @biomejs/biome@latest
|
|
109
|
+
bunx biome migrate --write
|
|
38
110
|
```
|
|
39
111
|
|
|
40
112
|
## Build
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
|
|
3
|
+
"vcs": {
|
|
4
|
+
"enabled": true,
|
|
5
|
+
"clientKind": "git",
|
|
6
|
+
"useIgnoreFile": true
|
|
7
|
+
},
|
|
8
|
+
"files": {
|
|
9
|
+
"includes": ["**", "!!**/dist", "!!**/src/generated"]
|
|
10
|
+
},
|
|
11
|
+
"formatter": {
|
|
12
|
+
"enabled": true,
|
|
13
|
+
"indentStyle": "space"
|
|
14
|
+
},
|
|
15
|
+
"linter": {
|
|
16
|
+
"enabled": true,
|
|
17
|
+
"rules": {
|
|
18
|
+
"preset": "recommended",
|
|
19
|
+
"complexity": {
|
|
20
|
+
"useLiteralKeys": "off"
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
},
|
|
24
|
+
"assist": {
|
|
25
|
+
"enabled": true,
|
|
26
|
+
"actions": {
|
|
27
|
+
"source": {
|
|
28
|
+
"organizeImports": "on"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { defineConfig } from "@nxgt/openapi-codegen";
|
|
2
|
+
|
|
3
|
+
// `bun run generate` writes src/generated/ from openapi.yaml; `alxia` adds
|
|
4
|
+
// alxia.ts, the operations src/routes/todos.ts binds. The 400 is alxia's own,
|
|
5
|
+
// declared in openapi.yaml, not the one validationErrors would add.
|
|
6
|
+
export default defineConfig({
|
|
7
|
+
input: "openapi.yaml",
|
|
8
|
+
output: "src/generated",
|
|
9
|
+
alxia: true,
|
|
10
|
+
validationErrors: false,
|
|
11
|
+
});
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# The API's contract: the routes of src/routes/todos.ts are bound to the operations
|
|
2
|
+
# generated from it. Edit it first, then run `bun run generate`.
|
|
3
|
+
openapi: 3.1.0
|
|
4
|
+
info:
|
|
5
|
+
title: my-api
|
|
6
|
+
version: 0.1.0
|
|
7
|
+
paths:
|
|
8
|
+
/todos:
|
|
9
|
+
get:
|
|
10
|
+
operationId: listTodos
|
|
11
|
+
summary: Every todo
|
|
12
|
+
responses:
|
|
13
|
+
"200":
|
|
14
|
+
description: The todos, oldest first
|
|
15
|
+
content:
|
|
16
|
+
application/json:
|
|
17
|
+
schema:
|
|
18
|
+
type: array
|
|
19
|
+
items: { $ref: "#/components/schemas/Todo" }
|
|
20
|
+
post:
|
|
21
|
+
operationId: createTodo
|
|
22
|
+
summary: Add a todo
|
|
23
|
+
security:
|
|
24
|
+
- apiKey: []
|
|
25
|
+
requestBody:
|
|
26
|
+
required: true
|
|
27
|
+
content:
|
|
28
|
+
application/json:
|
|
29
|
+
schema: { $ref: "#/components/schemas/NewTodo" }
|
|
30
|
+
responses:
|
|
31
|
+
"201":
|
|
32
|
+
description: The todo, created
|
|
33
|
+
content:
|
|
34
|
+
application/json:
|
|
35
|
+
schema: { $ref: "#/components/schemas/Todo" }
|
|
36
|
+
"400":
|
|
37
|
+
$ref: "#/components/responses/ValidationError"
|
|
38
|
+
"401":
|
|
39
|
+
description: No x-api-key header, or not the key
|
|
40
|
+
content:
|
|
41
|
+
application/json:
|
|
42
|
+
schema: { $ref: "#/components/schemas/Unauthorized" }
|
|
43
|
+
/todos/{id}:
|
|
44
|
+
get:
|
|
45
|
+
operationId: getTodo
|
|
46
|
+
summary: One todo
|
|
47
|
+
parameters:
|
|
48
|
+
- name: id
|
|
49
|
+
in: path
|
|
50
|
+
required: true
|
|
51
|
+
schema: { type: integer, minimum: 1 }
|
|
52
|
+
responses:
|
|
53
|
+
"200":
|
|
54
|
+
description: The todo
|
|
55
|
+
content:
|
|
56
|
+
application/json:
|
|
57
|
+
schema: { $ref: "#/components/schemas/Todo" }
|
|
58
|
+
"400":
|
|
59
|
+
$ref: "#/components/responses/ValidationError"
|
|
60
|
+
"404":
|
|
61
|
+
description: No todo has this id
|
|
62
|
+
content:
|
|
63
|
+
application/json:
|
|
64
|
+
schema: { $ref: "#/components/schemas/NotFound" }
|
|
65
|
+
components:
|
|
66
|
+
securitySchemes:
|
|
67
|
+
apiKey: { type: apiKey, in: header, name: x-api-key }
|
|
68
|
+
responses:
|
|
69
|
+
ValidationError:
|
|
70
|
+
description: alxia's own 400, for a request the schemas refuse
|
|
71
|
+
content:
|
|
72
|
+
application/json:
|
|
73
|
+
schema: { $ref: "#/components/schemas/ValidationError" }
|
|
74
|
+
schemas:
|
|
75
|
+
Todo:
|
|
76
|
+
type: object
|
|
77
|
+
required: [id, title, done]
|
|
78
|
+
properties:
|
|
79
|
+
id: { type: integer }
|
|
80
|
+
title: { type: string }
|
|
81
|
+
done: { type: boolean }
|
|
82
|
+
NewTodo:
|
|
83
|
+
type: object
|
|
84
|
+
required: [title]
|
|
85
|
+
properties:
|
|
86
|
+
title: { type: string, minLength: 1 }
|
|
87
|
+
Unauthorized:
|
|
88
|
+
type: object
|
|
89
|
+
required: [error]
|
|
90
|
+
properties:
|
|
91
|
+
error: { type: string, enum: [unauthorized] }
|
|
92
|
+
NotFound:
|
|
93
|
+
type: object
|
|
94
|
+
required: [error]
|
|
95
|
+
properties:
|
|
96
|
+
error: { type: string, enum: [not_found] }
|
|
97
|
+
ValidationError:
|
|
98
|
+
type: object
|
|
99
|
+
required: [error, issues]
|
|
100
|
+
properties:
|
|
101
|
+
error: { type: string, enum: [validation] }
|
|
102
|
+
issues:
|
|
103
|
+
type: array
|
|
104
|
+
items:
|
|
105
|
+
type: object
|
|
106
|
+
required: [target, path, code, message]
|
|
107
|
+
properties:
|
|
108
|
+
target:
|
|
109
|
+
type: string
|
|
110
|
+
enum: [params, query, headers, cookies, body]
|
|
111
|
+
path:
|
|
112
|
+
type: array
|
|
113
|
+
items:
|
|
114
|
+
anyOf: [{ type: string }, { type: integer }]
|
|
115
|
+
code: { type: string }
|
|
116
|
+
message: { type: string }
|