@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.
- package/README.md +80 -25
- package/dist/args.d.ts +3 -1
- package/dist/args.d.ts.map +1 -1
- package/dist/index.js +19 -9
- package/dist/index.js.map +7 -7
- package/dist/main.d.ts +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/registry.d.ts +2 -0
- package/dist/registry.d.ts.map +1 -1
- package/dist/versions.d.ts +5 -2
- package/dist/versions.d.ts.map +1 -1
- package/docs/README.md +16 -6
- package/docs/guide.md +438 -56
- package/docs/roadmap.md +24 -0
- package/docs/troubleshooting.md +146 -50
- package/package.json +16 -6
- package/templates/api/.env.example +9 -1
- package/templates/api/README.md +40 -12
- package/templates/api/openapi.yaml +13 -9
- package/templates/api/package.json +6 -4
- package/templates/api/src/app.spec.ts +42 -28
- package/templates/api/src/app.ts +13 -3
- package/templates/api/src/context.ts +3 -4
- package/templates/api/src/env.ts +20 -0
- package/templates/api/src/generated/alxia.ts +15 -5
- package/templates/api/src/generated/operations.ts +4 -4
- package/templates/api/src/generated/paths.ts +6 -6
- package/templates/api/src/generated/types.ts +14 -10
- package/templates/api/src/generated/zod.ts +6 -2
- package/templates/api/src/routes/todos.ts +2 -2
- package/templates/api/src/server.ts +8 -16
- package/templates/graphql/.dockerignore +6 -0
- package/templates/graphql/.env.example +3 -0
- package/templates/graphql/.vscode/extensions.json +3 -0
- package/templates/graphql/.vscode/settings.json +8 -0
- package/templates/graphql/Dockerfile +26 -0
- package/templates/graphql/README.md +171 -0
- package/templates/graphql/_biome.json +32 -0
- package/templates/graphql/codegen.ts +22 -0
- package/templates/graphql/gitignore +6 -0
- package/templates/graphql/package.json +34 -0
- package/templates/graphql/schema.graphql +26 -0
- package/templates/graphql/src/app.spec.ts +119 -0
- package/templates/graphql/src/app.ts +14 -0
- package/templates/graphql/src/context.ts +24 -0
- package/templates/graphql/src/env.ts +8 -0
- package/templates/graphql/src/generated/resolvers.ts +180 -0
- package/templates/graphql/src/graphql.d.ts +6 -0
- package/templates/graphql/src/resolvers.ts +42 -0
- package/templates/graphql/src/schema.ts +6 -0
- package/templates/graphql/src/server.ts +10 -0
- package/templates/graphql/src/store.ts +25 -0
- package/templates/graphql/tsconfig.json +25 -0
- package/templates/minimal/.dockerignore +6 -0
- package/templates/minimal/.vscode/extensions.json +3 -0
- package/templates/minimal/.vscode/settings.json +8 -0
- package/templates/minimal/Dockerfile +26 -0
- package/templates/minimal/README.md +107 -0
- package/templates/minimal/_biome.json +32 -0
- package/templates/minimal/gitignore +6 -0
- package/templates/minimal/package.json +25 -0
- package/templates/minimal/src/index.spec.ts +12 -0
- package/templates/minimal/src/index.ts +17 -0
- package/templates/minimal/tsconfig.json +25 -0
- 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
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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.
|
|
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
|
-
|
|
525
|
+
## The `graphql` project's schema
|
|
533
526
|
|
|
534
|
-
|
|
535
|
-
|
|
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
|
-
|
|
539
|
-
`
|
|
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
|
-
**
|
|
542
|
-
|
|
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
|
-
**
|
|
545
|
-
the
|
|
546
|
-
the
|
|
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
|
|
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.
|
|
4
|
-
"description": "Start an alxia app: `bun create @alxia` writes
|
|
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.
|
|
43
|
-
"@alxia/
|
|
44
|
-
"@alxia/
|
|
45
|
-
"@
|
|
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
|
package/templates/api/README.md
CHANGED
|
@@ -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),
|
|
16
|
-
|
|
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, `
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
|
58
|
-
`
|
|
59
|
-
`dev-key
|
|
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. `
|
|
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/
|
|
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/
|
|
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
|
-
|
|
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/
|
|
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
|
-
|
|
97
|
+
ValidationProblem:
|
|
98
98
|
type: object
|
|
99
|
-
required: [
|
|
99
|
+
required: [type, title, status, detail, instance, issues]
|
|
100
100
|
properties:
|
|
101
|
-
|
|
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.
|
|
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
|
}
|