create-rango 0.1.0

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

@@ -0,0 +1,36 @@
+import { Link, href } from "@rangojs/router/client";
+
+const linkClass =
+  "mt-6 inline-flex font-medium text-blue-600 underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-blue-600 dark:text-blue-400 dark:focus-visible:outline-blue-400";
+
+export function ErrorFallback() {
+  return (
+    <main>
+      <div role="alert">
+        <h1 className="text-3xl font-semibold tracking-tight">
+          Something went wrong
+        </h1>
+        <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+          The page could not be rendered. Try again or return home.
+        </p>
+      </div>
+      <Link to={href("/")} className={linkClass}>
+        Return home
+      </Link>
+    </main>
+  );
+}
+
+export function NotFoundPage() {
+  return (
+    <main>
+      <h1 className="text-3xl font-semibold tracking-tight">Page not found</h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        The page you requested does not exist.
+      </p>
+      <Link to={href("/")} className={linkClass}>
+        Return home
+      </Link>
+    </main>
+  );
+}

package/templates/basic/src/components/pages/AboutPage.tsx

@@ -0,0 +1,21 @@
+import { Meta, type HandlerContext } from "@rangojs/router";
+
+export function AboutPage(ctx: HandlerContext) {
+  const meta = ctx.use(Meta);
+  meta({ title: "About — Rango" });
+  meta({
+    name: "description",
+    content: "How this Rango starter structures routes and server components",
+  });
+
+  return (
+    <main>
+      <h1 className="text-3xl font-semibold tracking-tight">About</h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        Routes are plain functions receiving a handler context. Register them in{" "}
+        <code>src/router.tsx</code> with Django-style URL patterns; route names
+        generate typed <code>href()</code> lookups as you save.
+      </p>
+    </main>
+  );
+}

package/templates/basic/src/components/pages/CounterPage.tsx

@@ -0,0 +1,27 @@
+import { Meta, type HandlerContext } from "@rangojs/router";
+import { Counter } from "../Counter.js";
+import { getCount } from "../../data/counter.js";
+
+export function CounterPage(ctx: HandlerContext) {
+  const meta = ctx.use(Meta);
+  meta({ title: "Counter — Rango" });
+  meta({
+    name: "description",
+    content: "A progressively enhanced React server action counter",
+  });
+
+  const initialCount = getCount();
+
+  return (
+    <main>
+      <h1 className="text-3xl font-semibold tracking-tight">Counter</h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        The count lives on the server. The form works before JavaScript loads,
+        then React adds pending feedback without changing the action.
+      </p>
+      <div className="mt-8">
+        <Counter initialCount={initialCount} />
+      </div>
+    </main>
+  );
+}

package/templates/basic/src/components/pages/GreetingPage.tsx

@@ -0,0 +1,24 @@
+import { Meta, type Handler } from "@rangojs/router";
+
+export const GreetingPage: Handler<"greeting"> = (ctx) => {
+  const name = ctx.params.name;
+
+  const meta = ctx.use(Meta);
+  meta({ title: `Hello ${name} — Rango` });
+  meta({
+    name: "description",
+    content: `A typed dynamic route greeting ${name}`,
+  });
+
+  return (
+    <main>
+      <h1 className="break-words text-3xl font-semibold tracking-tight">
+        Hello, {name}!
+      </h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        This page matched <code>/hello/:name</code> and read the param from{" "}
+        <code>ctx.params</code> on the server.
+      </p>
+    </main>
+  );
+};

package/templates/basic/src/components/pages/HomePage.tsx

@@ -0,0 +1,52 @@
+import { Meta, type HandlerContext } from "@rangojs/router";
+import { Link } from "@rangojs/router/client";
+
+export function HomePage(ctx: HandlerContext) {
+  const meta = ctx.use(Meta);
+  meta({ title: "Home — Rango" });
+  meta({
+    name: "description",
+    content: "A React Server Components app powered by @rangojs/router",
+  });
+
+  const greetingUrl = ctx.reverse("greeting", { name: "world" });
+  const counterUrl = ctx.reverse("counter");
+
+  return (
+    <main>
+      <h1 className="text-3xl font-semibold tracking-tight">
+        Welcome to Rango
+      </h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        This starter renders React Server Components with streaming SSR, typed
+        routes, and Tailwind CSS. Handlers run on the server; client components
+        hydrate where you opt in with <code>"use client"</code>.
+      </p>
+      <ul className="mt-8 space-y-3">
+        <li className="rounded-lg border border-zinc-200 p-4 dark:border-zinc-800">
+          <Link
+            to={greetingUrl}
+            className="font-medium text-blue-600 hover:underline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-blue-600 dark:text-blue-400 dark:focus-visible:outline-blue-400"
+          >
+            Dynamic route
+          </Link>
+          <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
+            <code>/hello/:name</code> — read path params from the handler
+            context.
+          </p>
+        </li>
+        <li className="rounded-lg border border-zinc-200 p-4 dark:border-zinc-800">
+          <Link
+            to={counterUrl}
+            className="font-medium text-blue-600 hover:underline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-blue-600 dark:text-blue-400 dark:focus-visible:outline-blue-400"
+          >
+            Server actions
+          </Link>
+          <p className="mt-1 text-sm text-zinc-600 dark:text-zinc-400">
+            A client component calling <code>"use server"</code> functions.
+          </p>
+        </li>
+      </ul>
+    </main>
+  );
+}

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

