@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. 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:
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.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.
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
@@ -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.1",
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",
@@ -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"