create-rr-stack 0.0.0-stage → 0.1.0
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/index.ts +48 -0
- package/package.json +34 -4
- package/scaffold.ts +88 -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 +58 -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/README.md +0 -3
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/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.0",
|
|
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 LICENSE",
|
|
11
|
+
"postpack": "rm -rf template LICENSE"
|
|
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,88 @@
|
|
|
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, "web/package.json"), (s) => {
|
|
57
|
+
const pkg = JSON.parse(s);
|
|
58
|
+
pkg.name = `${name}-web`;
|
|
59
|
+
return `${JSON.stringify(pkg, null, 2)}\n`;
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
const db = name.replaceAll("-", "_");
|
|
63
|
+
const port = dbPort(name);
|
|
64
|
+
await edit(join(dest, "compose.yml"), (s) =>
|
|
65
|
+
must(s, ["POSTGRES_USER: rr", "POSTGRES_PASSWORD: rr", "POSTGRES_DB: rr", "pg_isready -U rr", "127.0.0.1:5432:5432"])
|
|
66
|
+
.replace("POSTGRES_USER: rr", `POSTGRES_USER: ${db}`)
|
|
67
|
+
.replace("POSTGRES_PASSWORD: rr", `POSTGRES_PASSWORD: ${db}`)
|
|
68
|
+
.replace("POSTGRES_DB: rr", `POSTGRES_DB: ${db}`)
|
|
69
|
+
.replace("pg_isready -U rr", `pg_isready -U ${db}`)
|
|
70
|
+
.replace("127.0.0.1:5432:5432", `127.0.0.1:${port}:5432`),
|
|
71
|
+
);
|
|
72
|
+
const dbUrl = "postgres://rr:rr@localhost:5432/rr";
|
|
73
|
+
await edit(join(dest, ".env.example"), (s) =>
|
|
74
|
+
must(s, [dbUrl]).replace(dbUrl, `postgres://${db}:${db}@localhost:${port}/${db}`),
|
|
75
|
+
);
|
|
76
|
+
await writeFile(join(dest, ".env"), await readFile(join(dest, ".env.example"), "utf8"));
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
async function edit(path: string, change: (text: string) => string): Promise<void> {
|
|
80
|
+
await writeFile(path, change(await readFile(path, "utf8")));
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// Fails loudly if the template changed under the CLI instead of producing a half-renamed project.
|
|
84
|
+
function must(text: string, needles: string[]): string {
|
|
85
|
+
const missing = needles.filter((n) => !text.includes(n));
|
|
86
|
+
if (missing.length > 0) throw new Error(`template changed, cannot find: ${missing.join(", ")}`);
|
|
87
|
+
return text;
|
|
88
|
+
}
|
|
@@ -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,58 @@
|
|
|
1
|
+
# RR stack
|
|
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
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
bun create rr-stack my-app # add --no-install or --no-git to skip those steps
|
|
14
|
+
```
|
|
15
|
+
|
|
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`.
|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
Needs Rust, bun, Docker, and `cargo install sqlx-cli --no-default-features --features postgres,rustls`.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
cp .env.example .env
|
|
27
|
+
docker compose up -d --wait
|
|
28
|
+
(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
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Open http://localhost:5173 and http://localhost:5173/app/todos.
|
|
35
|
+
|
|
36
|
+
## Daily commands
|
|
37
|
+
|
|
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 |
|
|
43
|
+
|
|
44
|
+
## SEO pages vs the app
|
|
45
|
+
|
|
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.
|
|
49
|
+
|
|
50
|
+
## Production
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
(cd web && bun run build)
|
|
54
|
+
(cd server && cargo build --release)
|
|
55
|
+
WEB_DIST=web/build/client DATABASE_URL=... server/target/release/server
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
See `AGENTS.md` for the rules agents follow in this repo.
|
|
@@ -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:
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
{
|
|
2
|
+
"openapi": "3.1.0",
|
|
3
|
+
"info": {
|
|
4
|
+
"title": "utoipa-axum",
|
|
5
|
+
"description": "Utoipa's axum bindings for seamless integration for the two",
|
|
6
|
+
"contact": {
|
|
7
|
+
"name": "Juha Kukkonen",
|
|
8
|
+
"email": "juha7kukkonen@gmail.com"
|
|
9
|
+
},
|
|
10
|
+
"license": {
|
|
11
|
+
"name": "MIT OR Apache-2.0",
|
|
12
|
+
"identifier": "MIT OR Apache-2.0"
|
|
13
|
+
},
|
|
14
|
+
"version": "0.3.0"
|
|
15
|
+
},
|
|
16
|
+
"paths": {
|
|
17
|
+
"/api/health": {
|
|
18
|
+
"get": {
|
|
19
|
+
"operationId": "health",
|
|
20
|
+
"responses": {
|
|
21
|
+
"200": {
|
|
22
|
+
"content": {
|
|
23
|
+
"application/json": {
|
|
24
|
+
"schema": {
|
|
25
|
+
"$ref": "#/components/schemas/Health"
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"/api/todos": {
|
|
34
|
+
"get": {
|
|
35
|
+
"operationId": "listTodos",
|
|
36
|
+
"responses": {
|
|
37
|
+
"200": {
|
|
38
|
+
"content": {
|
|
39
|
+
"application/json": {
|
|
40
|
+
"schema": {
|
|
41
|
+
"type": "array",
|
|
42
|
+
"items": {
|
|
43
|
+
"$ref": "#/components/schemas/Todo"
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
},
|
|
51
|
+
"post": {
|
|
52
|
+
"operationId": "createTodo",
|
|
53
|
+
"requestBody": {
|
|
54
|
+
"content": {
|
|
55
|
+
"application/json": {
|
|
56
|
+
"schema": {
|
|
57
|
+
"$ref": "#/components/schemas/NewTodo"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
"required": true
|
|
62
|
+
},
|
|
63
|
+
"responses": {
|
|
64
|
+
"201": {
|
|
65
|
+
"content": {
|
|
66
|
+
"application/json": {
|
|
67
|
+
"schema": {
|
|
68
|
+
"$ref": "#/components/schemas/Todo"
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
"422": {
|
|
74
|
+
"description": "title is empty or longer than 200 characters"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
},
|
|
80
|
+
"components": {
|
|
81
|
+
"schemas": {
|
|
82
|
+
"Health": {
|
|
83
|
+
"type": "object",
|
|
84
|
+
"required": [
|
|
85
|
+
"status"
|
|
86
|
+
],
|
|
87
|
+
"properties": {
|
|
88
|
+
"status": {
|
|
89
|
+
"type": "string"
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
},
|
|
93
|
+
"NewTodo": {
|
|
94
|
+
"type": "object",
|
|
95
|
+
"required": [
|
|
96
|
+
"title"
|
|
97
|
+
],
|
|
98
|
+
"properties": {
|
|
99
|
+
"title": {
|
|
100
|
+
"$ref": "#/components/schemas/TodoTitle"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
},
|
|
104
|
+
"Todo": {
|
|
105
|
+
"type": "object",
|
|
106
|
+
"required": [
|
|
107
|
+
"id",
|
|
108
|
+
"title",
|
|
109
|
+
"done",
|
|
110
|
+
"created_at"
|
|
111
|
+
],
|
|
112
|
+
"properties": {
|
|
113
|
+
"created_at": {
|
|
114
|
+
"type": "string",
|
|
115
|
+
"description": "RFC 3339 timestamp."
|
|
116
|
+
},
|
|
117
|
+
"done": {
|
|
118
|
+
"type": "boolean"
|
|
119
|
+
},
|
|
120
|
+
"id": {
|
|
121
|
+
"type": "integer",
|
|
122
|
+
"format": "int64"
|
|
123
|
+
},
|
|
124
|
+
"title": {
|
|
125
|
+
"type": "string"
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
},
|
|
129
|
+
"TodoTitle": {
|
|
130
|
+
"type": "string",
|
|
131
|
+
"description": "A title that is already trimmed and 1..=200 characters; it cannot be built any other way.",
|
|
132
|
+
"maxLength": 200,
|
|
133
|
+
"minLength": 1
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# The definition of done. Exit 0 means SQL, Rust, the OpenAPI contract and the React code agree.
|
|
3
|
+
set -euo pipefail
|
|
4
|
+
root="$(cd "$(dirname "$0")/.." && pwd)"
|
|
5
|
+
[ -f "$root/.env" ] && { set -a; . "$root/.env"; set +a; }
|
|
6
|
+
export SQLX_OFFLINE=true
|
|
7
|
+
step() { printf '\n== %s\n' "$*"; }
|
|
8
|
+
|
|
9
|
+
cd "$root/server"
|
|
10
|
+
step "rustfmt"
|
|
11
|
+
cargo fmt --check
|
|
12
|
+
step "clippy (offline SQL metadata from .sqlx/)"
|
|
13
|
+
cargo clippy -q --all-targets -- -D warnings
|
|
14
|
+
|
|
15
|
+
step "contract: openapi.json and web/app/api match a fresh generation"
|
|
16
|
+
tmp="$(mktemp -d)"
|
|
17
|
+
trap 'rm -rf "$tmp"' EXIT
|
|
18
|
+
cargo run -q --bin openapi > "$tmp/openapi.json"
|
|
19
|
+
(cd "$root/web" && RR_OPENAPI="$tmp/openapi.json" RR_API_OUT="$tmp/api" bunx openapi-ts >/dev/null)
|
|
20
|
+
if ! diff -q "$root/openapi.json" "$tmp/openapi.json" >/dev/null || ! diff -rq "$root/web/app/api" "$tmp/api" >/dev/null; then
|
|
21
|
+
diff -ru "$root/openapi.json" "$tmp/openapi.json" | head -20 || true
|
|
22
|
+
diff -rq "$root/web/app/api" "$tmp/api" || true
|
|
23
|
+
echo "generated files are stale or hand-edited: run 'cd web && bun run gen' and commit" >&2
|
|
24
|
+
exit 1
|
|
25
|
+
fi
|
|
26
|
+
|
|
27
|
+
step "typecheck"
|
|
28
|
+
(cd "$root/web" && bun run typecheck >/dev/null)
|
|
29
|
+
step "web build (prerendered pages render)"
|
|
30
|
+
(cd "$root/web" && bun run build >/dev/null)
|
|
31
|
+
|
|
32
|
+
if [ -n "${DATABASE_URL:-}" ]; then
|
|
33
|
+
command -v sqlx >/dev/null || { echo "sqlx-cli missing: cargo install sqlx-cli --no-default-features --features postgres,rustls" >&2; exit 1; }
|
|
34
|
+
step "migrations + .sqlx/ up to date"
|
|
35
|
+
sqlx migrate run >/dev/null
|
|
36
|
+
cargo sqlx prepare --check -- --all-targets
|
|
37
|
+
step "tests"
|
|
38
|
+
cargo test -q
|
|
39
|
+
elif [ "${SKIP_DB:-}" = 1 ]; then
|
|
40
|
+
echo "SKIP_DB=1: skipped .sqlx check and tests. This is NOT done."
|
|
41
|
+
else
|
|
42
|
+
echo "DATABASE_URL is not set: start the DB (docker compose up -d --wait) or set SKIP_DB=1 for a partial check" >&2
|
|
43
|
+
exit 1
|
|
44
|
+
fi
|
|
45
|
+
if [ -d "$root/cli" ]; then
|
|
46
|
+
step "cli tests"
|
|
47
|
+
(cd "$root/cli" && bun test 2>&1 | tail -3)
|
|
48
|
+
fi
|
|
49
|
+
echo; echo "check OK"
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Builds the web app, runs the real server binary, and checks what a browser and an API client get.
|
|
3
|
+
set -euo pipefail
|
|
4
|
+
root="$(cd "$(dirname "$0")/.." && pwd)"
|
|
5
|
+
[ -f "$root/.env" ] && { set -a; . "$root/.env"; set +a; }
|
|
6
|
+
: "${DATABASE_URL:?DATABASE_URL must be set (cp .env.example .env)}"
|
|
7
|
+
|
|
8
|
+
(cd "$root/web" && bun run build >/dev/null 2>&1)
|
|
9
|
+
(cd "$root/server" && cargo build -q --bin server)
|
|
10
|
+
|
|
11
|
+
port="$(python3 -c 'import socket; s=socket.socket(); s.bind(("127.0.0.1",0)); print(s.getsockname()[1])')"
|
|
12
|
+
PORT="$port" WEB_DIST="$root/web/build/client" "$root/server/target/debug/server" >/dev/null 2>&1 &
|
|
13
|
+
pid=$!
|
|
14
|
+
trap 'kill "$pid" 2>/dev/null || true' EXIT
|
|
15
|
+
base="http://127.0.0.1:$port"
|
|
16
|
+
for _ in $(seq 50); do curl -sf "$base/api/health" >/dev/null && break; sleep 0.2; done
|
|
17
|
+
|
|
18
|
+
fail() { echo "smoke FAIL: $*" >&2; exit 1; }
|
|
19
|
+
expect() { # expect <status> <method> <path> [body]
|
|
20
|
+
local out; out="$(mktemp)"
|
|
21
|
+
local code; code="$(curl -s -o "$out" -w '%{http_code} %{content_type}' -X "$2" -H 'content-type: application/json' ${4:+--data "$4"} "$base$3")"
|
|
22
|
+
[[ "${code%% *}" == "$1" ]] || fail "$2 $3 → $code, want $1"
|
|
23
|
+
cat "$out"; rm -f "$out"
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
expect 200 GET / | grep -q 'RR stack</h1>' || fail "/ is not the prerendered landing page"
|
|
27
|
+
expect 200 GET /app/todos | grep -q '<script' || fail "/app/todos did not return the SPA fallback"
|
|
28
|
+
curl -s -o /dev/null -w '%{content_type}' "$base/api/nope" | grep -q '^application/json' || fail "/api/nope is not JSON"
|
|
29
|
+
expect 404 GET /api/nope >/dev/null
|
|
30
|
+
expect 201 POST /api/todos '{"title":"smoke"}' >/dev/null
|
|
31
|
+
echo "smoke OK"
|