@alxia/create 0.5.0 → 0.5.2
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/docs/README.md +1 -1
- package/docs/guide.md +45 -2
- package/docs/roadmap.md +11 -0
- package/docs/troubleshooting.md +83 -0
- package/package.json +1 -1
- package/templates/api/README.md +5 -0
- package/templates/react-router/app/app.css +8 -0
- package/templates/react-router/app/root.tsx +14 -1
- package/templates/react-router/package.json +8 -8
package/docs/README.md
CHANGED
|
@@ -10,7 +10,7 @@ errors the command and a new project print.
|
|
|
10
10
|
| Page | Read it when |
|
|
11
11
|
| --- | --- |
|
|
12
12
|
| [Guide](guide.md) | choosing a template, reading what it wrote, adding an operation to the `api` project's `openapi.yaml` or a field to the `graphql` project's `schema.graphql`, linting and formatting it with Biome, building its Docker image, pinning or moving versions, or running the command in a script or CI |
|
|
13
|
-
| [Troubleshooting](troubleshooting.md) | the command refused a directory, a template or an option, the registry did not answer or lacked a version, `bun install` failed, Biome refused to run in a project, or the `api` or `graphql` project's `generate --check`, an `api` `matchesSpec` or reply check, or a `graphql` schema import failed |
|
|
13
|
+
| [Troubleshooting](troubleshooting.md) | the command refused a directory, a template or an option, the registry did not answer or lacked a version, `bun install` failed, Biome refused to run in a project, or the `api` or `graphql` project's `generate --check`, an `api` `matchesSpec` or reply check, an `api` test's `ValidationError` or `UndeclaredStatusError`, or a `graphql` schema import failed, or a `react-router` page test no longer finds its exact tag |
|
|
14
14
|
| [Roadmap](roadmap.md) | wondering what is coming, and what is not planned |
|
|
15
15
|
|
|
16
16
|
## Recipes
|
package/docs/guide.md
CHANGED
|
@@ -570,6 +570,8 @@ request against the spec before it sends it, so the 400 and the 401 tests
|
|
|
570
570
|
use a second client built with `validate: { request: false }`, and a request
|
|
571
571
|
the types forbid (`/todos/first`) goes through `app.request`. See
|
|
572
572
|
[Testing with the generated client](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/testing.md).
|
|
573
|
+
A test that throws `ValidationError` or `UndeclaredStatusError` is in
|
|
574
|
+
[troubleshooting](troubleshooting.md#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters) ([the other](troubleshooting.md#undeclaredstatuserror-gettodo-get-todosid-no-418-reply-is-declared)).
|
|
573
575
|
|
|
574
576
|
### Adding an operation
|
|
575
577
|
|
|
@@ -991,18 +993,59 @@ and the README gains a Lint and format section
|
|
|
991
993
|
([Lint and format](#lint-and-format)); Biome formatted the scaffold once,
|
|
992
994
|
which changed three of its files: `app/app.css`'s font list wraps
|
|
993
995
|
differently, and `app/routes.ts` and `app/routes/home.tsx` have their
|
|
994
|
-
imports sorted.
|
|
996
|
+
imports sorted. `app/root.tsx` and `app/app.css` gain a page transition
|
|
997
|
+
([below](#page-transitions)). Every other file is React Router's:
|
|
995
998
|
`app/`, `public/`, `tsconfig.json`, `react-router.config.ts`, its
|
|
996
999
|
`README.md` (with Bun's commands where it wrote npm's: `bun install`,
|
|
997
1000
|
`bun dev`, `bun run build`), `.gitignore` and `.dockerignore`. `package.json` takes the directory's name, and its
|
|
998
1001
|
versions are moved to the newest the registry has ([Versions](#versions)):
|
|
999
1002
|
the template's own are where they start.
|
|
1000
1003
|
|
|
1004
|
+
### Page transitions
|
|
1005
|
+
|
|
1006
|
+
React Router 8.5 deprecates its own view transition options (`viewTransition`
|
|
1007
|
+
on `<Link>`, `<Form>` and `navigate`, `useViewTransitionState`) in favour of
|
|
1008
|
+
React's `<ViewTransition>`, stable in React 19.3. The template puts one
|
|
1009
|
+
boundary around the root's `<Outlet />`, never around the `Layout` that holds
|
|
1010
|
+
`<html>` and `<body>`, so the page fades from one route to the next and the
|
|
1011
|
+
document around it stays still:
|
|
1012
|
+
|
|
1013
|
+
```tsx
|
|
1014
|
+
export default function App() {
|
|
1015
|
+
const { pathname } = useLocation();
|
|
1016
|
+
const shown = useRef(pathname);
|
|
1017
|
+
useEffect(() => {
|
|
1018
|
+
shown.current = pathname;
|
|
1019
|
+
}, [pathname]);
|
|
1020
|
+
return (
|
|
1021
|
+
<ViewTransition update={shown.current === pathname ? "none" : "auto"}>
|
|
1022
|
+
<Outlet />
|
|
1023
|
+
</ViewTransition>
|
|
1024
|
+
);
|
|
1025
|
+
}
|
|
1026
|
+
```
|
|
1027
|
+
|
|
1028
|
+
`update` is `"none"` unless the pathname changes. Animating every update
|
|
1029
|
+
would also fade a fetcher's answer, or a search writing `?q=` as the reader
|
|
1030
|
+
types, and in an app measured with the plain `<ViewTransition>` the keys
|
|
1031
|
+
typed during that fade were lost. `app/app.css` ends with a
|
|
1032
|
+
`prefers-reduced-motion` rule that turns every view transition's animation
|
|
1033
|
+
off. Keep React Router's transitions on: never `useTransitions={false}`, nor
|
|
1034
|
+
`flushSync` around a navigation, since React animates a `<ViewTransition>`
|
|
1035
|
+
for an update it runs as a transition
|
|
1036
|
+
([React's reference](https://react.dev/reference/react/ViewTransition)). An element shared by two pages animates between them
|
|
1037
|
+
with `<ViewTransition name="…">`, the same unique name on both.
|
|
1038
|
+
|
|
1039
|
+
Under `<ViewTransition>`, React's server render marks the element it wraps
|
|
1040
|
+
with a `vt-*` attribute (`<main class="p-4" vt-update="none">`), which breaks
|
|
1041
|
+
a test matching a page's exact tag
|
|
1042
|
+
([troubleshooting](troubleshooting.md#a-page-test-no-longer-finds-its-exact-tag)).
|
|
1043
|
+
|
|
1001
1044
|
The template follows React Router's majors, not its every release: it is
|
|
1002
1045
|
written again from `create-react-router` when React Router ships one that
|
|
1003
1046
|
`@alxia/react-router` accepts, in a new `@alxia/create`. Between two, the
|
|
1004
1047
|
files are what `create-react-router` wrote when the template was last
|
|
1005
|
-
generated (React Router 8.
|
|
1048
|
+
generated (React Router 8.5.0 in this release; `react` and `react-dom` start at 19.3, the first React with `<ViewTransition>`, where the scaffold may still ask for an older one), and the versions are the newest of that major.
|
|
1006
1049
|
|
|
1007
1050
|
There is no `app/server.ts`: the plugin's default server serves the pages
|
|
1008
1051
|
in `bun dev` and from the build. To put alxia's middlewares or `/api` routes in
|
package/docs/roadmap.md
CHANGED
|
@@ -39,6 +39,17 @@ Nothing scheduled yet.
|
|
|
39
39
|
|
|
40
40
|
## Shipped
|
|
41
41
|
|
|
42
|
+
### 0.5.1
|
|
43
|
+
|
|
44
|
+
- **The `api` template's client errors, documented and held in step.**
|
|
45
|
+
[Troubleshooting](troubleshooting.md#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters)
|
|
46
|
+
names the two errors a new project's tests can meet through the typed
|
|
47
|
+
client, `ValidationError` (a request the spec refuses never leaves the
|
|
48
|
+
test: use a second client with `validate: { request: false }`) and
|
|
49
|
+
`UndeclaredStatusError` (the app answered a status the spec does not
|
|
50
|
+
declare), and a spec of `@alxia/create` fails when the template's
|
|
51
|
+
`@nxgt/httpyz` and `@nxgt/openapi-httpyz` ranges differ from its own.
|
|
52
|
+
|
|
42
53
|
### 0.4.1
|
|
43
54
|
|
|
44
55
|
- **`graphqlClient` in the `graphql` template.** Its spec calls the app through `graphqlClient` from `@alxia/graphql/testing`, in place of a helper of its own.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -47,6 +47,8 @@ print, or — for a trap that prints nothing — the symptom.
|
|
|
47
47
|
- [`src/generated/` changes after moving `@nxgt/openapi-codegen`](#srcgenerated-changes-after-moving-nxgtopenapi-codegen)
|
|
48
48
|
- [`TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`](#typeerror-matchesspec-1-operation-has-no-route-delete-todosid-deletetodo)
|
|
49
49
|
- [`ResponseValidationError: POST /todos: the 201 reply does not match its schema`](#responsevalidationerror-post-todos-the-201-reply-does-not-match-its-schema)
|
|
50
|
+
- [`ValidationError: createTodo (POST /todos): Too small: expected string to have >=1 characters`](#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters)
|
|
51
|
+
- [`UndeclaredStatusError: getTodo (GET /todos/{id}): no 418 reply is declared`](#undeclaredstatuserror-gettodo-get-todosid-no-418-reply-is-declared)
|
|
50
52
|
|
|
51
53
|
**The `graphql` project's schema**
|
|
52
54
|
|
|
@@ -399,6 +401,26 @@ an existing project
|
|
|
399
401
|
[`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
|
|
400
402
|
for what a minor changed.
|
|
401
403
|
|
|
404
|
+
### A page test no longer finds its exact tag
|
|
405
|
+
|
|
406
|
+
`expect(received).toContain(expected)`, with `Expected to contain:
|
|
407
|
+
"<h1>Title</h1>"` and the page's HTML holding `<h1 vt-update="none">Title</h1>`.
|
|
408
|
+
|
|
409
|
+
**When:** a `react-router` project's test reads a page's HTML from the
|
|
410
|
+
server and matches the first element of a route's page by its exact tag.
|
|
411
|
+
|
|
412
|
+
**Why:** the root's `<Outlet />` is inside React's `<ViewTransition>`
|
|
413
|
+
([Page transitions](guide.md#page-transitions)), and React's server render
|
|
414
|
+
marks the element it wraps with a `vt-*` attribute, such as
|
|
415
|
+
`vt-update="none"`.
|
|
416
|
+
|
|
417
|
+
**Fix:** match the tag whatever its attributes, or query the page by role
|
|
418
|
+
and accessible name:
|
|
419
|
+
|
|
420
|
+
```ts
|
|
421
|
+
expect(html).toMatch(/<h1[^>]*>Title<\/h1>/);
|
|
422
|
+
```
|
|
423
|
+
|
|
402
424
|
## The `api` project's spec
|
|
403
425
|
|
|
404
426
|
### `openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
|
|
@@ -523,6 +545,67 @@ reply.created({ id: todo.id, title: todo.title, done: todo.done }) // Todo: { id
|
|
|
523
545
|
The other forms of the error, and how to turn the check off, are in
|
|
524
546
|
[`@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).
|
|
525
547
|
|
|
548
|
+
### `ValidationError: createTodo (POST /todos): Too small: expected string to have >=1 characters`
|
|
549
|
+
|
|
550
|
+
A test of the app's own 400 or 401 throws in the test, before any request
|
|
551
|
+
reaches the app:
|
|
552
|
+
|
|
553
|
+
```text
|
|
554
|
+
ValidationError: createTodo (POST /todos): Too small: expected string to have >=1 characters
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
The operation, method and path are the call's, and the text after the colon is
|
|
558
|
+
the first issue's message (several are joined with `; `). The same class
|
|
559
|
+
also throws for a reply the spec does not describe (a body that is not valid
|
|
560
|
+
JSON, a value its schema refuses), whose `failure.kind` is `'response'`;
|
|
561
|
+
`'request'` is the one here.
|
|
562
|
+
|
|
563
|
+
**When:** the test sends what `openapi.yaml` refuses (an empty `title`, a
|
|
564
|
+
missing key) to see the app answer 400 or 401.
|
|
565
|
+
|
|
566
|
+
**Why:** the client checks every request against the spec before it sends
|
|
567
|
+
it, by default, and throws what the server would refuse. Nothing was sent.
|
|
568
|
+
|
|
569
|
+
**Fix:** build a second client that does not check requests, and use it for
|
|
570
|
+
the tests of a refusal. Keep the first one for the calls that must pass:
|
|
571
|
+
|
|
572
|
+
```ts
|
|
573
|
+
const api = createOpenApiClient(http, operations);
|
|
574
|
+
const raw = createOpenApiClient(http, operations, {
|
|
575
|
+
validate: { request: false },
|
|
576
|
+
});
|
|
577
|
+
|
|
578
|
+
const reply = await raw.op("createTodo", { json: { title: "" } });
|
|
579
|
+
expect(reply.status).toBe(400);
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
A request the types forbid (`/todos/first`) goes through `app.request()`.
|
|
583
|
+
See [Testing with the generated client](https://github.com/softistx/alxia/blob/develop/packages/openapi/docs/guide/testing.md#keep-one-apprequest-test).
|
|
584
|
+
|
|
585
|
+
### `UndeclaredStatusError: getTodo (GET /todos/{id}): no 418 reply is declared`
|
|
586
|
+
|
|
587
|
+
A test through the client throws, naming the status the app answered:
|
|
588
|
+
|
|
589
|
+
```text
|
|
590
|
+
UndeclaredStatusError: getTodo (GET /todos/{id}): no 418 reply is declared
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
The error's `status` is the status and its `response` the unread `Response`,
|
|
594
|
+
so a test can read the body to see what the app sent.
|
|
595
|
+
|
|
596
|
+
**When:** the app answers a status `openapi.yaml` does not declare for that
|
|
597
|
+
operation: a 500 from a handler that threw, a 404 or 403 the spec never
|
|
598
|
+
mentioned, a status a middleware sent.
|
|
599
|
+
|
|
600
|
+
**Why:** the client reads a reply by the statuses the operation declares, so
|
|
601
|
+
a client generated from the spec never returns a body it was not told about.
|
|
602
|
+
|
|
603
|
+
**Fix:** if the status is right, declare it under the operation's
|
|
604
|
+
`responses` in `openapi.yaml`, then `bun run generate`; if the app should not
|
|
605
|
+
send it, fix the route (a 500 is usually the handler's bug, so read
|
|
606
|
+
`error.response`). A test of a status the spec leaves out on purpose goes through
|
|
607
|
+
`app.request()`, which reads whatever comes back.
|
|
608
|
+
|
|
526
609
|
## The `graphql` project's schema
|
|
527
610
|
|
|
528
611
|
### `The following stale files were detected: src/generated/resolvers.ts`
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@alxia/create",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
4
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",
|
package/templates/api/README.md
CHANGED
|
@@ -139,6 +139,11 @@ bun run typecheck
|
|
|
139
139
|
bun run generate # src/generated/, from openapi.yaml
|
|
140
140
|
```
|
|
141
141
|
|
|
142
|
+
A test that throws `ValidationError` (the client refused a request the spec
|
|
143
|
+
forbids before sending it) or `UndeclaredStatusError` (the app answered a
|
|
144
|
+
status `openapi.yaml` does not declare) is in
|
|
145
|
+
[troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#validationerror-createtodo-post-todos-too-small-expected-string-to-have-1-characters).
|
|
146
|
+
|
|
142
147
|
## Lint and format
|
|
143
148
|
|
|
144
149
|
[Biome](https://biomejs.dev) lints and formats the project, as `biome.json`
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { useEffect, useRef, ViewTransition } from "react";
|
|
1
2
|
import {
|
|
2
3
|
isRouteErrorResponse,
|
|
3
4
|
Links,
|
|
@@ -5,6 +6,7 @@ import {
|
|
|
5
6
|
Outlet,
|
|
6
7
|
Scripts,
|
|
7
8
|
ScrollRestoration,
|
|
9
|
+
useLocation,
|
|
8
10
|
} from "react-router";
|
|
9
11
|
|
|
10
12
|
import type { Route } from "./+types/root";
|
|
@@ -42,7 +44,18 @@ export function Layout({ children }: { children: React.ReactNode }) {
|
|
|
42
44
|
}
|
|
43
45
|
|
|
44
46
|
export default function App() {
|
|
45
|
-
|
|
47
|
+
// One boundary for the pages: a navigation to another pathname
|
|
48
|
+
// animates, while a fetcher's answer or a new ?q= updates in place.
|
|
49
|
+
const { pathname } = useLocation();
|
|
50
|
+
const shown = useRef(pathname);
|
|
51
|
+
useEffect(() => {
|
|
52
|
+
shown.current = pathname;
|
|
53
|
+
}, [pathname]);
|
|
54
|
+
return (
|
|
55
|
+
<ViewTransition update={shown.current === pathname ? "none" : "auto"}>
|
|
56
|
+
<Outlet />
|
|
57
|
+
</ViewTransition>
|
|
58
|
+
);
|
|
46
59
|
}
|
|
47
60
|
|
|
48
61
|
export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
|
|
@@ -16,20 +16,20 @@
|
|
|
16
16
|
"dependencies": {
|
|
17
17
|
"@alxia/core": "workspace:^",
|
|
18
18
|
"@alxia/react-router": "workspace:^",
|
|
19
|
-
"@react-router/node": "^8.
|
|
20
|
-
"@react-router/serve": "^8.
|
|
19
|
+
"@react-router/node": "^8.5.0",
|
|
20
|
+
"@react-router/serve": "^8.5.0",
|
|
21
21
|
"isbot": "^5.1.36",
|
|
22
|
-
"react": "^19.
|
|
23
|
-
"react-dom": "^19.
|
|
24
|
-
"react-router": "^8.
|
|
22
|
+
"react": "^19.3.0",
|
|
23
|
+
"react-dom": "^19.3.0",
|
|
24
|
+
"react-router": "^8.5.0"
|
|
25
25
|
},
|
|
26
26
|
"devDependencies": {
|
|
27
27
|
"@biomejs/biome": "2.5.15",
|
|
28
|
-
"@react-router/dev": "^8.
|
|
28
|
+
"@react-router/dev": "^8.5.0",
|
|
29
29
|
"@tailwindcss/vite": "^4.2.2",
|
|
30
30
|
"@types/node": "^22",
|
|
31
|
-
"@types/react": "^19.
|
|
32
|
-
"@types/react-dom": "^19.
|
|
31
|
+
"@types/react": "^19.3.0",
|
|
32
|
+
"@types/react-dom": "^19.3.0",
|
|
33
33
|
"tailwindcss": "^4.2.2",
|
|
34
34
|
"typescript": "^5.9.3",
|
|
35
35
|
"vite": "^8.0.3"
|