@alxia/create 0.5.1 → 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, 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
|
@@ -993,18 +993,59 @@ and the README gains a Lint and format section
|
|
|
993
993
|
([Lint and format](#lint-and-format)); Biome formatted the scaffold once,
|
|
994
994
|
which changed three of its files: `app/app.css`'s font list wraps
|
|
995
995
|
differently, and `app/routes.ts` and `app/routes/home.tsx` have their
|
|
996
|
-
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:
|
|
997
998
|
`app/`, `public/`, `tsconfig.json`, `react-router.config.ts`, its
|
|
998
999
|
`README.md` (with Bun's commands where it wrote npm's: `bun install`,
|
|
999
1000
|
`bun dev`, `bun run build`), `.gitignore` and `.dockerignore`. `package.json` takes the directory's name, and its
|
|
1000
1001
|
versions are moved to the newest the registry has ([Versions](#versions)):
|
|
1001
1002
|
the template's own are where they start.
|
|
1002
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
|
+
|
|
1003
1044
|
The template follows React Router's majors, not its every release: it is
|
|
1004
1045
|
written again from `create-react-router` when React Router ships one that
|
|
1005
1046
|
`@alxia/react-router` accepts, in a new `@alxia/create`. Between two, the
|
|
1006
1047
|
files are what `create-react-router` wrote when the template was last
|
|
1007
|
-
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.
|
|
1008
1049
|
|
|
1009
1050
|
There is no `app/server.ts`: the plugin's default server serves the pages
|
|
1010
1051
|
in `bun dev` and from the build. To put alxia's middlewares or `/api` routes in
|
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`
|
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",
|
|
@@ -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"
|