@alxia/create 0.1.5 → 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 +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 +371 -53
- package/docs/roadmap.md +36 -4
- package/docs/troubleshooting.md +182 -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 +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/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,399 @@ 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.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";
|
|
98
254
|
|
|
99
255
|
/** Set API_KEY in the environment: this default is for development. */
|
|
100
256
|
export const apiKey = Bun.env["API_KEY"] ?? "dev-key";
|
|
101
257
|
|
|
102
|
-
const
|
|
258
|
+
const todos: Todo[] = [];
|
|
259
|
+
|
|
260
|
+
// The base: what every route reads, decorated or derived here. It is
|
|
261
|
+
// registered below, so a route file reads it with no import of the app.
|
|
262
|
+
export const base = alxia().decorate({ todos });
|
|
263
|
+
|
|
264
|
+
// Register the base, never the app: the app mounts the route files, whose
|
|
265
|
+
// type reads this, and would then be typed by itself.
|
|
266
|
+
declare module "@alxia/core" {
|
|
267
|
+
interface Register {
|
|
268
|
+
context: typeof base;
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
The base is what every route reads: here the todos, decorated. Register it
|
|
274
|
+
once, and each route file reads that context with no import of the app
|
|
275
|
+
([Register and AppContext](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/types.md#register-and-appcontext)).
|
|
276
|
+
Register `base`, never `app`: `app` mounts the route files, whose type
|
|
277
|
+
reads `Register`, so it would be typed by itself, `TS7022`. A `derive`
|
|
278
|
+
for a `user` from a session goes here too, and every route then reads
|
|
279
|
+
`user` typed.
|
|
280
|
+
|
|
281
|
+
### `src/routes/todos.ts`
|
|
282
|
+
|
|
283
|
+
```ts
|
|
284
|
+
import { defineMiddleware, defineRoutes } from "@alxia/core";
|
|
285
|
+
import { apiKey } from "../context";
|
|
286
|
+
import { operations } from "../generated/alxia";
|
|
287
|
+
|
|
288
|
+
// A middleware of the routes it is given to: it answers 401 without the key,
|
|
289
|
+
// before the body is read. openapi.yaml declares that 401.
|
|
290
|
+
const requireKey = defineMiddleware(({ request, reply }, next) =>
|
|
103
291
|
request.headers.get("x-api-key") === apiKey
|
|
104
|
-
?
|
|
292
|
+
? next()
|
|
105
293
|
: reply(401, { error: "unauthorized" as const }),
|
|
106
294
|
);
|
|
107
295
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
)
|
|
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);
|
|
122
331
|
|
|
123
332
|
export type App = typeof app;
|
|
124
333
|
```
|
|
125
334
|
|
|
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`.
|
|
335
|
+
```ts
|
|
336
|
+
route(operation, ...middlewares, handler)
|
|
337
|
+
```
|
|
132
338
|
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
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`
|
|
136
361
|
|
|
137
362
|
```ts
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
+
});
|
|
142
381
|
```
|
|
143
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
|
+
|
|
144
455
|
The scripts:
|
|
145
456
|
|
|
146
457
|
| script | runs |
|
|
147
458
|
| --- | --- |
|
|
148
459
|
| `bun dev` | `bun --watch src/server.ts`: restarted on every change, on `PORT` or 3000 |
|
|
149
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 |
|
|
150
462
|
| `bun run typecheck` | `tsc --noEmit` |
|
|
151
463
|
| `bun run build` | `bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked`: one file, its dependencies bundled |
|
|
152
464
|
| `bun start` | `bun dist/server.js`: the build, after `bun run build` |
|
|
153
465
|
| `bun run check` | `biome check --write`: lint, format, sort imports, fixing what it can |
|
|
154
466
|
| `bun run lint`, `bun run format` | `biome lint`, `biome format --write` |
|
|
155
467
|
| `bun run check:ci` | `biome ci`: read-only, for CI |
|
|
156
|
-
| `bun run verify` | `check:ci`, `typecheck`, then `test` |
|
|
468
|
+
| `bun run verify` | `generate --check`, `check:ci`, `typecheck`, then `test` |
|
|
157
469
|
|
|
158
470
|
`start` runs what `build` wrote, as production and the image do:
|
|
159
471
|
|
|
@@ -178,7 +490,8 @@ keeps out of git and `.dockerignore` out of the image.
|
|
|
178
490
|
`noUnusedLocals` and the rest. Hence `Bun.env["API_KEY"]` and not
|
|
179
491
|
`Bun.env.API_KEY`, and Biome's `useLiteralKeys`, which would ask for the
|
|
180
492
|
second, is off in `biome.json`. Loosen what you would rather not keep:
|
|
181
|
-
alxia's types compile under each one, and under
|
|
493
|
+
alxia's types, and the generated files, compile under each one, and under
|
|
494
|
+
none.
|
|
182
495
|
|
|
183
496
|
## The `react-router` template
|
|
184
497
|
|
|
@@ -250,7 +563,7 @@ files are what `create-react-router` wrote when the template was last
|
|
|
250
563
|
generated (React Router 8.4.0 in this release), and the versions are the newest of that major.
|
|
251
564
|
|
|
252
565
|
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
|
|
566
|
+
in `bun dev` and from the build. To put alxia's middlewares or `/api` routes in
|
|
254
567
|
front of the pages, write it out and edit it:
|
|
255
568
|
|
|
256
569
|
```sh
|
|
@@ -294,7 +607,8 @@ configuration of its own, extending nothing:
|
|
|
294
607
|
```
|
|
295
608
|
|
|
296
609
|
That is the `react-router` project's, written here compact. The `api`
|
|
297
|
-
project's skips `dist/` instead of `build/` and
|
|
610
|
+
project's skips `dist/` and `src/generated/` instead of `build/` and
|
|
611
|
+
`.react-router/`, has no
|
|
298
612
|
CSS settings and no overrides, and turns `complexity.useLiteralKeys` off
|
|
299
613
|
in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
|
|
300
614
|
|
|
@@ -306,8 +620,8 @@ in place of `noEmptyPattern` ([the `api` template](#the-api-template)).
|
|
|
306
620
|
- **`$schema` is the installed Biome's own schema**, so an editor checks
|
|
307
621
|
the file against the version `bun install` put in `node_modules`,
|
|
308
622
|
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
|
|
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
|
|
311
625
|
`.gitignore` names, the project in a git repository or not (with no
|
|
312
626
|
`.gitignore` and no git repository, Biome refuses to run:
|
|
313
627
|
[troubleshooting](troubleshooting.md#-biome-couldnt-find-an-ignore-file-in-the-following-folder-)).
|
|
@@ -336,7 +650,7 @@ bunx biome migrate --write
|
|
|
336
650
|
| `bun run lint` | `biome lint` |
|
|
337
651
|
| `bun run format` | `biome format --write` |
|
|
338
652
|
| `bun run check:ci` | `biome ci`: changes nothing, and fails on any error |
|
|
339
|
-
| `bun run verify` | `check:ci`, `typecheck`, then `test`
|
|
653
|
+
| `bun run verify` | `api`: `generate --check`, `check:ci`, `typecheck`, then `test`; `react-router`: `check:ci`, `typecheck`, then `build` |
|
|
340
654
|
|
|
341
655
|
The read-only one is `check:ci`, not `ci`: `bun ci` is Bun's
|
|
342
656
|
`bun install --frozen-lockfile`, and a script named `ci` would only run
|
|
@@ -386,6 +700,9 @@ Bun's `--no-install` (not create-alxia's option of the same name), so that a pac
|
|
|
386
700
|
startup rather than being fetched from npm, written out so that Bun
|
|
387
701
|
is the container's process. `src/server.ts` stops the app on `SIGTERM`:
|
|
388
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`.
|
|
389
706
|
|
|
390
707
|
```dockerfile
|
|
391
708
|
FROM oven/bun:1 AS build
|
|
@@ -448,12 +765,13 @@ template pins exactly:
|
|
|
448
765
|
|
|
449
766
|
| dependency | moved to the newest within |
|
|
450
767
|
| --- | --- |
|
|
451
|
-
| `@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` |
|
|
452
769
|
| `typescript` | `^6.0.3 \|\| ^7.0.0`, every alxia package's peer range |
|
|
453
770
|
| `zod` | `^4.2.0`, `@alxia/zod`'s |
|
|
454
771
|
| `vite` | `^7.0.0 \|\| ^8.0.0`, `@alxia/react-router`'s |
|
|
455
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 |
|
|
456
|
-
| `@biomejs/biome` | its own minor, from the exact version the template pins (`~2.5.15`): written exactly, `2.5.16`, never
|
|
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` |
|
|
457
775
|
| anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
|
|
458
776
|
|
|
459
777
|
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
|