@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 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. Every other file is React Router's:
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.4.0 in this release), and the versions are the newest of that major.
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.
@@ -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.0",
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",
@@ -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`
@@ -14,3 +14,11 @@ body {
14
14
  color-scheme: dark;
15
15
  }
16
16
  }
17
+
18
+ @media (prefers-reduced-motion: reduce) {
19
+ ::view-transition-group(*),
20
+ ::view-transition-old(*),
21
+ ::view-transition-new(*) {
22
+ animation: none;
23
+ }
24
+ }
@@ -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
- return <Outlet />;
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.4.0",
20
- "@react-router/serve": "^8.4.0",
19
+ "@react-router/node": "^8.5.0",
20
+ "@react-router/serve": "^8.5.0",
21
21
  "isbot": "^5.1.36",
22
- "react": "^19.2.8",
23
- "react-dom": "^19.2.8",
24
- "react-router": "^8.4.0"
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.4.0",
28
+ "@react-router/dev": "^8.5.0",
29
29
  "@tailwindcss/vite": "^4.2.2",
30
30
  "@types/node": "^22",
31
- "@types/react": "^19.2.18",
32
- "@types/react-dom": "^19.2.7",
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"