@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/guide.md
CHANGED
|
@@ -1,11 +1,14 @@
|
|
|
1
1
|
# Guide
|
|
2
2
|
|
|
3
|
-
How `bun create @alxia` asks, what each template writes,
|
|
4
|
-
|
|
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
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
name,
|
|
60
|
-
back on the copy: `gitignore` is
|
|
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
|
-
│ ├──
|
|
69
|
-
│ ├──
|
|
70
|
-
│
|
|
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
|
-
├──
|
|
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
|
|
91
|
+
├── .env.example PORT and API_KEY, for a .env Bun loads
|
|
76
92
|
├── .gitignore
|
|
77
93
|
└── README.md
|
|
78
94
|
```
|
|
79
95
|
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
85
|
-
|
|
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
|
-
|
|
88
|
-
|
|
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[
|
|
256
|
+
export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
|
|
92
257
|
|
|
93
|
-
const
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
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
|
-
|
|
125
|
-
|
|
126
|
-
by
|
|
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
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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[
|
|
166
|
-
`Bun.env.API_KEY
|
|
167
|
-
|
|
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)).
|
|
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
|
|
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/
|
|
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:
|