@alxia/create 0.1.6 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/README.md +80 -25
  2. package/dist/args.d.ts +3 -1
  3. package/dist/args.d.ts.map +1 -1
  4. package/dist/index.js +19 -9
  5. package/dist/index.js.map +7 -7
  6. package/dist/main.d.ts +1 -1
  7. package/dist/main.d.ts.map +1 -1
  8. package/dist/registry.d.ts +2 -0
  9. package/dist/registry.d.ts.map +1 -1
  10. package/dist/versions.d.ts +5 -2
  11. package/dist/versions.d.ts.map +1 -1
  12. package/docs/README.md +16 -6
  13. package/docs/guide.md +438 -56
  14. package/docs/roadmap.md +24 -0
  15. package/docs/troubleshooting.md +146 -50
  16. package/package.json +16 -6
  17. package/templates/api/.env.example +9 -1
  18. package/templates/api/README.md +40 -12
  19. package/templates/api/openapi.yaml +13 -9
  20. package/templates/api/package.json +6 -4
  21. package/templates/api/src/app.spec.ts +42 -28
  22. package/templates/api/src/app.ts +13 -3
  23. package/templates/api/src/context.ts +3 -4
  24. package/templates/api/src/env.ts +20 -0
  25. package/templates/api/src/generated/alxia.ts +15 -5
  26. package/templates/api/src/generated/operations.ts +4 -4
  27. package/templates/api/src/generated/paths.ts +6 -6
  28. package/templates/api/src/generated/types.ts +14 -10
  29. package/templates/api/src/generated/zod.ts +6 -2
  30. package/templates/api/src/routes/todos.ts +2 -2
  31. package/templates/api/src/server.ts +8 -16
  32. package/templates/graphql/.dockerignore +6 -0
  33. package/templates/graphql/.env.example +3 -0
  34. package/templates/graphql/.vscode/extensions.json +3 -0
  35. package/templates/graphql/.vscode/settings.json +8 -0
  36. package/templates/graphql/Dockerfile +26 -0
  37. package/templates/graphql/README.md +171 -0
  38. package/templates/graphql/_biome.json +32 -0
  39. package/templates/graphql/codegen.ts +22 -0
  40. package/templates/graphql/gitignore +6 -0
  41. package/templates/graphql/package.json +34 -0
  42. package/templates/graphql/schema.graphql +26 -0
  43. package/templates/graphql/src/app.spec.ts +119 -0
  44. package/templates/graphql/src/app.ts +14 -0
  45. package/templates/graphql/src/context.ts +24 -0
  46. package/templates/graphql/src/env.ts +8 -0
  47. package/templates/graphql/src/generated/resolvers.ts +180 -0
  48. package/templates/graphql/src/graphql.d.ts +6 -0
  49. package/templates/graphql/src/resolvers.ts +42 -0
  50. package/templates/graphql/src/schema.ts +6 -0
  51. package/templates/graphql/src/server.ts +10 -0
  52. package/templates/graphql/src/store.ts +25 -0
  53. package/templates/graphql/tsconfig.json +25 -0
  54. package/templates/minimal/.dockerignore +6 -0
  55. package/templates/minimal/.vscode/extensions.json +3 -0
  56. package/templates/minimal/.vscode/settings.json +8 -0
  57. package/templates/minimal/Dockerfile +26 -0
  58. package/templates/minimal/README.md +107 -0
  59. package/templates/minimal/_biome.json +32 -0
  60. package/templates/minimal/gitignore +6 -0
  61. package/templates/minimal/package.json +25 -0
  62. package/templates/minimal/src/index.spec.ts +12 -0
  63. package/templates/minimal/src/index.ts +17 -0
  64. package/templates/minimal/tsconfig.json +25 -0
  65. package/templates/react-router/package.json +2 -2
package/docs/roadmap.md CHANGED
@@ -7,11 +7,32 @@ number on it. Every release, with each change it made, is in
7
7
 
8
8
  ## Now
9
9
 
