create-rr-stack 0.1.0 → 0.1.1
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 +114 -0
- package/package.json +3 -3
- package/scaffold.ts +1 -0
- package/template/README.md +88 -32
package/README.md
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# RR stack
|
|
2
|
+
|
|
3
|
+
React Router + Rust (Axum), typed from the database to the screen.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
bun create rr-stack my-app
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Made for a team where AI agents write most of the code and people review it. One command,
|
|
10
|
+
`scripts/check.sh`, answers "is it done?". If it exits 0, the SQL, the Rust API, the OpenAPI
|
|
11
|
+
contract and the React code agree with each other.
|
|
12
|
+
|
|
13
|
+
> **If you are an AI agent:** read this file for the map, then follow `AGENTS.md` in the project root.
|
|
14
|
+
> Your task is done only when `scripts/check.sh` exits 0.
|
|
15
|
+
|
|
16
|
+
## What you get
|
|
17
|
+
|
|
18
|
+
| Layer | Tool | What is checked, and when |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| Database | Postgres + SQLx `query!` | SQL against the real schema, at compile time |
|
|
21
|
+
| API | Axum + utoipa | `openapi.json` is derived from the Rust handlers |
|
|
22
|
+
| Contract | `openapi.json` | regenerated and diffed on every check |
|
|
23
|
+
| Client | hey-api + TanStack Query | TS client and hooks generated from the contract |
|
|
24
|
+
| UI | React Router (`ssr: false` + `prerender`) | `tsc --noEmit` and a full build |
|
|
25
|
+
|
|
26
|
+
In production it is one process. Axum serves `/api/*` and the built pages. There is no Node at
|
|
27
|
+
runtime.
|
|
28
|
+
|
|
29
|
+
## Requirements
|
|
30
|
+
|
|
31
|
+
- Rust (stable), [bun](https://bun.sh), Docker
|
|
32
|
+
- `cargo install sqlx-cli --no-default-features --features postgres,rustls`
|
|
33
|
+
|
|
34
|
+
## Create a project
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
bun create rr-stack my-app # --no-install and --no-git skip those steps
|
|
38
|
+
cd my-app
|
|
39
|
+
docker compose up -d --wait
|
|
40
|
+
(cd server && sqlx migrate run)
|
|
41
|
+
scripts/check.sh # expect "check OK" on the last line
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The CLI copies the template and renames the packages to `my-app-server` and `my-app-web`. Each
|
|
45
|
+
project gets its own Postgres database name and host port (54000-54999), so two projects can run at
|
|
46
|
+
the same time. It also writes `.env`, runs `bun install` and runs `git init`.
|
|
47
|
+
|
|
48
|
+
## Run it
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
(cd server && cargo run) # API on :3000, reads ../.env
|
|
52
|
+
(cd web && bun run dev) # UI on :5173, /api is proxied to :3000
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Open http://localhost:5173 (a prerendered page) and http://localhost:5173/app/todos (the SPA).
|
|
56
|
+
|
|
57
|
+
## Commands
|
|
58
|
+
|
|
59
|
+
| Command | Exit 0 means | Run it when |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `scripts/check.sh` | fmt, clippy, contract, typecheck, web build, `.sqlx`, tests all pass | before you call anything done |
|
|
62
|
+
| `scripts/smoke.sh` | the real binary serves pages, deep links and the API over HTTP | you changed how files or routes are served |
|
|
63
|
+
| `cd web && bun run gen` | `openapi.json` and `web/app/api/` regenerated | you changed a handler or a type that crosses the wire |
|
|
64
|
+
| `cd server && cargo sqlx prepare -- --all-targets` | `server/.sqlx/` matches the SQL | you added or changed a query |
|
|
65
|
+
|
|
66
|
+
`check.sh` needs the database. Without `DATABASE_URL` it fails on purpose. `SKIP_DB=1` runs the
|
|
67
|
+
rest, and the output says that the result is not done.
|
|
68
|
+
|
|
69
|
+
## Where things are
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
server/src/lib.rs api_router(): every route is registered here (spec + runtime)
|
|
73
|
+
server/src/todos.rs example domain: TodoTitle validates input at the boundary
|
|
74
|
+
server/migrations/ database schema (source of truth for tables)
|
|
75
|
+
server/tests/ integration tests, each gets a fresh database (#[sqlx::test])
|
|
76
|
+
web/app/routes.ts page routes
|
|
77
|
+
web/app/api/ GENERATED client, never edit by hand
|
|
78
|
+
web/react-router.config.ts prerender list: pages that search engines must see
|
|
79
|
+
openapi.json GENERATED contract, never edit by hand
|
|
80
|
+
scripts/check.sh definition of done
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## How a change flows
|
|
84
|
+
|
|
85
|
+
1. Change the SQL in a migration, or add a query with `query!`.
|
|
86
|
+
2. Change the Rust handler and its `ToSchema` types. Then register the route in `api_router()`.
|
|
87
|
+
3. `cd web && bun run gen` regenerates the contract and the client.
|
|
88
|
+
4. Use the generated `<operationId>Options()` or `<operationId>Mutation()` in a route.
|
|
89
|
+
5. `scripts/check.sh`. If a layer disagrees with another, this is where it fails.
|
|
90
|
+
|
|
91
|
+
## SEO pages and the app
|
|
92
|
+
|
|
93
|
+
Paths in `prerender` (`web/react-router.config.ts`) are rendered to HTML at build time, so search
|
|
94
|
+
engines see their content. Every other route is a SPA behind the same server, and deep links work
|
|
95
|
+
because Axum falls back to the SPA shell. Unknown `/api/*` paths return a JSON 404, never HTML.
|
|
96
|
+
In this version, prerendered pages cannot fetch from the API at build time.
|
|
97
|
+
|
|
98
|
+
## Production
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
(cd web && bun run build)
|
|
102
|
+
(cd server && cargo build --release)
|
|
103
|
+
WEB_DIST=web/build/client DATABASE_URL=postgres://... server/target/release/server
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The server runs migrations on startup.
|
|
107
|
+
|
|
108
|
+
## Not included yet
|
|
109
|
+
|
|
110
|
+
Auth, server-side rendering (`ssr: true`), structured JSON error bodies, deploy recipes.
|
|
111
|
+
|
|
112
|
+
## License
|
|
113
|
+
|
|
114
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-rr-stack",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"bin": {
|
|
6
6
|
"create-rr-stack": "index.ts"
|
|
7
7
|
},
|
|
8
8
|
"scripts": {
|
|
9
9
|
"test": "bun test",
|
|
10
|
-
"prepack": "rm -rf template && bun -e \"await (await import('./scaffold.ts')).buildTemplate('..', 'template')\" && cp ../LICENSE
|
|
11
|
-
"postpack": "rm -rf template LICENSE"
|
|
10
|
+
"prepack": "rm -rf template && bun -e \"await (await import('./scaffold.ts')).buildTemplate('..', 'template')\" && cp ../LICENSE ../README.md .",
|
|
11
|
+
"postpack": "rm -rf template LICENSE README.md"
|
|
12
12
|
},
|
|
13
13
|
"description": "Scaffold a React Router + Rust (Axum) app that is typed from the database to the screen.",
|
|
14
14
|
"license": "MIT",
|
package/scaffold.ts
CHANGED
|
@@ -53,6 +53,7 @@ export async function scaffold(opts: { name: string; dest: string; source: strin
|
|
|
53
53
|
const crate = `name = "${name}-server"`;
|
|
54
54
|
await edit(join(dest, "server/Cargo.toml"), (s) => must(s, ['name = "rr-server"']).replace('name = "rr-server"', crate));
|
|
55
55
|
await edit(join(dest, "server/Cargo.lock"), (s) => must(s, ['name = "rr-server"']).replace('name = "rr-server"', crate));
|
|
56
|
+
await edit(join(dest, "README.md"), (s) => must(s, ["# RR stack\n"]).replace("# RR stack\n", `# ${name}\n`));
|
|
56
57
|
await edit(join(dest, "web/package.json"), (s) => {
|
|
57
58
|
const pkg = JSON.parse(s);
|
|
58
59
|
pkg.name = `${name}-web`;
|
package/template/README.md
CHANGED
|
@@ -1,58 +1,114 @@
|
|
|
1
1
|
# RR stack
|
|
2
2
|
|
|
3
|
-
React + Rust, typed from the database to the screen.
|
|
4
|
-
if `scripts/check.sh` passes, the SQL, the Rust API, the OpenAPI contract and the React code agree.
|
|
5
|
-
|
|
6
|
-
- **server/** Axum + utoipa (OpenAPI from code) + SQLx (`query!` checked against the real schema)
|
|
7
|
-
- **web/** React Router (`ssr: false` + `prerender`), client and react-query hooks generated by hey-api
|
|
8
|
-
- One process in production: Axum serves `/api/*` and the built pages. No Node at runtime.
|
|
9
|
-
|
|
10
|
-
## New project
|
|
3
|
+
React Router + Rust (Axum), typed from the database to the screen.
|
|
11
4
|
|
|
12
5
|
```bash
|
|
13
|
-
bun create rr-stack my-app
|
|
6
|
+
bun create rr-stack my-app
|
|
14
7
|
```
|
|
15
8
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
9
|
+
Made for a team where AI agents write most of the code and people review it. One command,
|
|
10
|
+
`scripts/check.sh`, answers "is it done?". If it exits 0, the SQL, the Rust API, the OpenAPI
|
|
11
|
+
contract and the React code agree with each other.
|
|
12
|
+
|
|
13
|
+
> **If you are an AI agent:** read this file for the map, then follow `AGENTS.md` in the project root.
|
|
14
|
+
> Your task is done only when `scripts/check.sh` exits 0.
|
|
15
|
+
|
|
16
|
+
## What you get
|
|
17
|
+
|
|
18
|
+
| Layer | Tool | What is checked, and when |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| Database | Postgres + SQLx `query!` | SQL against the real schema, at compile time |
|
|
21
|
+
| API | Axum + utoipa | `openapi.json` is derived from the Rust handlers |
|
|
22
|
+
| Contract | `openapi.json` | regenerated and diffed on every check |
|
|
23
|
+
| Client | hey-api + TanStack Query | TS client and hooks generated from the contract |
|
|
24
|
+
| UI | React Router (`ssr: false` + `prerender`) | `tsc --noEmit` and a full build |
|
|
25
|
+
|
|
26
|
+
In production it is one process. Axum serves `/api/*` and the built pages. There is no Node at
|
|
27
|
+
runtime.
|
|
20
28
|
|
|
21
|
-
##
|
|
29
|
+
## Requirements
|
|
22
30
|
|
|
23
|
-
|
|
31
|
+
- Rust (stable), [bun](https://bun.sh), Docker
|
|
32
|
+
- `cargo install sqlx-cli --no-default-features --features postgres,rustls`
|
|
33
|
+
|
|
34
|
+
## Create a project
|
|
24
35
|
|
|
25
36
|
```bash
|
|
26
|
-
|
|
37
|
+
bun create rr-stack my-app # --no-install and --no-git skip those steps
|
|
38
|
+
cd my-app
|
|
27
39
|
docker compose up -d --wait
|
|
28
40
|
(cd server && sqlx migrate run)
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
41
|
+
scripts/check.sh # expect "check OK" on the last line
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The CLI copies the template and renames the packages to `my-app-server` and `my-app-web`. Each
|
|
45
|
+
project gets its own Postgres database name and host port (54000-54999), so two projects can run at
|
|
46
|
+
the same time. It also writes `.env`, runs `bun install` and runs `git init`.
|
|
47
|
+
|
|
48
|
+
## Run it
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
(cd server && cargo run) # API on :3000, reads ../.env
|
|
52
|
+
(cd web && bun run dev) # UI on :5173, /api is proxied to :3000
|
|
32
53
|
```
|
|
33
54
|
|
|
34
|
-
Open http://localhost:5173 and http://localhost:5173/app/todos.
|
|
55
|
+
Open http://localhost:5173 (a prerendered page) and http://localhost:5173/app/todos (the SPA).
|
|
35
56
|
|
|
36
|
-
##
|
|
57
|
+
## Commands
|
|
37
58
|
|
|
38
|
-
| Command |
|
|
39
|
-
|
|
40
|
-
| `scripts/check.sh` |
|
|
41
|
-
| `scripts/smoke.sh` |
|
|
42
|
-
| `cd web && bun run gen` |
|
|
59
|
+
| Command | Exit 0 means | Run it when |
|
|
60
|
+
|---|---|---|
|
|
61
|
+
| `scripts/check.sh` | fmt, clippy, contract, typecheck, web build, `.sqlx`, tests all pass | before you call anything done |
|
|
62
|
+
| `scripts/smoke.sh` | the real binary serves pages, deep links and the API over HTTP | you changed how files or routes are served |
|
|
63
|
+
| `cd web && bun run gen` | `openapi.json` and `web/app/api/` regenerated | you changed a handler or a type that crosses the wire |
|
|
64
|
+
| `cd server && cargo sqlx prepare -- --all-targets` | `server/.sqlx/` matches the SQL | you added or changed a query |
|
|
43
65
|
|
|
44
|
-
|
|
66
|
+
`check.sh` needs the database. Without `DATABASE_URL` it fails on purpose. `SKIP_DB=1` runs the
|
|
67
|
+
rest, and the output says that the result is not done.
|
|
45
68
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
69
|
+
## Where things are
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
server/src/lib.rs api_router(): every route is registered here (spec + runtime)
|
|
73
|
+
server/src/todos.rs example domain: TodoTitle validates input at the boundary
|
|
74
|
+
server/migrations/ database schema (source of truth for tables)
|
|
75
|
+
server/tests/ integration tests, each gets a fresh database (#[sqlx::test])
|
|
76
|
+
web/app/routes.ts page routes
|
|
77
|
+
web/app/api/ GENERATED client, never edit by hand
|
|
78
|
+
web/react-router.config.ts prerender list: pages that search engines must see
|
|
79
|
+
openapi.json GENERATED contract, never edit by hand
|
|
80
|
+
scripts/check.sh definition of done
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## How a change flows
|
|
84
|
+
|
|
85
|
+
1. Change the SQL in a migration, or add a query with `query!`.
|
|
86
|
+
2. Change the Rust handler and its `ToSchema` types. Then register the route in `api_router()`.
|
|
87
|
+
3. `cd web && bun run gen` regenerates the contract and the client.
|
|
88
|
+
4. Use the generated `<operationId>Options()` or `<operationId>Mutation()` in a route.
|
|
89
|
+
5. `scripts/check.sh`. If a layer disagrees with another, this is where it fails.
|
|
90
|
+
|
|
91
|
+
## SEO pages and the app
|
|
92
|
+
|
|
93
|
+
Paths in `prerender` (`web/react-router.config.ts`) are rendered to HTML at build time, so search
|
|
94
|
+
engines see their content. Every other route is a SPA behind the same server, and deep links work
|
|
95
|
+
because Axum falls back to the SPA shell. Unknown `/api/*` paths return a JSON 404, never HTML.
|
|
96
|
+
In this version, prerendered pages cannot fetch from the API at build time.
|
|
49
97
|
|
|
50
98
|
## Production
|
|
51
99
|
|
|
52
100
|
```bash
|
|
53
101
|
(cd web && bun run build)
|
|
54
102
|
(cd server && cargo build --release)
|
|
55
|
-
WEB_DIST=web/build/client DATABASE_URL
|
|
103
|
+
WEB_DIST=web/build/client DATABASE_URL=postgres://... server/target/release/server
|
|
56
104
|
```
|
|
57
105
|
|
|
58
|
-
|
|
106
|
+
The server runs migrations on startup.
|
|
107
|
+
|
|
108
|
+
## Not included yet
|
|
109
|
+
|
|
110
|
+
Auth, server-side rendering (`ssr: true`), structured JSON error bodies, deploy recipes.
|
|
111
|
+
|
|
112
|
+
## License
|
|
113
|
+
|
|
114
|
+
MIT
|