@alxia/create 0.5.1 → 0.5.3

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 CHANGED
@@ -223,7 +223,7 @@ or CI.
223
223
  rules the template was not checked against.
224
224
  - **The code generators** are pinned exactly and kept at the template's
225
225
  versions, never moved to a newer patch: `@nxgt/openapi-codegen` (`api`,
226
- `0.7.0`) and GraphQL Code Generator's `@graphql-codegen/cli`,
226
+ `0.11.0`) and GraphQL Code Generator's `@graphql-codegen/cli`,
227
227
  `typescript` and `typescript-resolvers` (`graphql`). `bun run verify` runs
228
228
  `generate --check` over the committed `src/generated/`, which a release
229
229
  that writes the files differently would fail in a fresh project.
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, an `api` test's `ValidationError` or `UndeclaredStatusError`, 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
@@ -249,6 +249,13 @@ files a client reads (`types.ts`, `zod.ts`, `operations.ts`,
249
249
  `paths.ts`). alxia never sends that body. Turned off, the generated files
250
250
  declare only the spec's own 400, which is the one alxia sends.
251
251
 
252
+ `readOnly` and `writeOnly` are `"omit"` by default (since 0.11): a request
253
+ body uses a `<Name>Write` view of its schema without the `readOnly`
254
+ properties, a reply a `<Name>Read` view without the `writeOnly` ones, and a
255
+ schema used in one direction only is stripped in place, with no copy. The
256
+ template's `openapi.yaml` marks none, so nothing changes here; `"keep"`
257
+ restores the schema as written.
258
+
252
259
  ### `src/generated/`
253
260
 
254
261
  `bun run generate` runs `nxgt-openapi generate`, the bin of
@@ -263,7 +270,7 @@ openapi.yaml → src/generated: 5 written, 0 unchanged
263
270
  | `alxia.ts` | one `as const` constant per operation, `{ method, path, schema }`, with the path in alxia's form (`/todos/:id`), the request's Zod schemas, a schema per response status and the `operationId`; and `operations`, all of them by `operationId` |
264
271
  | `zod.ts` | a Zod schema per component schema: `zTodo`, `zNewTodo`, … |
265
272
  | `types.ts` | a TypeScript type per component schema: `Todo`, `NewTodo`, … |
266
- | `operations.ts`, `paths.ts` | `operations.ts` is the table `@nxgt/openapi-httpyz` binds onto a client, which the template's spec uses; `paths.ts` is the same document in openapi-typescript's shape, for a client that reads it, and the template does not use it |
273
+ | `operations.ts`, `paths.ts` | `operations.ts` is the table `@nxgt/openapi-httpyz` binds onto a client, which the template's spec uses; an operation sent as a `QUERY` over `POST` (`x-nxgt-method: query`) has `queryMethod: true`; `paths.ts` is the same document in openapi-typescript's shape, for a client that reads it, and the template does not use it |
267
274
 
268
275
  ```ts
269
276
  // src/generated/alxia.ts, in part
@@ -310,7 +317,7 @@ bun run generate
310
317
  git diff src/generated
311
318
  ```
312
319
 
313
- What the generator does not write, in 0.7.0, and how the app does it
320
+ What the generator does not write, in 0.11.0, and how the app does it
314
321
  instead:
315
322
 
316
323
  - **`security`**: no middleware is generated from it. Authentication is