@@ -0,0 +1,11 @@
+// In-memory state for demo purposes: it resets on restart and is per-instance.
+// Use a database or KV store in a real app.
+let count = 0;
+
+export function getCount(): number {
+  return count;
+}
+
+export function updateCount(delta: number): void {
+  count += delta;
+}

package/templates/basic/src/router.gen.ts

@@ -0,0 +1,8 @@
+// Auto-generated by @rangojs/router - do not edit
+export const routes = {
+  about: "/about",
+  counter: "/counter",
+  greeting: "/hello/:name",
+  home: "/",
+} as const;
+export type routes = typeof routes;

package/templates/basic/src/router.named-routes.gen.ts

@@ -0,0 +1,17 @@
+// Auto-generated by @rangojs/router - do not edit
+export const NamedRoutes = {
+  about: "/about",
+  counter: "/counter",
+  greeting: "/hello/:name",
+  home: "/",
+} as const;
+
+// Aliased so the augmentation below does not pay a homomorphic mapped-type
+// instantiation per route; `as const` already makes the members readonly.
+type NamedRoutesShape = typeof NamedRoutes;
+
+declare global {
+  namespace Rango {
+    interface GeneratedRouteMap extends NamedRoutesShape {}
+  }
+}

package/templates/basic/src/router.tsx

@@ -0,0 +1,33 @@
+import { createRouter, urls } from "@rangojs/router";
+import { updateCount } from "./actions/counter.js";
+import { Document } from "./components/Document.js";
+import { ErrorFallback, NotFoundPage } from "./components/Fallbacks.js";
+import { HomePage } from "./components/pages/HomePage.js";
+import { AboutPage } from "./components/pages/AboutPage.js";
+import { GreetingPage } from "./components/pages/GreetingPage.js";
+import { CounterPage } from "./components/pages/CounterPage.js";
+
+export const urlpatterns = urls(({ path, revalidate }) => [
+  path("/", HomePage, { name: "home" }),
+  path("/about", AboutPage, { name: "about" }),
+  path("/hello/:name", GreetingPage, { name: "greeting" }),
+  path("/counter", CounterPage, { name: "counter" }, () => [
+    revalidate((ctx) => ctx.isAction(updateCount) || undefined),
+  ]),
+]);
+
+export const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  defaultErrorBoundary: ErrorFallback,
+  defaultNotFoundBoundary: NotFoundPage,
+  notFound: NotFoundPage,
+});
+
+type AppRoutes = typeof router.routeMap;
+
+declare global {
+  namespace Rango {
+    interface RegisteredRoutes extends AppRoutes {}
+  }
+}

package/templates/basic/src/styles.css

@@ -0,0 +1,5 @@
+@import "tailwindcss";
+
+:root {
+  color-scheme: light dark;
+}

package/templates/basic/test/router.test.ts

@@ -0,0 +1,8 @@
+import { assertGeneratedRoutesMatch } from "@rangojs/router/testing";
+import { test } from "vitest";
+import { NamedRoutes } from "../src/router.named-routes.gen.js";
+import { router } from "../src/router.js";
+
+test("generated routes match the runtime router", async () => {
+  await assertGeneratedRoutesMatch(router, NamedRoutes);
+});

package/templates/basic/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/basic/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { rango } from "@rangojs/router/vite";
+
+// The rango plugin auto-discovers the router (the single createRouter call in
+// src/router.tsx) and provides the client/server entries, so no index.html or
+// entry files are needed.
+export default defineConfig(({ command }) => ({
+  plugins: [react(), tailwindcss(), rango()],
+  // Fold NODE_ENV at build time so React's dev/prod branches collapse and the
+  // production bundle does not ship react development chunks.
+  define:
+    command === "build"
+      ? { "process.env.NODE_ENV": JSON.stringify("production") }
+      : undefined,
+}));

