@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 +1 -1
- package/docs/README.md +1 -1
- package/docs/guide.md +53 -5
- package/docs/troubleshooting.md +23 -3
- package/package.json +6 -6
- package/templates/api/package.json +3 -3
- package/templates/api/src/generated/operations.ts +2 -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/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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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:
|
package/docs/troubleshooting.md
CHANGED
|
@@ -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.
|
|
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.
|
|
464
|
-
`bun add --dev --exact @nxgt/openapi-codegen@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.
|
|
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.
|
|
47
|
-
"@alxia/openapi": "^0.6.
|
|
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.
|
|
53
|
-
"@nxgt/openapi-codegen": "0.
|
|
54
|
-
"@nxgt/openapi-httpyz": "^0.3.
|
|
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.
|
|
27
|
-
"@nxgt/openapi-codegen": "0.
|
|
28
|
-
"@nxgt/openapi-httpyz": "^0.3.
|
|
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. */
|
|
@@ -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"
|