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