package/templates/basic/vitest.config.ts

@@ -0,0 +1,10 @@
+import { rangoTestConfig } from "@rangojs/router/testing/vitest";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["test/**/*.test.{ts,tsx}"],
+    ...rangoTestConfig(),
+  },
+});

package/templates/basic-js/.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-js/.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-js/README.md

@@ -0,0 +1,38 @@
+# 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 — plain JavaScript, no TypeScript.
+
+## 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 lint     # oxlint
+npm run format   # oxfmt check
+npm run check    # 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.jsx` — 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.jsx` — the HTML shell (client component). Tailwind is wired here via `styles.css?url`.
+- `src/components/pages/` — route handlers. Each is a server function receiving the handler context (params, meta, headers, …).
+- `src/actions/` — `"use server"` functions callable from client components.
+- `test/router.test.js` — route-map drift test using `@rangojs/router/testing`.
+- `src/router.named-routes.gen.ts` — generated global route names used by `ctx.reverse()` and editor path checks; 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.
+
+## Why is `typescript` in devDependencies?
+
+Your app code is plain JavaScript. The router's route-name generator uses the TypeScript compiler API to parse your routes and write `src/router.named-routes.gen.ts`, so the `typescript` package must be installed — no `tsconfig.json`, no type checking.

package/templates/basic-js/_gitignore

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

package/templates/basic-js/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "rango-template-basic-js",
+  "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",
+    "lint": "oxlint --deny-warnings .",
+    "format": "oxfmt --check .",
+    "format:fix": "oxfmt .",
+    "check": "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",
+    "@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-js/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-js/src/actions/counter.js

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

package/templates/basic-js/src/components/Counter.jsx

@@ -0,0 +1,50 @@
+"use client";
+
+import { useFormStatus } from "react-dom";
+import { updateCount } from "../actions/counter.js";
+
+export function Counter({ initialCount }) {
+  return (
+    <form action={updateCount}>
+      <CounterControls count={initialCount} />
+    </form>
+  );
+}
+
+function CounterControls({ count }) {
+  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-js/src/components/Document.jsx

@@ -0,0 +1,78 @@
+"use client";
+
+import { useEffect, useRef } 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 }) {
+  const pathname = usePathname();
+  const reverse = useReverse(routes);
+  const isNavigating = useNavigation(
+    (navigation) => navigation.state !== "idle",
+  );
+  const contentRef = useRef(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"],
+  ];
+
+  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>
+  );
+}

package/templates/basic-js/src/components/Fallbacks.jsx

@@ -0,0 +1,36 @@
+import { Link, href } from "@rangojs/router/client";
+
+const linkClass =
+  "mt-6 inline-flex font-medium text-blue-600 underline-offset-4 hover:underline focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-blue-600 dark:text-blue-400 dark:focus-visible:outline-blue-400";
+
+export function ErrorFallback() {
+  return (
+    <main>
+      <div role="alert">
+        <h1 className="text-3xl font-semibold tracking-tight">
+          Something went wrong
+        </h1>
+        <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+          The page could not be rendered. Try again or return home.
+        </p>
+      </div>
+      <Link to={href("/")} className={linkClass}>
+        Return home
+      </Link>
+    </main>
+  );
+}
+
+export function NotFoundPage() {
+  return (
+    <main>
+      <h1 className="text-3xl font-semibold tracking-tight">Page not found</h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        The page you requested does not exist.
+      </p>
+      <Link to={href("/")} className={linkClass}>
+        Return home
+      </Link>
+    </main>
+  );
+}

package/templates/basic-js/src/components/pages/AboutPage.jsx

@@ -0,0 +1,21 @@
+import { Meta } from "@rangojs/router";
+
+export function AboutPage(ctx) {
+  const meta = ctx.use(Meta);
+  meta({ title: "About — Rango" });
+  meta({
+    name: "description",
+    content: "How this Rango starter structures routes and server components",
+  });
+
+  return (
+    <main>
+      <h1 className="text-3xl font-semibold tracking-tight">About</h1>
+      <p className="mt-4 leading-7 text-zinc-600 dark:text-zinc-400">
+        Routes are plain functions receiving a handler context. Register them in{" "}
+        <code>src/router.jsx</code> with Django-style URL patterns; route names
+        generate <code>href()</code> lookups as you save.
+      </p>
+    </main>
+  );
+}