10
+ - **Two templates: `minimal` and `graphql`.** `minimal` is one file, one
11
+ dependency and a test, the template to try alxia with, and what the
12
+ prompt offers first. `graphql` is a GraphQL Yoga API served by
13
+ `@alxia/graphql`, schema first: `schema.graphql` is the contract, GraphQL
14
+ Code Generator types the resolvers (committed, checked by
15
+ `generate --check`), `viewer` is typed in every resolver, and
16
+ `noteAdded` is a subscription over server-sent events.
17
+ - **The `api` template reads its environment with `defineEnv`.**
18
+ `src/env.ts`, from `@alxia/env`, checks `PORT` and `API_KEY` (a secret)
19
+ once, before the server listens; `src/context.ts` no longer exports
20
+ `apiKey`.
10
21
  - **The `api` project split across files.** `src/context.ts` holds the
11
22
  base the routes read and registers it with `@alxia/core`'s `Register`;
12
23
  `src/routes/todos.ts` binds the operations with `defineRoutes()`,
13
24
  reading that context with no import of the app; `src/app.ts` mounts
14
25
  them, `base.plugin(todoRoutes)`.
26
+ - **Production-safe defaults.** Every `dev` script sets
27
+ `NODE_ENV=development`, the only mode alxia's dev helps run in; the
28
+ `api` project's `API_KEY` is required outside development and test; the
29
+ `api` and `graphql` projects mount `health()`, the `api` project answers
30
+ alxia's own errors as problems and serves `/docs` from the bundled
31
+ `openapi.yaml`; no template installs signal handlers of its own, as
32
+ `listen` drains and exits on `SIGINT` and `SIGTERM`.
33
+ - **The `api` template's tests use a typed client.** `src/app.spec.ts` calls
34
+ the app through openapi-fetch over the generated `paths.ts`, with
35
+ `app.fetch` as its `fetch`: in process, typed by `openapi.yaml`.
15
36
 
16
37
  ## Next
17
38
 
@@ -37,6 +58,9 @@ Nothing scheduled yet.
37
58
  code would describe whatever the code does.
38
59
  - **A runtime dependency.** The prompts are Bun's `prompt()`, the registry
39
60
  is read with `fetch`, versions are compared with `Bun.semver`.
61
+ - **A code-first GraphQL template (Pothos, Nexus).** The `graphql`
62
+ template is schema first, as the `api` one is spec first: the schema file
63
+ is the contract, and the resolvers are typed from it.
40
64
 
41
65
  ## Shipped
42
66
 
@@ -11,8 +11,8 @@ print, or — for a trap that prints nothing — the symptom.
11
11
 
12
12
  **The command line**
13
13
 
