create-rr-stack 0.0.0-stage → 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.
Files changed (59) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +113 -2
  3. package/index.ts +48 -0
  4. package/package.json +34 -4
  5. package/scaffold.ts +89 -0
  6. package/template/.env.example +3 -0
  7. package/template/.github/workflows/ci.yml +38 -0
  8. package/template/AGENTS.md +44 -0
  9. package/template/CLAUDE.md +1 -0
  10. package/template/LICENSE +21 -0
  11. package/template/README.md +114 -0
  12. package/template/_gitignore +7 -0
  13. package/template/compose.yml +17 -0
  14. package/template/openapi.json +137 -0
  15. package/template/scripts/check.sh +49 -0
  16. package/template/scripts/smoke.sh +31 -0
  17. package/template/server/.sqlx/query-2abc65ebb76339a9d9a9d09820c9cdd6ceba212593a9641b80cda81df39e2fed.json +64 -0
  18. package/template/server/.sqlx/query-4713cdeecf4c3beeef699a78fc6f52857ba3a8f357565ba00d1d97095057e0f5.json +62 -0
  19. package/template/server/Cargo.lock +2135 -0
  20. package/template/server/Cargo.toml +34 -0
  21. package/template/server/clippy.toml +2 -0
  22. package/template/server/migrations/0001_todos.sql +6 -0
  23. package/template/server/src/bin/openapi.rs +4 -0
  24. package/template/server/src/health.rs +15 -0
  25. package/template/server/src/lib.rs +80 -0
  26. package/template/server/src/main.rs +22 -0
  27. package/template/server/src/todos.rs +94 -0
  28. package/template/server/tests/health.rs +31 -0
  29. package/template/server/tests/todos.rs +83 -0
  30. package/template/web/_gitignore +7 -0
  31. package/template/web/app/api/@tanstack/react-query.gen.ts +84 -0
  32. package/template/web/app/api/client/client.gen.ts +277 -0
  33. package/template/web/app/api/client/index.ts +27 -0
  34. package/template/web/app/api/client/types.gen.ts +218 -0
  35. package/template/web/app/api/client/utils.gen.ts +316 -0
  36. package/template/web/app/api/client.gen.ts +16 -0
  37. package/template/web/app/api/core/auth.gen.ts +48 -0
  38. package/template/web/app/api/core/bodySerializer.gen.ts +82 -0
  39. package/template/web/app/api/core/params.gen.ts +178 -0
  40. package/template/web/app/api/core/pathSerializer.gen.ts +171 -0
  41. package/template/web/app/api/core/queryKeySerializer.gen.ts +117 -0
  42. package/template/web/app/api/core/serverSentEvents.gen.ts +242 -0
  43. package/template/web/app/api/core/types.gen.ts +110 -0
  44. package/template/web/app/api/core/utils.gen.ts +140 -0
  45. package/template/web/app/api/index.ts +4 -0
  46. package/template/web/app/api/sdk.gen.ts +32 -0
  47. package/template/web/app/api/types.gen.ts +74 -0
  48. package/template/web/app/app.css +15 -0
  49. package/template/web/app/root.tsx +82 -0
  50. package/template/web/app/routes/home.tsx +21 -0
  51. package/template/web/app/routes/todos.tsx +47 -0
  52. package/template/web/app/routes.ts +6 -0
  53. package/template/web/bun.lock +572 -0
  54. package/template/web/openapi-ts.config.ts +11 -0
  55. package/template/web/package.json +30 -0
  56. package/template/web/public/favicon.ico +0 -0
  57. package/template/web/react-router.config.ts +7 -0
  58. package/template/web/tsconfig.json +26 -0
  59. package/template/web/vite.config.ts +13 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jintaphas Thammabuth
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,114 @@
1
- # Temporary Holding Version
1
+ # RR stack
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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/index.ts ADDED
@@ -0,0 +1,48 @@
1
+ #!/usr/bin/env bun
2
+ import { existsSync, mkdtempSync } from "node:fs";
3
+ import { tmpdir } from "node:os";
4
+ import { join, resolve } from "node:path";
5
+ import { buildTemplate, scaffold, validateName } from "./scaffold";
6
+
7
+ const args = process.argv.slice(2);
8
+ const flags = new Set(args.filter((a) => a.startsWith("--")));
9
+ const name = args.find((a) => !a.startsWith("--")) ?? prompt("Project name:")?.trim() ?? "";
10
+
11
+ const problem = validateName(name);
12
+ if (problem) {
13
+ console.error(`create-rr-stack: invalid name "${name}": ${problem}`);
14
+ process.exit(1);
15
+ }
16
+
17
+ const dest = resolve(process.cwd(), name);
18
+ try {
19
+ // The npm package ships template/ (built by prepack); a git checkout builds it on the fly.
20
+ let source = join(import.meta.dir, "template");
21
+ if (!existsSync(source)) {
22
+ source = join(mkdtempSync(join(tmpdir(), "rr-template-")), "t");
23
+ await buildTemplate(resolve(import.meta.dir, ".."), source);
24
+ }
25
+ await scaffold({ name, dest, source });
26
+ } catch (err) {
27
+ console.error(`create-rr-stack: ${(err as Error).message}`);
28
+ process.exit(1);
29
+ }
30
+
31
+ const run = (cmd: string[], cwd: string) => {
32
+ const { exitCode } = Bun.spawnSync(cmd, { cwd, stdout: "inherit", stderr: "inherit" });
33
+ if (exitCode !== 0) {
34
+ console.error(`create-rr-stack: \`${cmd.join(" ")}\` failed in ${cwd}. The project is created; rerun that command there.`);
35
+ process.exit(1);
36
+ }
37
+ };
38
+ if (!flags.has("--no-install")) run(["bun", "install"], resolve(dest, "web"));
39
+ if (!flags.has("--no-git")) run(["git", "init", "-q", "-b", "main"], dest);
40
+
41
+ console.log(`
42
+ Created ${name}. Next:
43
+ cd ${name}
44
+ docker compose up -d --wait
45
+ (cd server && sqlx migrate run)
46
+ scripts/check.sh
47
+ (cd server && cargo run) & (cd web && bun run dev)
48
+ Then read AGENTS.md before you (or your agent) write code.`);
package/package.json CHANGED
@@ -1,6 +1,36 @@
1
1
  {
2
2
  "name": "create-rr-stack",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "type": "module",
5
+ "bin": {
6
+ "create-rr-stack": "index.ts"
7
+ },
8
+ "scripts": {
9
+ "test": "bun test",
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
+ },
13
+ "description": "Scaffold a React Router + Rust (Axum) app that is typed from the database to the screen.",
14
+ "license": "MIT",
15
+ "keywords": [
16
+ "create",
17
+ "react",
18
+ "rust",
19
+ "axum",
20
+ "react-router",
21
+ "openapi",
22
+ "typesafe",
23
+ "bun"
24
+ ],
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/Useless007/rr-stack.git",
28
+ "directory": "cli"
29
+ },
30
+ "homepage": "https://github.com/Useless007/rr-stack#readme",
31
+ "files": [
32
+ "index.ts",
33
+ "scaffold.ts",
34
+ "template"
35
+ ]
36
+ }
package/scaffold.ts ADDED
@@ -0,0 +1,89 @@
1
+ import { execFileSync } from "node:child_process";
2
+ import { existsSync } from "node:fs";
3
+ import { copyFile, mkdir, readdir, readFile, rename, writeFile } from "node:fs/promises";
4
+ import { dirname, join } from "node:path";
5
+
6
+ /** Returns null when the name is usable as a directory, Cargo package and npm package; else why not. */
7
+ export function validateName(name: string): string | null {
8
+ if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
9
+ return "use lowercase letters, digits and dashes, starting with a letter (max 64)";
10
+ }
11
+ if (name.endsWith("-")) return "must not end with a dash";
12
+ return null;
13
+ }
14
+
15
+ /** A stable host port in 54000..54999 so two projects' databases can run side by side. */
16
+ export function dbPort(name: string): number {
17
+ let hash = 0x811c9dc5;
18
+ for (const ch of name) hash = Math.imul(hash ^ ch.charCodeAt(0), 0x01000193) >>> 0;
19
+ return 54000 + (hash % 1000);
20
+ }
21
+
22
+ // Tracked in the template repo but not part of a new project.
23
+ const SKIP_TOP = new Set(["cli", "docs"]);
24
+ // npm never ships files named .gitignore, so the template stores them under this name.
25
+ const GITIGNORE = "_gitignore";
26
+
27
+ /** Writes the project template (only files git tracks in `repo`) into `out`, ready to ship in the npm package. */
28
+ export async function buildTemplate(repo: string, out: string): Promise<void> {
29
+ const files = execFileSync("git", ["ls-files", "-z"], { cwd: repo, encoding: "utf8" })
30
+ .split("\0")
31
+ .filter((f) => f && !SKIP_TOP.has(f.split("/")[0] ?? "") && existsSync(join(repo, f)));
32
+ for (const file of files) {
33
+ const target = join(out, file.replace(/(^|\/)\.gitignore$/, `$1${GITIGNORE}`));
34
+ await mkdir(dirname(target), { recursive: true });
35
+ await copyFile(join(repo, file), target);
36
+ }
37
+ }
38
+
39
+ export async function scaffold(opts: { name: string; dest: string; source: string }): Promise<void> {
40
+ const { name, dest, source } = opts;
41
+ const existing = await readdir(dest).catch(() => []);
42
+ if (existing.length > 0) throw new Error(`${dest} is not empty`);
43
+
44
+ for (const file of await readdir(source, { recursive: true, withFileTypes: true })) {
45
+ if (!file.isFile()) continue;
46
+ const from = join(file.parentPath, file.name);
47
+ const to = join(dest, from.slice(source.length + 1));
48
+ await mkdir(dirname(to), { recursive: true });
49
+ await copyFile(from, to);
50
+ if (file.name === GITIGNORE) await rename(to, join(dirname(to), ".gitignore"));
51
+ }
52
+
53
+ const crate = `name = "${name}-server"`;
54
+ await edit(join(dest, "server/Cargo.toml"), (s) => must(s, ['name = "rr-server"']).replace('name = "rr-server"', crate));
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`));
57
+ await edit(join(dest, "web/package.json"), (s) => {
58
+ const pkg = JSON.parse(s);
59
+ pkg.name = `${name}-web`;
60
+ return `${JSON.stringify(pkg, null, 2)}\n`;
61
+ });
62
+
63
+ const db = name.replaceAll("-", "_");
64
+ const port = dbPort(name);
65
+ await edit(join(dest, "compose.yml"), (s) =>
66
+ must(s, ["POSTGRES_USER: rr", "POSTGRES_PASSWORD: rr", "POSTGRES_DB: rr", "pg_isready -U rr", "127.0.0.1:5432:5432"])
67
+ .replace("POSTGRES_USER: rr", `POSTGRES_USER: ${db}`)
68
+ .replace("POSTGRES_PASSWORD: rr", `POSTGRES_PASSWORD: ${db}`)
69
+ .replace("POSTGRES_DB: rr", `POSTGRES_DB: ${db}`)
70
+ .replace("pg_isready -U rr", `pg_isready -U ${db}`)
71
+ .replace("127.0.0.1:5432:5432", `127.0.0.1:${port}:5432`),
72
+ );
73
+ const dbUrl = "postgres://rr:rr@localhost:5432/rr";
74
+ await edit(join(dest, ".env.example"), (s) =>
75
+ must(s, [dbUrl]).replace(dbUrl, `postgres://${db}:${db}@localhost:${port}/${db}`),
76
+ );
77
+ await writeFile(join(dest, ".env"), await readFile(join(dest, ".env.example"), "utf8"));
78
+ }
79
+
80
+ async function edit(path: string, change: (text: string) => string): Promise<void> {
81
+ await writeFile(path, change(await readFile(path, "utf8")));
82
+ }
83
+
84
+ // Fails loudly if the template changed under the CLI instead of producing a half-renamed project.
85
+ function must(text: string, needles: string[]): string {
86
+ const missing = needles.filter((n) => !text.includes(n));
87
+ if (missing.length > 0) throw new Error(`template changed, cannot find: ${missing.join(", ")}`);
88
+ return text;
89
+ }
@@ -0,0 +1,3 @@
1
+ DATABASE_URL=postgres://rr:rr@localhost:5432/rr
2
+ PORT=3000
3
+ WEB_DIST=../web/build/client
@@ -0,0 +1,38 @@
1
+ name: ci
2
+ on:
3
+ push:
4
+ pull_request:
5
+
6
+ jobs:
7
+ check:
8
+ runs-on: ubuntu-latest
9
+ services:
10
+ db:
11
+ image: postgres:18-alpine
12
+ env:
13
+ POSTGRES_USER: rr
14
+ POSTGRES_PASSWORD: rr
15
+ POSTGRES_DB: rr
16
+ ports: ["5432:5432"]
17
+ options: >-
18
+ --health-cmd "pg_isready -U rr" --health-interval 2s --health-retries 30
19
+ env:
20
+ DATABASE_URL: postgres://rr:rr@localhost:5432/rr
21
+ steps:
22
+ - uses: actions/checkout@v4
23
+ - uses: dtolnay/rust-toolchain@stable
24
+ with:
25
+ components: clippy, rustfmt
26
+ - uses: oven-sh/setup-bun@v2
27
+ - uses: Swatinem/rust-cache@v2
28
+ with:
29
+ workspaces: server
30
+ cache-all-crates: true
31
+ - run: cargo install sqlx-cli --locked --no-default-features --features postgres,rustls
32
+ - run: bun install --frozen-lockfile
33
+ working-directory: web
34
+ - name: build with no database (offline .sqlx/)
35
+ run: env -u DATABASE_URL SQLX_OFFLINE=true cargo build --all-targets
36
+ working-directory: server
37
+ - run: scripts/check.sh
38
+ - run: scripts/smoke.sh
@@ -0,0 +1,44 @@
1
+ # Working in this repo
2
+
3
+ React (React Router, `web/`) + Rust (Axum, `server/`), typed end to end through `openapi.json`.
4
+
5
+ ## Definition of done
6
+
7
+ - Run `scripts/check.sh` and read its output. Exit 0 is the only "done".
8
+ - Changed how the server serves pages or files? Also run `scripts/smoke.sh`.
9
+ - Do not claim success from "it compiles" or from reading the diff.
10
+
11
+ ## Never edit these by hand
12
+
13
+ They are generated. `check.sh` fails if they differ from a fresh generation.
14
+
15
+ - `openapi.json` — from the Rust handlers (`cargo run --bin openapi`)
16
+ - `web/app/api/**` — from `openapi.json` (`cd web && bun run gen`)
17
+ - `server/.sqlx/**` — from the SQL in `query!` macros (`cd server && cargo sqlx prepare -- --all-targets`)
18
+
19
+ ## Where each type comes from
20
+
21
+ | Layer | Source of truth |
22
+ |---|---|
23
+ | Database | `server/migrations/*.sql` |
24
+ | Wire (JSON) | Rust structs deriving `ToSchema` in `server/src/` |
25
+ | TypeScript | `~/api` only. Never hand-write a type that crosses the wire. |
26
+
27
+ ## Add an endpoint
28
+
29
+ 1. Write the handler with `#[utoipa::path(..., operation_id = "camelCaseName")]` in `server/src/<domain>.rs`.
30
+ 2. Register it in `api_router()` in `server/src/lib.rs` with `routes!`.
31
+ 3. Add an integration test in `server/tests/` (`#[sqlx::test]` gives a fresh database).
32
+ 4. `cd web && bun run gen`, then use the generated `<name>Options()` / `<name>Mutation()` from `~/api/@tanstack/react-query.gen`.
33
+ 5. New SQL? `cargo sqlx prepare -- --all-targets` and commit `.sqlx/`.
34
+
35
+ ## Rules
36
+
37
+ - Validate at the boundary with a newtype (see `TodoTitle`): parse once, trust the type inside.
38
+ `#[schema(max_length = ...)]` only documents; it does not enforce.
39
+ - No `unwrap`/`expect` outside tests (clippy denies it). Return `AppError`.
40
+ - Keep Rust plain: no custom macros, no generic abstraction layers. A human must be able to
41
+ debug it when you get stuck.
42
+ - New public page that search engines must see? Add its path to `prerender` in
43
+ `web/react-router.config.ts`. Everything else is SPA.
44
+ - New migration: a new numbered file. Never edit one that is committed.
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jintaphas Thammabuth
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -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
@@ -0,0 +1,7 @@
1
+ .env
2
+ target/
3
+ node_modules/
4
+ build/
5
+ .react-router/
6
+ .superpowers/
7
+ .omc/
@@ -0,0 +1,17 @@
1
+ services:
2
+ db:
3
+ image: postgres:18-alpine
4
+ environment:
5
+ POSTGRES_USER: rr
6
+ POSTGRES_PASSWORD: rr
7
+ POSTGRES_DB: rr
8
+ ports:
9
+ - "127.0.0.1:5432:5432"
10
+ volumes:
11
+ - pgdata:/var/lib/postgresql
12
+ healthcheck:
13
+ test: ["CMD-SHELL", "pg_isready -U rr"]
14
+ interval: 2s
15
+ retries: 30
16
+ volumes:
17
+ pgdata: