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 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.0",
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 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`;
@@ -1,58 +1,114 @@
1
1
  # RR stack
2
2
 
3
- React + Rust, typed from the database to the screen. Built for AI agents to write and humans to review:
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 # add --no-install or --no-git to skip those steps
6
+ bun create rr-stack my-app
14
7
  ```
15
8
 
16
- `bun create rr-stack` runs the `create-rr-stack` package. It copies the template (only files git
17
- tracks), renames the Cargo and npm packages to `my-app-server` / `my-app-web`, gives the project its
18
- own Postgres database name and host port (54000-54999), writes `.env`, runs `bun install` and
19
- `git init`.
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
- ## Quick start
29
+ ## Requirements
22
30
 
23
- Needs Rust, bun, Docker, and `cargo install sqlx-cli --no-default-features --features postgres,rustls`.
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
- cp .env.example .env
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
- (cd web && bun install)
30
- (cd server && cargo run) # API on :3000
31
- (cd web && bun run dev) # UI on :5173, /api proxied to :3000
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
- ## Daily commands
57
+ ## Commands
37
58
 
38
- | Command | What it does |
39
- |---|---|
40
- | `scripts/check.sh` | The definition of done (fmt, clippy, contract drift, typecheck, `.sqlx`, tests) |
41
- | `scripts/smoke.sh` | Builds everything, runs the real binary, checks pages and API over HTTP |
42
- | `cd web && bun run gen` | Regenerate `openapi.json` and the TS client after changing a handler |
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
- ## SEO pages vs the app
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
- Pages listed in `prerender` (`web/react-router.config.ts`) are rendered to HTML at build time, so
47
- search engines see their content. Every other route is a SPA behind the same server. Prerendered
48
- pages must not call the API at build time in v0.
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=... server/target/release/server
103
+ WEB_DIST=web/build/client DATABASE_URL=postgres://... server/target/release/server
56
104
  ```
57
105
 
58
- See `AGENTS.md` for the rules agents follow in this repo.
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