create-rango 0.1.0

package/index.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Layout is selected explicitly, not by probing: installed under any package
+// manager the CLI lives inside a node_modules tree and MUST use the templates
+// bundled by prepack; running from the repo it MUST use the source templates
+// two levels up (a leftover ./templates snapshot from a local pack would
+// otherwise silently shadow them).
+const IS_INSTALLED = __dirname.split(path.sep).includes("node_modules");
+const TEMPLATES_ROOT = IS_INSTALLED
+  ? path.join(__dirname, "templates")
+  : path.join(__dirname, "../../templates");
+
+const TEMPLATES = [
+  {
+    name: "basic",
+    label: "Basic",
+    hint: "Vite + RSC, deploy to any Node host",
+    jsFlavor: true,
+  },
+  {
+    name: "cloudflare",
+    label: "Cloudflare Workers",
+    hint: "Cloudflare Vite plugin + wrangler",
+  },
+  {
+    name: "vercel",
+    label: "Vercel",
+    hint: "Build Output API, deploy with `vercel deploy --prebuilt`",
+  },
+];
+
+const PACKAGE_MANAGERS = ["npm", "pnpm"];
+
+const HELP = `create-rango — scaffold a Rango (@rangojs/router) app
+
+Usage:
+  create-rango [directory] [options]
+
+Options:
+  -t, --template <name>  ${TEMPLATES.map((t) => t.name).join(" | ")}
+  --js                   JavaScript flavor (basic template only)
+  --ts                   TypeScript flavor (default)
+  --package-manager <pm> npm | pnpm
+  --overwrite            scaffold into a non-empty directory
+  -h, --help             show this help
+  -v, --version          show the create-rango version
+
+Examples:
+  npm create rango@latest my-app
+  pnpm create rango my-app --template cloudflare
+  npm create rango@latest my-app -- --package-manager npm
+  pnpm create rango my-app -t basic --js
+`;
+
+function parseArgs(argv) {
+  const args = {
+    dir: undefined,
+    template: undefined,
+    lang: undefined,
+    packageManager: undefined,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") args.help = true;
+    else if (arg === "-v" || arg === "--version") args.version = true;
+    else if (arg === "-t" || arg === "--template") {
+      args.template = argv[++i];
+      if (!args.template) fail(`${arg} requires a value`);
+    } else if (arg.startsWith("--template=")) {
+      args.template = arg.slice("--template=".length);
+    } else if (arg === "--package-manager") {
+      args.packageManager = argv[++i];
+      if (!args.packageManager) fail(`${arg} requires a value`);
+    } else if (arg.startsWith("--package-manager=")) {
+      args.packageManager = arg.slice("--package-manager=".length);
+    } else if (arg === "--js") args.lang = "js";
+    else if (arg === "--ts") args.lang = "ts";
+    else if (arg === "--overwrite") args.overwrite = true;
+    else if (arg.startsWith("-")) fail(`Unknown option: ${arg}`);
+    else if (args.dir === undefined) args.dir = arg;
+    else fail(`Unexpected argument: ${arg}`);
+  }
+  return args;
+}
+
+function fail(message) {
+  console.error(`create-rango: ${message}\n\nRun create-rango --help.`);
+  process.exit(1);
+}
+
+function bail(value, message = "Cancelled.") {
+  if (p.isCancel(value)) {
+    p.cancel(message);
+    process.exit(1);
+  }
+  return value;
+}
+
+// Names npm rejects outright (validate-npm-package-name blacklist).
+const RESERVED_PACKAGE_NAMES = new Set(["node_modules", "favicon.ico"]);
+
+function toValidPackageName(name) {
+  const valid = name
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/^[-._]+/, "")
+    .replace(/[^a-z0-9-~._]+/g, "-")
+    .slice(0, 214);
+  if (!valid || RESERVED_PACKAGE_NAMES.has(valid)) return "rango-app";
+  return valid;
+}
+
+// Cloudflare Worker names allow only [a-z0-9-] and cap at 54 chars for
+// workers.dev, stricter than npm package names (which keep _ . ~).
+function toValidWorkerName(name) {
+  const valid = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 54)
+    .replace(/-+$/, "");
+  return valid || "rango-app";
+}
+
+// Render a path for the copy-pasteable `cd` step: anchor relative paths with
+// ./ (so a leading "-" cannot parse as an option and "~" cannot expand), then
+// POSIX-quote anything outside the safe charset.
+function shellPath(value) {
+  const anchored =
+    path.isAbsolute(value) || value.startsWith(".") ? value : `./${value}`;
+  if (/^[A-Za-z0-9._/-]+$/.test(anchored)) return anchored;
+  return `'${anchored.replaceAll("'", `'\\''`)}'`;
+}
+
+function isEmptyDir(dir) {
+  const entries = fs.readdirSync(dir);
+  return (
+    entries.length === 0 || (entries.length === 1 && entries[0] === ".git")
+  );
+}
+
+function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  if (userAgent.startsWith("pnpm/")) return "pnpm";
+  return "npm";
+}
+
+// Local install/build artifacts that may exist in a template checkout (repo
+// dev, or a user re-running into the same dir) and must never be scaffolded.
+const SKIP_COPY = new Set([
+  "node_modules",
+  "dist",
+  ".wrangler",
+  ".vercel",
+  ".vite",
+  ".turbo",
+]);
+
+// Local credential files (wrangler `.dev.vars`, dotenv) must never be copied
+// into a scaffold either; mirrors scripts/sync-templates.mjs.
+function shouldSkipCopy(basename) {
+  return (
+    SKIP_COPY.has(basename) ||
+    basename.startsWith(".env") ||
+    basename.startsWith(".dev.vars")
+  );
+}
+
+function copyTemplate(templateDir, targetDir) {
+  fs.cpSync(templateDir, targetDir, {
+    recursive: true,
+    filter: (src) => !shouldSkipCopy(path.basename(src)),
+  });
+  const gitignore = path.join(targetDir, "_gitignore");
+  if (fs.existsSync(gitignore)) {
+    fs.renameSync(gitignore, path.join(targetDir, ".gitignore"));
+  }
+}
+
+function patchJsonName(file, name) {
+  if (!fs.existsSync(file)) return;
+  const source = fs.readFileSync(file, "utf8");
+  JSON.parse(source);
+  const nameProperty = /("name"\s*:\s*)"(?:\\.|[^"\\])*"/;
+  if (!nameProperty.test(source)) {
+    throw new Error(`Cannot update name in ${file}`);
+  }
+  const next = source.replace(
+    nameProperty,
+    (_match, prefix) => `${prefix}${JSON.stringify(name)}`,
+  );
+  fs.writeFileSync(file, next);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    console.log(HELP);
+    return;
+  }
+  if (args.version) {
+    const own = JSON.parse(
+      fs.readFileSync(path.join(__dirname, "package.json"), "utf8"),
+    );
+    console.log(own.version);
+    return;
+  }
+
+  p.intro("create-rango");
+
+  // engines says >=24; npm only warns on engine mismatch, so repeat it loudly
+  // for anyone who got here on an older Node (generated apps hard-require 24).
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  if (nodeMajor < 24) {
+    p.log.warn(
+      `Node ${process.versions.node} detected — create-rango and the apps it generates require Node 24+. Continuing, but installing/running the generated app will fail on this Node.`,
+    );
+  }
+
+  let dir = args.dir;
+  if (dir === undefined) {
+    dir = bail(
+      await p.text({
+        message: "Where should the app be created?",
+        placeholder: "./rango-app",
+        defaultValue: "rango-app",
+      }),
+    );
+  }
+  const targetDir = path.resolve(process.cwd(), dir);
+  const packageName = toValidPackageName(path.basename(targetDir));
+
+  // Accept both `--template cloudflare --js` and `--template cloudflare-js`.
+  let template = args.template;
+  let lang = args.lang;
+  if (template?.endsWith("-js")) {
+    template = template.slice(0, -3);
+    lang ??= "js";
+  }
+  if (template && !TEMPLATES.some((t) => t.name === template)) {
+    fail(
+      `Unknown template "${template}". Available: ${TEMPLATES.map((t) => t.name).join(", ")}`,
+    );
+  }
+  if (!template) {
+    template = bail(
+      await p.select({
+        message: "Which template?",
+        options: TEMPLATES.map((t) => ({
+          value: t.name,
+          label: t.label,
+          hint: t.hint,
+        })),
+      }),
+    );
+    if (TEMPLATES.find((t) => t.name === template)?.jsFlavor) {
+      lang ??= bail(
+        await p.select({
+          message: "TypeScript or JavaScript?",
+          options: [
+            { value: "ts", label: "TypeScript" },
+            { value: "js", label: "JavaScript" },
+          ],
+        }),
+      );
+    }
+  }
+  lang ??= "ts";
+  if (lang === "js" && !TEMPLATES.find((t) => t.name === template)?.jsFlavor) {
+    const jsTemplates = TEMPLATES.filter((t) => t.jsFlavor).map((t) => t.name);
+    fail(
+      `the JavaScript flavor is only available for: ${jsTemplates.join(", ")}`,
+    );
+  }
+
+  if (args.packageManager && !PACKAGE_MANAGERS.includes(args.packageManager)) {
+    fail(
+      `Unknown package manager "${args.packageManager}". Available: ${PACKAGE_MANAGERS.join(", ")}`,
+    );
+  }
+  let packageManager = args.packageManager ?? detectPackageManager();
+  if (!args.packageManager && process.stdin.isTTY && process.stdout.isTTY) {
+    packageManager = bail(
+      await p.select({
+        message: "Which package manager?",
+        initialValue: packageManager,
+        options: PACKAGE_MANAGERS.map((value) => ({ value, label: value })),
+      }),
+    );
+  }
+
+  const templateName = lang === "js" ? `${template}-js` : template;
+  const templateDir = path.join(TEMPLATES_ROOT, templateName);
+  if (!fs.existsSync(templateDir)) {
+    fail(`Template directory missing: ${templateDir}`);
+  }
+
+  if (fs.existsSync(targetDir) && !isEmptyDir(targetDir)) {
+    if (args.overwrite) {
+      // Keep the directory itself (it may be the cwd); template files
+      // overwrite existing ones of the same name.
+    } else if (process.stdout.isTTY) {
+      const overwrite = bail(
+        await p.confirm({
+          message: `${path.relative(process.cwd(), targetDir) || "."} is not empty. Continue and overwrite matching files?`,
+          initialValue: false,
+        }),
+      );
+      if (!overwrite) {
+        p.cancel("Cancelled.");
+        process.exit(1);
+      }
+    } else {
+      fail(`${targetDir} is not empty (pass --overwrite to continue)`);
+    }
+  }
+
+  copyTemplate(templateDir, targetDir);
+  patchJsonName(path.join(targetDir, "package.json"), packageName);
+  patchJsonName(
+    path.join(targetDir, "wrangler.json"),
+    toValidWorkerName(path.basename(targetDir)),
+  );
+
+  const cd = path.relative(process.cwd(), targetDir);
+  const steps = [
+    ...(cd ? [`cd ${shellPath(cd)}`] : []),
+    `${packageManager} install`,
+    packageManager === "npm" ? "npm run dev" : "pnpm dev",
+  ];
+  p.note(steps.join("\n"), "Next steps");
+  p.outro(`Scaffolded ${templateName} template in ${cd || "."}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "create-rango",
+  "version": "0.1.0",
+  "description": "Scaffold a React Server Components app powered by @rangojs/router",
+  "keywords": [
+    "create",
+    "rango",
+    "react-server-components",
+    "rsc",
+    "scaffold",
+    "vite"
+  ],
+  "homepage": "https://github.com/rangojs/templates#readme",
+  "bugs": {
+    "url": "https://github.com/rangojs/templates/issues"
+  },
+  "license": "MIT",
+  "author": "Ivo Todorov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rangojs/templates.git",
+    "directory": "packages/create-rango"
+  },
+  "bin": {
+    "create-rango": "index.js"
+  },
+  "files": [
+    "index.js",
+    "templates"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prepack": "node scripts/sync-templates.mjs",
+    "postpack": "node scripts/sync-templates.mjs --clean",
+    "prepublishOnly": "npm test",
+    "test": "node test/smoke.mjs && node test/pack-smoke.mjs",
+    "test:smoke": "node test/smoke.mjs",
+    "test:pack": "node test/pack-smoke.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/templates/basic/.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "all",
+  "ignorePatterns": ["dist/", "node_modules/", ".vite/"]
+}

