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.
- package/LICENSE +21 -0
- package/README.md +113 -2
- package/index.ts +48 -0
- package/package.json +34 -4
- package/scaffold.ts +89 -0
- package/template/.env.example +3 -0
- package/template/.github/workflows/ci.yml +38 -0
- package/template/AGENTS.md +44 -0
- package/template/CLAUDE.md +1 -0
- package/template/LICENSE +21 -0
- package/template/README.md +114 -0
- package/template/_gitignore +7 -0
- package/template/compose.yml +17 -0
- package/template/openapi.json +137 -0
- package/template/scripts/check.sh +49 -0
- package/template/scripts/smoke.sh +31 -0
- package/template/server/.sqlx/query-2abc65ebb76339a9d9a9d09820c9cdd6ceba212593a9641b80cda81df39e2fed.json +64 -0
- package/template/server/.sqlx/query-4713cdeecf4c3beeef699a78fc6f52857ba3a8f357565ba00d1d97095057e0f5.json +62 -0
- package/template/server/Cargo.lock +2135 -0
- package/template/server/Cargo.toml +34 -0
- package/template/server/clippy.toml +2 -0
- package/template/server/migrations/0001_todos.sql +6 -0
- package/template/server/src/bin/openapi.rs +4 -0
- package/template/server/src/health.rs +15 -0
- package/template/server/src/lib.rs +80 -0
- package/template/server/src/main.rs +22 -0
- package/template/server/src/todos.rs +94 -0
- package/template/server/tests/health.rs +31 -0
- package/template/server/tests/todos.rs +83 -0
- package/template/web/_gitignore +7 -0
- package/template/web/app/api/@tanstack/react-query.gen.ts +84 -0
- package/template/web/app/api/client/client.gen.ts +277 -0
- package/template/web/app/api/client/index.ts +27 -0
- package/template/web/app/api/client/types.gen.ts +218 -0
- package/template/web/app/api/client/utils.gen.ts +316 -0
- package/template/web/app/api/client.gen.ts +16 -0
- package/template/web/app/api/core/auth.gen.ts +48 -0
- package/template/web/app/api/core/bodySerializer.gen.ts +82 -0
- package/template/web/app/api/core/params.gen.ts +178 -0
- package/template/web/app/api/core/pathSerializer.gen.ts +171 -0
- package/template/web/app/api/core/queryKeySerializer.gen.ts +117 -0
- package/template/web/app/api/core/serverSentEvents.gen.ts +242 -0
- package/template/web/app/api/core/types.gen.ts +110 -0
- package/template/web/app/api/core/utils.gen.ts +140 -0
- package/template/web/app/api/index.ts +4 -0
- package/template/web/app/api/sdk.gen.ts +32 -0
- package/template/web/app/api/types.gen.ts +74 -0
- package/template/web/app/app.css +15 -0
- package/template/web/app/root.tsx +82 -0
- package/template/web/app/routes/home.tsx +21 -0
- package/template/web/app/routes/todos.tsx +47 -0
- package/template/web/app/routes.ts +6 -0
- package/template/web/bun.lock +572 -0
- package/template/web/openapi-ts.config.ts +11 -0
- package/template/web/package.json +30 -0
- package/template/web/public/favicon.ico +0 -0
- package/template/web/react-router.config.ts +7 -0
- package/template/web/tsconfig.json +26 -0
- 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
|
-
#
|
|
1
|
+
# RR stack
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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,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
|
package/template/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.
|
|
@@ -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,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:
|