@@ -993,18 +1000,59 @@ and the README gains a Lint and format section
993
1000
  ([Lint and format](#lint-and-format)); Biome formatted the scaffold once,
994
1001
  which changed three of its files: `app/app.css`'s font list wraps
995
1002
  differently, and `app/routes.ts` and `app/routes/home.tsx` have their
996
- imports sorted. Every other file is React Router's:
1003
+ imports sorted. `app/root.tsx` and `app/app.css` gain a page transition
1004
+ ([below](#page-transitions)). Every other file is React Router's:
997
1005
  `app/`, `public/`, `tsconfig.json`, `react-router.config.ts`, its
998
1006
  `README.md` (with Bun's commands where it wrote npm's: `bun install`,
999
1007
  `bun dev`, `bun run build`), `.gitignore` and `.dockerignore`. `package.json` takes the directory's name, and its
1000
1008
  versions are moved to the newest the registry has ([Versions](#versions)):
1001
1009
  the template's own are where they start.
1002
1010
 
1011
+ ### Page transitions
1012
+
1013
+ React Router 8.5 deprecates its own view transition options (`viewTransition`
1014
+ on `<Link>`, `<Form>` and `navigate`, `useViewTransitionState`) in favour of
1015
+ React's `<ViewTransition>`, stable in React 19.3. The template puts one
1016
+ boundary around the root's `<Outlet />`, never around the `Layout` that holds
1017
+ `<html>` and `<body>`, so the page fades from one route to the next and the
1018
+ document around it stays still:
1019
+
1020
+ ```tsx
1021
+ export default function App() {
1022
+ const { pathname } = useLocation();
1023
+ const shown = useRef(pathname);
1024
+ useEffect(() => {
1025
+ shown.current = pathname;
1026
+ }, [pathname]);
1027
+ return (
1028
+ <ViewTransition update={shown.current === pathname ? "none" : "auto"}>
1029
+ <Outlet />
1030
+ </ViewTransition>
1031
+ );
1032
+ }
1033
+ ```
1034
+
1035
+ `update` is `"none"` unless the pathname changes. Animating every update
1036
+ would also fade a fetcher's answer, or a search writing `?q=` as the reader
1037
+ types, and in an app measured with the plain `<ViewTransition>` the keys
1038
+ typed during that fade were lost. `app/app.css` ends with a
1039
+ `prefers-reduced-motion` rule that turns every view transition's animation
1040
+ off. Keep React Router's transitions on: never `useTransitions={false}`, nor
1041
+ `flushSync` around a navigation, since React animates a `<ViewTransition>`
1042
+ for an update it runs as a transition
1043
+ ([React's reference](https://react.dev/reference/react/ViewTransition)). An element shared by two pages animates between them
1044
+ with `<ViewTransition name="…">`, the same unique name on both.
1045
+
1046
+ Under `<ViewTransition>`, React's server render marks the element it wraps
1047
+ with a `vt-*` attribute (`<main class="p-4" vt-update="none">`), which breaks
1048
+ a test matching a page's exact tag
1049
+ ([troubleshooting](troubleshooting.md#a-page-test-no-longer-finds-its-exact-tag)).
1050
+
1003
1051
  The template follows React Router's majors, not its every release: it is
1004
1052
  written again from `create-react-router` when React Router ships one that
1005
1053
  `@alxia/react-router` accepts, in a new `@alxia/create`. Between two, the
1006
1054
  files are what `create-react-router` wrote when the template was last
1007
- generated (React Router 8.4.0 in this release), and the versions are the newest of that major.
1055
+ 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.
1008
1056
 
1009
1057
  There is no `app/server.ts`: the plugin's default server serves the pages
1010
1058
  in `bun dev` and from the build. To put alxia's middlewares or `/api` routes in
@@ -1286,7 +1334,7 @@ template pins exactly:
1286
1334
  | `graphql` | `^16.11.0 \|\| ^17.0.0`, `@alxia/graphql`'s; so a new project may declare `^17` where the template ships `^16.11.0` |
1287
1335
  | `graphql-yoga` | `^5.16.0`, `@alxia/graphql`'s |
1288
1336
  | `@graphql-codegen/cli`, `@graphql-codegen/typescript`, `@graphql-codegen/typescript-resolvers` | none: the template's exact versions, 7.4.3, 6.1.0 and 6.1.0, are kept, for the reason `@nxgt/openapi-codegen`'s are: `generate --check` |
1289
- | `@nxgt/openapi-codegen` | none: the template's exact version, `0.7.0`, is kept. Any release may write `src/generated/` differently, and `bun run verify` checks it with `generate --check` |
1337
+ | `@nxgt/openapi-codegen` | none: the template's exact version, `0.11.0`, is kept. Any release may write `src/generated/` differently, and `bun run verify` checks it with `generate --check` |
1290
1338
  | anything else: `react`, `isbot`, Tailwind, `@types/*` | no alxia range: npm's `latest` |
1291
1339
 
1292
1340
  The command prints each move, and each newer major it left out:
@@ -401,6 +401,26 @@ an existing project
401
401
  [`@alxia/core`'s upgrading page](https://github.com/softistx/alxia/blob/develop/packages/core/docs/upgrading.md)
402
402
  for what a minor changed.
403
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
+
404
424
  ## The `api` project's spec
405
425
 
406
426
  ### `openapi.yaml → src/generated: out of date, run nxgt-openapi generate`
@@ -441,7 +461,7 @@ A change made by hand in `src/generated/` is lost: make it in
441
461
  right after `bun add --dev --exact @nxgt/openapi-codegen@…`, with no
442
462
  change to `openapi.yaml`.
443
463
 
444
- **When:** the generator moved to another minor, `0.7.x` to `0.8.0`. A new
464
+ **When:** the generator moved to another minor, `0.11.x` to `0.12.0`. A new
445
465
  project never hits it: the command keeps the template's version
446
466
  ([Versions](guide.md#versions)).
447
467
 
@@ -460,8 +480,8 @@ bun run verify
460
480
 
461
481
  The diff is what the new release writes differently; `bun run verify`
462
482
  tells whether the app still compiles and passes against it. To stay
463
- where you were, pin the previous version again, `0.7.0` after a move to `0.8.0`:
464
- `bun add --dev --exact @nxgt/openapi-codegen@0.7.0`.
483
+ where you were, pin the previous version again, `0.11.0` after a move to `0.12.0`:
484
+ `bun add --dev --exact @nxgt/openapi-codegen@0.11.0`.
465
485
 
466
486
  ### `TypeError: matchesSpec(): 1 operation has no route: DELETE /todos/:id (deleteTodo)`
467
487
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alxia/create",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
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",
@@ -43,15 +43,15 @@
43
43
  "devDependencies": {
44
44
  "@alxia/core": "^0.14.2",
45
45
  "@alxia/env": "^0.2.0",
46
- "@alxia/graphql": "^0.8.0",
47
- "@alxia/openapi": "^0.6.8",
46
+ "@alxia/graphql": "^0.8.1",
47
+ "@alxia/openapi": "^0.6.9",
48
48
  "@alxia/react-router": "^0.8.0",
49
49
  "@graphql-codegen/cli": "7.4.3",
50
50
  "@graphql-codegen/typescript": "6.1.0",
51
51
  "@graphql-codegen/typescript-resolvers": "6.1.0",
52
- "@nxgt/httpyz": "^0.3.3",
53
- "@nxgt/openapi-codegen": "0.7.0",
54
- "@nxgt/openapi-httpyz": "^0.3.1",
52
+ "@nxgt/httpyz": "^0.4.1",
53
+ "@nxgt/openapi-codegen": "0.11.0",
54
+ "@nxgt/openapi-httpyz": "^0.3.2",
55
55
  "@types/bun": "^1.4.2",
56
56
  "dataloader": "^2.2.3",
57
57
  "graphql": "^16.11.0 || ^17.0.0",
@@ -23,9 +23,9 @@
23
23
  },
24
24
  "devDependencies": {
25
25
  "@biomejs/biome": "2.5.15",
26
- "@nxgt/httpyz": "^0.3.3",
27
- "@nxgt/openapi-codegen": "0.7.0",
28
- "@nxgt/openapi-httpyz": "^0.3.1",
26
+ "@nxgt/httpyz": "^0.4.1",
27
+ "@nxgt/openapi-codegen": "0.11.0",
28
+ "@nxgt/openapi-httpyz": "^0.3.2",
29
29
  "@types/bun": "^1.4.2",
30
30
  "typescript": "^6.0.3"
31
31
  }
@@ -30,6 +30,8 @@ export interface OperationSpec<Client = unknown> {
30
30
  readonly method: 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace' | 'query';
31
31
  readonly path: string;
32
32
  readonly honoPath: string;
33
+ /** A `QUERY` sent as a `POST` (`x-nxgt-method: query`): safe, its criteria in the body. */
34
+ readonly queryMethod?: true;
33
35
  readonly tags: readonly string[];
34
36
  readonly parameters: readonly ParameterSpec[];
35
37
  /** Validates the path parameters, each read as a string. */
@@ -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"