package/templates/basic/.oxlintrc.json

@@ -0,0 +1,6 @@
+{
+  "plugins": ["typescript"],
+  "categories": { "correctness": "error" },
+  "rules": { "typescript/triple-slash-reference": "off" },
+  "ignorePatterns": ["dist/", "node_modules/", ".vite/"]
+}

package/templates/basic/README.md

@@ -0,0 +1,35 @@
+# Rango app
+
+A [React Server Components](https://react.dev/reference/rsc/server-components) app powered by [`@rangojs/router`](https://www.npmjs.com/package/@rangojs/router), Vite, and Tailwind CSS.
+
+## Commands
+
+```sh
+npm run dev        # start the dev server
+npm run build      # production build to dist/
+npm run start      # run the production server (server.mjs)
+npm run preview    # serve the production build locally (Vite preview, local-only)
+npm run generate   # regenerate committed route maps
+npm test           # run unit tests
+npm run typecheck  # tsc --noEmit
+npm run lint       # oxlint
+npm run format     # oxfmt check
+npm run check      # typecheck + tests + lint + format
+```
+
+Requires Node.js 24 or newer.
+
+## Deploying
+
+`npm run build && npm run start` is the production path: `server.mjs` serves fingerprinted assets with immutable cache headers, keeps public files revalidatable, and streams everything else through the router's fetch handler. Set `PORT` to change the port. `vite preview` is a local convenience, not a production server.
+
+## Project layout
+
+- `server.mjs` — the production server (`npm run start`): static assets via sirv, everything else via the router.
+- `src/router.tsx` — the router: URL patterns, route names, and the document component. The Vite plugin auto-discovers it; there is no `index.html` or entry file.
+- `src/components/Document.tsx` — the HTML shell (client component). Tailwind is wired here via `styles.css?url`.
+- `src/components/pages/` — route handlers. Each is a server function receiving a `HandlerContext` (params, meta, headers, …).
+- `src/actions/` — `"use server"` functions callable from client components.
+- `test/router.test.ts` — route-map drift test using `@rangojs/router/testing`.
+- `src/router.named-routes.gen.ts` — generated global route names for `Handler<"name">` and `ctx.reverse()`; commit it.
+- `src/router.gen.ts` — generated local route map used by `useReverse()` in client components; run `npm run generate` after route changes and commit it.

package/templates/basic/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.env*
+*.local

package/templates/basic/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "rango-template-basic",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "predev": "rango generate src/",
+    "dev": "vite",
+    "prebuild": "rango generate src/",
+    "build": "vite build",
+    "start": "node server.mjs",
+    "preview": "vite preview",
+    "generate": "rango generate src/",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings .",
+    "format": "oxfmt --check .",
+    "format:fix": "oxfmt .",
+    "check": "tsc --noEmit && vitest run && oxlint --deny-warnings . && oxfmt --check ."
+  },
+  "dependencies": {
+    "@rangojs/router": "^0.4.0",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "sirv": "^3.0.0",
+    "srvx": "^0.11.22"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.1",
+    "@types/node": "^24.10.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.0",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "tailwindcss": "^4.3.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/templates/basic/server.mjs

@@ -0,0 +1,46 @@
+// Production server: serves the vite build from dist/.
+// Build first (`npm run build`), then `npm run start`.
+import { createServer } from "node:http";
+import sirv from "sirv";
+import { toNodeHandler } from "srvx/node";
+import handler from "./dist/rsc/index.js";
+
+const port = Number(process.env.PORT ?? 3000);
+
+const serveStatic = sirv("dist/client");
+const serveHashedAssets = sirv("dist/client", {
+  immutable: true,
+  maxAge: 31536000,
+});
+
+// srvx bridges the router's Web fetch handler onto Node's (req, res), piping
+// streamed responses through.
+const serveApp = toNodeHandler((request) =>
+  handler(request, { env: process.env }),
+);
+
+function isFingerprintedAsset(url) {
+  const pathname = new URL(url, "http://localhost").pathname;
+  return /^\/assets\/.+-[A-Za-z0-9_-]{8,}\.[A-Za-z0-9]+$/.test(pathname);
+}
+
+const server = createServer((req, res) => {
+  // Only Vite fingerprinted files are immutable. A user may also place an
+  // unhashed public file under public/assets/, which must remain revalidatable.
+  const serveAssets = isFingerprintedAsset(req.url ?? "/")
+    ? serveHashedAssets
+    : serveStatic;
+  serveAssets(req, res, () => serveApp(req, res));
+});
+server.listen(port, () => {
+  console.log(`Listening on http://localhost:${server.address().port}`);
+});
+
+function shutdown() {
+  const forceClose = setTimeout(() => server.closeAllConnections(), 10_000);
+  forceClose.unref();
+  server.close(() => clearTimeout(forceClose));
+}
+
+process.once("SIGTERM", shutdown);
+process.once("SIGINT", shutdown);

package/templates/basic/src/actions/counter.ts

@@ -0,0 +1,11 @@
+"use server";
+
+import { updateCount as persistCount } from "../data/counter.js";
+
+export async function updateCount(formData: FormData): Promise<void> {
+  const delta = formData.get("delta");
+  if (delta !== "-1" && delta !== "1") {
+    throw new Error("Invalid counter change");
+  }
+  persistCount(Number(delta));
+}

package/templates/basic/src/components/Counter.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { useFormStatus } from "react-dom";
+import { updateCount } from "../actions/counter.js";
+
+export function Counter({ initialCount }: { initialCount: number }) {
+  return (
+    <form action={updateCount}>
+      <CounterControls count={initialCount} />
+    </form>
+  );
+}
+
+function CounterControls({ count }: { count: number }) {
+  const { pending } = useFormStatus();
+  return (
+    <div className="flex items-center gap-4" aria-busy={pending}>
+      <button
+        type="submit"
+        name="delta"
+        value="-1"
+        disabled={pending}
+        aria-label="Decrease count"
+        className="rounded-md bg-zinc-900 px-4 py-2 text-sm font-medium text-white hover:bg-zinc-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 disabled:opacity-50 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-zinc-300 dark:focus-visible:outline-blue-400"
+      >
+        −1
+      </button>
+      <output
+        aria-live="polite"
+        className="min-w-16 text-center text-2xl font-semibold tabular-nums"
+        style={{ opacity: pending ? 0.5 : 1 }}
+      >
+        {count}
+      </output>
+      <button
+        type="submit"
+        name="delta"
+        value="1"
+        disabled={pending}
+        aria-label="Increase count"
+        className="rounded-md bg-zinc-900 px-4 py-2 text-sm font-medium text-white hover:bg-zinc-700 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-600 disabled:opacity-50 dark:bg-zinc-100 dark:text-zinc-900 dark:hover:bg-zinc-300 dark:focus-visible:outline-blue-400"
+      >
+        +1
+      </button>
+      <span className="sr-only" role="status">
+        {pending ? "Updating count" : ""}
+      </span>
+    </div>
+  );
+}

package/templates/basic/src/components/Document.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { useEffect, useRef, type ReactNode } from "react";
+import {
+  Link,
+  MetaTags,
+  useNavigation,
+  usePathname,
+  useReverse,
+} from "@rangojs/router/client";
+import { routes } from "../router.gen.js";
+import styles from "../styles.css?url";
+
+export function Document({ children }: { children: ReactNode }) {
+  const pathname = usePathname();
+  const reverse = useReverse(routes);
+  const isNavigating = useNavigation(
+    (navigation) => navigation.state !== "idle",
+  );
+  const contentRef = useRef<HTMLDivElement>(null);
+  const previousPathname = useRef(pathname);
+
+  useEffect(() => {
+    if (previousPathname.current !== pathname) {
+      contentRef.current?.focus();
+      previousPathname.current = pathname;
+    }
+  }, [pathname]);
+
+  const links = [
+    [reverse("home"), "Home"],
+    [reverse("about"), "About"],
+    [reverse("counter"), "Counter"],
+  ] as const;
+
+  return (
+    <html lang="en">
+      <head>
+        <MetaTags />
+        <link rel="preload" as="style" href={styles} precedence="default" />
+        <link rel="stylesheet" href={styles} precedence="default" />
+      </head>
+      <body className="min-h-dvh bg-white text-zinc-900 antialiased dark:bg-zinc-950 dark:text-zinc-100">
+        <div className="mx-auto max-w-2xl px-6 py-10">
+          <a
+            href="#main-content"
+            className="sr-only rounded bg-white px-3 py-2 text-zinc-950 focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-10"
+          >
+            Skip to content
+          </a>
+          <nav className="mb-10 flex items-center gap-6 border-b border-zinc-200 pb-4 text-sm font-medium dark:border-zinc-800">
+            {links.map(([to, label]) => (
+              <Link
+                key={to}
+                to={to}
+                aria-current={pathname === to ? "page" : undefined}
+                className="hover:text-blue-600 focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-blue-600 dark:hover:text-blue-400 dark:focus-visible:outline-blue-400"
+              >
+                {label}
+              </Link>
+            ))}
+          </nav>
+          <span className="sr-only" aria-live="polite">
+            {isNavigating ? "Loading page" : ""}
+          </span>
+          <div
+            id="main-content"
+            ref={contentRef}
+            tabIndex={-1}
+            className="outline-none"
+          >
+            {children}
+          </div>
+        </div>
+      </body>
+    </html>
+  );
+}