14
- - [`create-alxia: unknown template vue: use api or react-router.`](#create-alxia-unknown-template-vue-use-api-or-react-router)
15
- - [`create-alxia: --template needs a template: api or react-router.`](#create-alxia---template-needs-a-template-api-or-react-router)
14
+ - [`create-alxia: unknown template vue: use minimal, api, graphql or react-router.`](#create-alxia-unknown-template-vue-use-minimal-api-graphql-or-react-router)
15
+ - [`create-alxia: --template needs a template: minimal, api, graphql or react-router.`](#create-alxia---template-needs-a-template-minimal-api-graphql-or-react-router)
16
16
  - [`create-alxia: unknown option --yes.`](#create-alxia-unknown-option---yes)
17
17
  - [`create-alxia: one directory only, given a and b.`](#create-alxia-one-directory-only-given-a-and-b)
18
18
  - [`create-alxia: no directory given, and no terminal to ask in.`](#create-alxia-no-directory-given-and-no-terminal-to-ask-in)
@@ -32,7 +32,6 @@ print, or — for a trap that prints nothing — the symptom.
32
32
  - [`zod: no release within ^4.2.0; kept ^4.2.0`](#zod-no-release-within-420-kept-420)
33
33
  - [`@alxia/core: the registry has no release within ^0.3.1 yet; wrote ^0.3.0, the newest of ~0.3.0`](#alxiacore-the-registry-has-no-release-within-031-yet-wrote-030-the-newest-of-030)
34
34
  - [`create-alxia: bun install failed; the files are written.`](#create-alxia-bun-install-failed-the-files-are-written)
35
- - [`warn: incorrect peer dependency "typescript@7.0.2"`](#warn-incorrect-peer-dependency-typescript702)
36
35
 
37
36
  **After**
38
37
 
@@ -48,7 +47,17 @@ print, or — for a trap that prints nothing — the symptom.
48
47
  - [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
49
48
  - [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
50
49
  - [`ResponseValidationError: POST /todos: the 201 reply does not match its schema`](#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)
51
- - [``cookie parameter `session` is not supported [unsupported_parameter]``](#cookie-parameter-session-is-not-supported-unsupported_parameter)
50
+
51
+ **The `graphql` project's schema**
52
+
53
+ - [`The following stale files were detected: src/generated/resolvers.ts`](#the-following-stale-files-were-detected-srcgeneratedresolversts)
54
+ - [`src/generated/` changes after moving `@graphql-codegen/*`](#srcgenerated-changes-after-moving-graphql-codegen)
55
+ - [`error: Could not resolve: "../schema.graphql"`, or `TS2307` for it](#error-could-not-resolve-schemagraphql-or-ts2307-for-it)
56
+ - [`Sign in to add a note`](#sign-in-to-add-a-note)
57
+
58
+ **The environment**
59
+
60
+ - [`EnvError: The environment is invalid:`](#enverror-the-environment-is-invalid)
52
61
 
53
62
  **Biome**
54
63
 
@@ -87,21 +96,21 @@ then run `bun create @alxia`.
87
96
 
88
97
  ## The command line
89
98
 
90
- ### `create-alxia: unknown template vue: use api or react-router.`
99
+ ### `create-alxia: unknown template vue: use minimal, api, graphql or react-router.`
91
100
 
92
101
  **When:** `--template` names a template the command does not have, or the
93
102
  prompt was answered with one.
94
103
 
95
- **Fix:** `--template api` or `--template react-router`. `bun create @alxia
96
- --help` lists them.
104
+ **Fix:** `--template minimal`, `--template api`, `--template graphql` or
105
+ `--template react-router`. `bun create @alxia --help` lists them.
97
106
 
98
- ### `create-alxia: --template needs a template: api or react-router.`
107
+ ### `create-alxia: --template needs a template: minimal, api, graphql or react-router.`
99
108
 
100
109
  **When:** `--template` is the last argument, or `--template=` is empty.
101
110
  The message names the option as typed: `-t needs a template` for `-t`,
102
111
  `--template= needs a template` for the empty form.
103
112
 
104
- **Fix:** name one: `bun create @alxia my-app --template api`.
113
+ **Fix:** name one: `bun create @alxia my-app --template minimal`.
105
114
 
106
115
  ### `create-alxia: unknown option --yes.`
107
116
 
@@ -132,7 +141,8 @@ terminal: a script, CI, a pipe.
132
141
 
133
142
  **When:** a directory but no `--template`, with no terminal.
134
143
 
135
- **Fix:** add `--template api` or `--template react-router`.
144
+ **Fix:** add `--template minimal`, `--template api`, `--template graphql` or
145
+ `--template react-router`.
136
146
 
137
147
  ### `create-alxia: cancelled, nothing written.`
138
148
 
@@ -255,23 +265,6 @@ the next steps.
255
265
  **Fix:** what its output says, then `cd my-app && bun install`. The
256
266
  project is complete; only `node_modules` is missing.
257
267
 
258
- ### `warn: incorrect peer dependency "typescript@7.0.2"`
259
-
260
- **When:** `bun install` in a new `api` project, the one `bun create @alxia`
261
- runs included, prints it once and finishes.
262
-
263
- **Why:** the project gets the newest TypeScript alxia's packages accept,
264
- `^6.0.3 || ^7.0.0`, and `@nxgt/openapi-codegen` 0.6.0, the generator the
265
- template pins, declares `typescript` `^6.0.3` alone. The generator never
266
- loads TypeScript, so nothing fails: `bun run generate`, `typecheck`, `test`
267
- and `build` all pass.
268
-
269
- **Fix:** none is needed. To silence it, hold the project to TypeScript 6:
270
-
271
- ```sh
272
- bun add -d typescript@^6.0.3
273
- ```
274
-
275
268
  ## After
276
269
 
277
270
  ### `error: lockfile had changes, but lockfile is frozen`
@@ -293,7 +286,7 @@ traps of the `react-router` image, a write refused to the `bun` user among them,
293
286
  **When:** `bun start` in an `api` project that was never built, or whose
294
287
  `dist/` was deleted.
295
288
 
296
- **Why:** `start` runs the build, `bun dist/server.js`, as the image does;
289
+ **Why:** `start` runs the build, `NODE_ENV=production bun dist/server.js`, as the image does;
297
290
  it no longer runs `src/server.ts`. `bun dev` runs the sources.
298
291
 
299
292
  **Fix:** build first:
@@ -445,7 +438,7 @@ A change made by hand in `src/generated/` is lost: make it in
445
438
  right after `bun add --dev --exact @nxgt/openapi-codegen@…`, with no
446
439
  change to `openapi.yaml`.
447
440
 
448
- **When:** the generator moved to another minor, `0.6.x` to `0.7.0`. A new
441
+ **When:** the generator moved to another minor, `0.7.x` to `0.8.0`. A new
449
442
  project never hits it: the command keeps the template's version
450
443
  ([Versions](guide.md#versions)).
451
444
 
@@ -464,8 +457,8 @@ bun run verify
464
457
 
465
458
  The diff is what the new release writes differently; `bun run verify`
466
459
  tells whether the app still compiles and passes against it. To stay
467
- where you were, pin the previous version again:
468
- `bun add --dev --exact @nxgt/openapi-codegen@0.6.0`.
460
+ where you were, pin the previous version again, `0.7.0` after a move to `0.8.0`:
461
+ `bun add --dev --exact @nxgt/openapi-codegen@0.7.0`.
469
462
 
470
463
  ### `TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`
471
464
 
@@ -529,34 +522,137 @@ reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id
529
522
  The other forms of the error, and how to turn the check off, are in
530
523
  [`@alxia/core`'s troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/core/docs/troubleshooting.md#responsevalidationerror--the-200-reply-does-not-match-its-schema).
531
524
 
532
- ### ``cookie parameter `session` is not supported [unsupported_parameter]``
525
+ ## The `graphql` project's schema
533
526
 
534
- ```text
535
- error openapi.yaml#/paths/~1todos/get/parameters/0/in: cookie parameter `session` is not supported [unsupported_parameter]
527
+ ### `The following stale files were detected: src/generated/resolvers.ts`
528
+
529
+ `bun run verify` stops at its first step, with the stale file listed
530
+ below the line:
531
+
532
+ ```
533
+ The following stale files were detected:
534
+ - src/generated/resolvers.ts
535
+ ```
536
+
537
+ **When:** `bun run generate --check`, alone or as `verify`'s first step,
538
+ after `schema.graphql` or `codegen.ts` changed and `bun run generate` was
539
+ not run, or after `src/generated/resolvers.ts` was edited by hand. It
540
+ writes nothing and exits 1.
541
+
542
+ **Why:** `src/generated/` is committed, so that nothing is generated at
543
+ install or build; the check is what keeps it equal to `schema.graphql`.
544
+
545
+ **Fix:** generate, then commit the file with the schema:
546
+
547
+ ```sh
548
+ bun run generate
549
+ git add schema.graphql src/generated
550
+ ```
551
+
552
+ A change made by hand in `src/generated/` is lost: make it in
553
+ `schema.graphql`, or in `codegen.ts`.
554
+
555
+ ### `src/generated/` changes after moving `@graphql-codegen/*`
556
+
557
+ **Symptom:** `bun run verify` fails with
558
+ `The following stale files were detected` right after
559
+ `bun add --dev --exact @graphql-codegen/cli@…`, or one of the two
560
+ plugins, with no change to `schema.graphql`.
561
+
562
+ **When:** a generator moved to another version. A new project never hits
563
+ it: the command keeps the template's versions, `@graphql-codegen/cli` 7.4.3,
564
+ `typescript` 6.1.0 and `typescript-resolvers` 6.1.0
565
+ ([Versions](guide.md#versions)).
566
+
567
+ **Why:** `src/generated/resolvers.ts` is the output of one release of the
568
+ generator and its plugins, and another may write it differently. That is
569
+ why the template pins the three exactly.
570
+
571
+ **Fix:** generate again, read what changed before committing it, and verify:
572
+
573
+ ```sh
574
+ bun run generate
575
+ git diff src/generated
576
+ bun run verify
536
577
  ```
537
578
 
538
- **When:** `bun run generate`, once `openapi.yaml` declares a parameter
539
- `in: cookie`. It writes nothing and exits 1.
579
+ To stay where you were, pin the previous versions again:
580
+ `bun add --dev --exact @graphql-codegen/cli@7.4.3`.
581
+
582
+ ### `error: Could not resolve: "../schema.graphql"`, or `TS2307` for it
540
583
 
541
- **Why:** `@nxgt/openapi-codegen` 0.6.0 does not generate cookie
542
- parameters, and refuses the whole spec rather than leave one out.
584
+ **When:** `bun run build` prints `error: Could not resolve: "../schema.graphql"`, or `bun run typecheck` prints `error TS2307: Cannot find module '../schema.graphql' or its corresponding type declarations`: neither can resolve the import
585
+ of `schema.graphql` that `src/schema.ts` makes, or the file is not where
586
+ `../schema.graphql` says: the project's root.
543
587
 
544
- **Fix:** take the parameter out of `openapi.yaml`, and read the cookie in
545
- the app: in a middleware, or with a `validate({ cookies })` placed among
546
- the route's middlewares:
588
+ **Why:** the import is `import typeDefs from "../schema.graphql" with { type: "text" }`:
589
+ Bun reads the file as text, and `bun run build` bundles it into
590
+ `dist/server.js`. TypeScript knows the module through `src/graphql.d.ts`,
591
+ which declares `*.graphql`, and the text attribute is what makes Bun read
592
+ it as a string and not as a module.
593
+
594
+ **Fix:** keep `schema.graphql` at the root, `src/graphql.d.ts` in
595
+ `src/` (the `tsconfig.json` includes `src`), and the import as written,
596
+ attribute included:
547
597
 
548
598
  ```ts
549
- import { alxia, validate } from "@alxia/core";
550
- import { z } from "zod";
551
- import { operations } from "./generated/alxia";
552
-
553
- export const app = alxia().route(
554
- operations.listTodos,
555
- validate({ cookies: z.object({ session: z.string() }) }),
556
- ({ cookies, reply }) => reply.ok(todosOf(cookies.session)),
557
- );
599
+ import typeDefs from "../schema.graphql" with { type: "text" };
558
600
  ```
559
601
 
602
+ ### `Sign in to add a note`
603
+
604
+ **When:** a new project's `addNote` mutation answers an error with the
605
+ message `Sign in to add a note` and the code `UNAUTHENTICATED`. It is the
606
+ template working, not failing.
607
+
608
+ **Why:** `viewerOf` reads `Authorization: Bearer <token>` and gives each
609
+ resolver a `viewer`, `null` without a known token; `addNote` throws a
610
+ `GraphQLError` when it is `null`. The development token is `ada-token`.
611
+
612
+ **Fix:** send it:
613
+
614
+ ```sh
615
+ curl localhost:3000/graphql -H 'content-type: application/json' \
616
+ -H 'authorization: Bearer ada-token' \
617
+ -d '{"query":"mutation { addNote(text: \"Hello\") { id } }"}'
618
+ ```
619
+
620
+ Tokens live in `src/store.ts`: replace them with a session lookup or a
621
+ JWT check outside development.
622
+
623
+ ## The environment
624
+
625
+ ### `EnvError: The environment is invalid:`
626
+
627
+ `bun dev`, `bun start` or `bun test` stops before it listens, in the `api`
628
+ and `graphql` projects, with every variable that failed:
629
+
630
+ ```
631
+ EnvError: The environment is invalid:
632
+ PORT: Invalid input: expected number, received NaN; expected number
633
+ API_KEY: Invalid input: expected string, received undefined; expected string
634
+ ```
635
+
636
+ **Why:** `src/env.ts` calls `defineEnv` from `@alxia/env`, which checks each
637
+ variable with its own Zod schema once, when the module is first imported,
638
+ from `Bun.env` (the shell's, and the `.env` Bun loads). A value that fails
639
+ stops the process, as the first request that read it would have failed
640
+ later. A secret's value is never printed: `API_KEY` shows as `***`.
641
+
642
+ **Fix:** set the variables the message names, in the shell or in `.env`
643
+ (`cp .env.example .env`), or remove the wrong line:
644
+
645
+ ```sh
646
+ PORT=3000 bun dev
647
+ ```
648
+
649
+ A variable the schema gives a default (`PORT`, the `api` project's
650
+ `API_DOCS`) is fine unset. The `api` project's `API_KEY` defaults to
651
+ `dev-key` under `NODE_ENV=development` (`bun dev`) and `test` (`bun test`)
652
+ alone: `bun start`, the image and any other `NODE_ENV` require it, so set
653
+ it there (`docker run -e API_KEY=…`). `bun test` sets `NODE_ENV=test`: a
654
+ `.env` that sets `NODE_ENV` to another value overrides it.
655
+
560
656
  ## Biome
561
657
 
562
658
  ### `bun ci` installs, and checks nothing
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@alxia/create",
3
- "version": "0.1.6",
4
- "description": "Start an alxia app: `bun create @alxia` writes an API with Zod, or React Router's official template served by alxia",
3
+ "version": "0.2.0",
4
+ "description": "Start an alxia app: `bun create @alxia` writes a minimal API, a spec-first one, a GraphQL one, or React Router's official template served by alxia",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
@@ -10,7 +10,9 @@
10
10
  "files": [
11
11
  "dist",
12
12
  "docs",
13
+ "templates/minimal",
13
14
  "templates/api",
15
+ "templates/graphql",
14
16
  "templates/react-router",
15
17
  "README.md",
16
18
  "package.json",
@@ -39,11 +41,19 @@
39
41
  ]
40
42
  },
41
43
  "devDependencies": {
42
- "@alxia/core": "^0.4.0",
43
- "@alxia/openapi": "^0.4.0",
44
- "@alxia/react-router": "^0.5.0",
45
- "@nxgt/openapi-codegen": "0.6.0",
44
+ "@alxia/core": "^0.5.0",
45
+ "@alxia/env": "^0.2.0",
46
+ "@alxia/graphql": "^0.3.0",
47
+ "@alxia/openapi": "^0.5.0",
48
+ "@alxia/react-router": "^0.6.0",
49
+ "@graphql-codegen/cli": "7.4.3",
50
+ "@graphql-codegen/typescript": "6.1.0",
51
+ "@graphql-codegen/typescript-resolvers": "6.1.0",
52
+ "@nxgt/openapi-codegen": "0.7.0",
46
53
  "@types/bun": "^1.4.2",
54
+ "graphql": "^16.11.0 || ^17.0.0",
55
+ "graphql-yoga": "^5.16.0",
56
+ "openapi-fetch": "^0.17.0",
47
57
  "zod": "^4.6.5"
48
58
  }
49
59
  }
@@ -1,3 +1,11 @@
1
1
  # Copy to .env, which Bun loads on every command: bun dev, bun test, bun start.
2
+ # string, required; default dev-key in development and test alone, secret
3
+ # Left out: a .env holding it would give `bun start` the development key too.
4
+ # An empty value is refused, even under bun dev: give it one, or leave it out.
5
+ # API_KEY=change-me
6
+
7
+ # boolean, optional, default true in development, false elsewhere: the API reference at /docs
8
+ # API_DOCS=true
9
+
10
+ # number, optional, default 3000
2
11
  PORT=3000
3
- API_KEY=dev-key
@@ -12,8 +12,10 @@ operations generated from it, and a client is generated from the same file.
12
12
  (`openapi-codegen.config.ts`). `alxia.ts` holds each operation as the
13
13
  data `app.route()` takes. Never edit it: change `openapi.yaml`, then
14
14
  generate.
15
- - `src/context.ts`: the base, what every route reads (the todos), and
16
- its `Register` declaration: a route file reads that context with no
15
+ - `src/context.ts`: the base, what every route reads (the todos), alxia's
16
+ own errors as RFC 9457 problems (`alxia({ errors: "problem" })`: a 400
17
+ the schemas refuse is `application/problem+json`, as `openapi.yaml`
18
+ declares it), and its `Register` declaration: a route file reads that context with no
17
19
  import of the app. Register the base, never the app, which mounts the
18
20
  route files and would be typed by itself.
19
21
  - `src/routes/todos.ts`: the routes, `defineRoutes()`, each bound to an
@@ -22,10 +24,23 @@ operations generated from it, and a client is generated from the same file.
22
24
  answers 401 without the `x-api-key` header; the operation's body is
23
25
  validated just before the handler, and the handler's reply checked
24
26
  against the operation's responses.
25
- - `src/app.ts`: the app, `base.plugin(todoRoutes)`. Mounting the routes on
26
- an app that does not give the base's context is a compile error.
27
- - `src/server.ts`: listens on `PORT`, 3000 by default.
28
- - `src/app.spec.ts`: `app.request()`, no port, and `matchesSpec` from
27
+ - `src/app.ts`: the app: the base, `health()`'s probes (`GET /health`,
28
+ liveness, and `GET /ready`, readiness), `apiDocs` from `@alxia/openapi`
29
+ (the API reference at `/docs`, `openapi.yaml` at `/docs/openapi.yaml`),
30
+ then `todoRoutes`. `openapi.yaml` is imported, so the build bundles it.
31
+ Mounting the routes on an app that does not give the base's context is a
32
+ compile error.
33
+ - `src/env.ts`: the environment, `defineEnv` from
34
+ [`@alxia/env`](https://www.npmjs.com/package/@alxia/env): `PORT`,
35
+ `API_KEY` and `API_DOCS`, each checked by its own Zod schema once, when
36
+ the module is first imported. A missing or malformed one stops the
37
+ process with every issue, before it listens, and `API_KEY` prints as
38
+ `***`.
39
+ - `src/server.ts`: listens on `env.PORT`, 3000 by default, and shuts down
40
+ gracefully on `SIGINT` and `SIGTERM`, which `listen` handles.
41
+ - `src/app.spec.ts`: a typed client (openapi-fetch over `generated/paths.ts`,
42
+ its `fetch` being `app.fetch`: no server, no port), one `app.request()`
43
+ test, and `matchesSpec` from
29
44
  [`@alxia/openapi`](https://www.npmjs.com/package/@alxia/openapi): every
30
45
  operation of `openapi.yaml` has its route, and no route is outside it.
31
46
  - `biome.json`: Biome's lint and format settings ([Lint and format](#lint-and-format)).
@@ -54,9 +69,15 @@ Zod validators and the operations a typed client reads.
54
69
 
55
70
  ## Environment
56
71
 
57
- Bun loads `.env` on every command. Copy `.env.example` to `.env` to set
58
- `PORT` and `API_KEY`. Outside development, set `API_KEY`: its default,
59
- `dev-key`, is for development only.
72
+ Bun loads `.env` on every command, and `src/env.ts` checks what it finds.
73
+ Copy `.env.example` to `.env` to set `PORT`, `API_KEY` and `API_DOCS`.
74
+ `API_KEY` defaults to `dev-key` under `NODE_ENV=development` (`bun dev`)
75
+ and `test` (`bun test`) alone: anywhere else, `bun start` and the image
76
+ included, it is required, and the app does not start without it.
77
+ `API_DOCS` serves the API reference at `/docs`: on in development, off
78
+ elsewhere unless set to `true`. The document is public wherever it is on.
79
+ A variable that fails its schema stops the app with every issue named,
80
+ never the secret's value.
60
81
 
61
82
  ```sh
62
83
  cp .env.example .env
@@ -65,13 +86,19 @@ cp .env.example .env
65
86
  ## Develop
66
87
 
67
88
  ```sh
68
- bun dev # http://localhost:3000, restarted on every change
89
+ bun dev # NODE_ENV=development: http://localhost:3000, restarted on every change
69
90
  ```
70
91
 
92
+ `bun dev` sets `NODE_ENV=development`, alxia's dev switch: `listen`
93
+ prints the route table, a 404 hints at the closest route, a 500 shows its
94
+ error, and `/docs` is on. Under any other `NODE_ENV`, none of them is.
95
+
71
96
  ```sh
72
97
  curl -X POST localhost:3000/todos \
73
98
  -H 'content-type: application/json' -H 'x-api-key: dev-key' \
74
99
  -d '{"title":"Write a route"}'
100
+ curl localhost:3000/health # {"status":"ok"}
101
+ open http://localhost:3000/docs
75
102
  ```
76
103
 
77
104
  ## Test
@@ -117,7 +144,7 @@ runs it: what production and the image run.
117
144
 
118
145
  ```sh
119
146
  bun run build # dist/server.js and dist/server.js.map
120
- bun start # bun dist/server.js
147
+ bun start # NODE_ENV=production bun dist/server.js
121
148
  ```
122
149
 
123
150
  `bun start` before any build fails with `Module not found
@@ -139,13 +166,14 @@ that `bun install` wrote (commit it), and runs `bun run build`. The image
139
166
  holds `dist/` alone, no `node_modules` and no `src/`, and runs
140
167
  `bun --no-install dist/server.js` as its non-root `bun` user: a package
141
168
  missing from the bundle fails at startup instead of being fetched from
142
- npm. `src/server.ts` stops the app on `SIGTERM`, so `docker stop` is
169
+ npm. `listen` drains the app and exits on `SIGTERM`, so `docker stop` is
143
170
  immediate. A native addon built for glibc alone does not load on
144
171
  Alpine: put the final stage back on `oven/bun:1`.
145
172
 
146
173
  ```sh
147
174
  docker build -t my-api .
148
175
  docker run --rm -p 3000:3000 -e API_KEY=change-me my-api
176
+ # with the API reference at /docs: -e API_DOCS=true
149
177
  ```
150
178
 
151
179
  Next: [Getting started](https://github.com/softistx/alxia/blob/develop/packages/core/docs/guide/getting-started.md)
@@ -34,7 +34,7 @@ paths:
34
34
  application/json:
35
35
  schema: { $ref: "#/components/schemas/Todo" }
36
36
  "400":
37
- $ref: "#/components/responses/ValidationError"
37
+ $ref: "#/components/responses/ValidationProblem"
38
38
  "401":
39
39
  description: No x-api-key header, or not the key
40
40
  content:
@@ -56,7 +56,7 @@ paths:
56
56
  application/json:
57
57
  schema: { $ref: "#/components/schemas/Todo" }
58
58
  "400":
59
- $ref: "#/components/responses/ValidationError"
59
+ $ref: "#/components/responses/ValidationProblem"
60
60
  "404":
61
61
  description: No todo has this id
62
62
  content:
@@ -66,11 +66,11 @@ components:
66
66
  securitySchemes:
67
67
  apiKey: { type: apiKey, in: header, name: x-api-key }
68
68
  responses:
69
- ValidationError:
70
- description: alxia's own 400, for a request the schemas refuse
69
+ ValidationProblem:
70
+ description: alxia's own 400, for a request the schemas refuse, as an RFC 9457 problem
71
71
  content:
72
- application/json:
73
- schema: { $ref: "#/components/schemas/ValidationError" }
72
+ application/problem+json:
73
+ schema: { $ref: "#/components/schemas/ValidationProblem" }
74
74
  schemas:
75
75
  Todo:
76
76
  type: object
@@ -94,11 +94,15 @@ components:
94
94
  required: [error]
95
95
  properties:
96
96
  error: { type: string, enum: [not_found] }
97
- ValidationError:
97
+ ValidationProblem:
98
98
  type: object
99
- required: [error, issues]
99
+ required: [type, title, status, detail, instance, issues]
100
100
  properties:
101
- error: { type: string, enum: [validation] }
101
+ type: { type: string }
102
+ title: { type: string }
103
+ status: { type: integer }
104
+ detail: { type: string }
105
+ instance: { type: string }
102
106
  issues:
103
107
  type: array
104
108
  items:
@@ -4,9 +4,9 @@
4
4
  "type": "module",
5
5
  "scripts": {
6
6
  "generate": "nxgt-openapi generate",
7
- "dev": "bun --watch src/server.ts",
7
+ "dev": "NODE_ENV=development bun --watch src/server.ts",
8
8
  "build": "bun build src/server.ts --target=bun --outdir=dist --minify --sourcemap=linked",
9
- "start": "bun dist/server.js",
9
+ "start": "NODE_ENV=production bun dist/server.js",
10
10
  "test": "bun test",
11
11
  "typecheck": "tsc --noEmit",
12
12
  "lint": "biome lint",
@@ -17,13 +17,15 @@
17
17
  },
18
18
  "dependencies": {
19
19
  "@alxia/core": "workspace:^",
20
+ "@alxia/env": "workspace:^",
21
+ "@alxia/openapi": "workspace:^",
20
22
  "zod": "^4.5.4"
21
23
  },
22
24
  "devDependencies": {
23
- "@alxia/openapi": "workspace:^",
24
25
  "@biomejs/biome": "2.5.15",
25
- "@nxgt/openapi-codegen": "0.6.0",
26
+ "@nxgt/openapi-codegen": "0.7.0",
26
27
  "@types/bun": "^1.4.2",
28
+ "openapi-fetch": "^0.17.0",
27
29
  "typescript": "^6.0.3"
28
30
  }
29
31
  }