create-rango 0.1.0

package/templates/cloudflare/src/env.ts

@@ -0,0 +1,13 @@
+/// <reference types="@cloudflare/workers-types" />
+
+// Cloudflare Workers bindings. Add entries here as you bind resources in
+// wrangler.json, e.g.:
+//   KV: KVNamespace;
+//   DB: D1Database;
+export interface AppBindings {}
+
+declare global {
+  namespace Rango {
+    interface Env extends AppBindings {}
+  }
+}

package/templates/cloudflare/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/cloudflare/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/cloudflare/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/cloudflare/src/styles.css

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

package/templates/cloudflare/src/worker.rsc.tsx

@@ -0,0 +1,9 @@
+/// <reference types="@cloudflare/workers-types" />
+import { router } from "./router.js";
+import type { AppBindings } from "./env.js";
+
+export default {
+  async fetch(request, env, ctx) {
+    return router.fetch(request, { env, ctx });
+  },
+} satisfies ExportedHandler<AppBindings>;

package/templates/cloudflare/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/cloudflare/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": ["@cloudflare/workers-types", "vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/cloudflare/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { rango } from "@rangojs/router/vite";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+    rango({ preset: "cloudflare" }),
+    cloudflare({
+      configPath: "./wrangler.json",
+      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
+    }),
+  ],
+});

package/templates/cloudflare/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({ preset: "cloudflare" }),
+  },
+});

package/templates/cloudflare/wrangler.json

@@ -0,0 +1,9 @@
+{
+  "name": "rango-app",
+  "compatibility_date": "2026-07-12",
+  "compatibility_flags": ["nodejs_compat", "nodejs_als"],
+  "main": "./src/worker.rsc.tsx",
+  "assets": {
+    "directory": "./dist/client"
+  }
+}

package/templates/vercel/.oxfmtrc.json

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

package/templates/vercel/.oxlintrc.json

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

package/templates/vercel/README.md

@@ -0,0 +1,50 @@
+# Rango app on Vercel
+
+A [React Server Components](https://react.dev/reference/rsc/server-components) app powered by [`@rangojs/router`](https://www.npmjs.com/package/@rangojs/router), deployed to Vercel with Vite and Tailwind CSS.
+
+## Commands
+
+```sh
+npm run dev        # start the dev server
+npm run build      # vite build, then assembles .vercel/output (Build Output API v3)
+npm run preview    # serve .vercel/output with filesystem/function routing
+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
+
+The `vercel` preset assembles `.vercel/output/` during `npm run build`, so deploy prebuilt:
+
+```sh
+npm run build
+npx vercel@latest deploy --prebuilt          # preview deployment
+npx vercel@latest deploy --prebuilt --prod   # production
+```
+
+Pushing the repo to Vercel with the default Vite framework settings also works: the build output is picked up from `.vercel/output`.
+
+## Project layout
+
+- `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 (server functions receiving a `HandlerContext`).
+- `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.
+- `scripts/preview.mjs` — serves the assembled Vercel output locally, including the streaming function.
+
+## Why is `esbuild` in devDependencies?
+
+The vercel preset bundles the generated function launcher with esbuild at build time. Vite 8 no longer ships esbuild (it is rolldown-based), so the app must provide it.
+
+## Note on the counter demo
+
+The demo count lives in function instance memory, so it resets across invocations/instances. Use a database or Vercel KV-style store for real persistence.

package/templates/vercel/_gitignore

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

package/templates/vercel/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "rango-template-vercel",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "predev": "rango generate src/",
+    "dev": "vite",
+    "prebuild": "rango generate src/",
+    "build": "vite build",
+    "preview": "node scripts/preview.mjs",
+    "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",
+    "@vercel/functions": "^3.7.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "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",
+    "esbuild": "^0.28.1",
+    "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/vercel/scripts/preview.mjs

@@ -0,0 +1,23 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createVercelOutputServer } from "./serve-vercel-output.mjs";
+
+const appRoot = path.resolve(fileURLToPath(import.meta.url), "../..");
+const server = await createVercelOutputServer(
+  path.join(appRoot, ".vercel", "output"),
+);
+const port = Number(process.env.PORT ?? 3000);
+const host = process.env.HOST ?? "127.0.0.1";
+
+server.listen(port, host, () => {
+  console.log(`Vercel preview: http://${host}:${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/vercel/scripts/serve-vercel-output.mjs

@@ -0,0 +1,67 @@
+import http from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const CONTENT_TYPE = {
+  ".css": "text/css",
+  ".ico": "image/x-icon",
+  ".js": "text/javascript",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".mjs": "text/javascript",
+  ".svg": "image/svg+xml",
+};
+
+export async function createVercelOutputServer(outputDir) {
+  const functionEntry = path.join(
+    outputDir,
+    "functions",
+    "index.func",
+    "index.mjs",
+  );
+  const staticDir = path.join(outputDir, "static");
+  const handler = (await import(pathToFileURL(functionEntry).href)).default;
+
+  return http.createServer(async (request, response) => {
+    try {
+      const pathname = decodeURIComponent(
+        new URL(request.url, "http://localhost").pathname,
+      );
+      if (pathname !== "/") {
+        const filePath = path.resolve(staticDir, pathname.replace(/^\/+/, ""));
+        const relativePath = path.relative(staticDir, filePath);
+        if (
+          relativePath &&
+          !relativePath.startsWith("..") &&
+          !path.isAbsolute(relativePath)
+        ) {
+          try {
+            const info = await stat(filePath);
+            if (info.isFile()) {
+              response.setHeader(
+                "content-type",
+                CONTENT_TYPE[path.extname(filePath)] ??
+                  "application/octet-stream",
+              );
+              response.end(await readFile(filePath));
+              return;
+            }
+          } catch {
+            // Missing static files fall through to the function.
+          }
+        }
+      }
+      await handler(request, response);
+    } catch (error) {
+      if (!response.headersSent) {
+        response.statusCode = error instanceof URIError ? 400 : 500;
+        response.end();
+      } else {
+        response.destroy(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
+    }
+  });
+}

package/templates/vercel/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/vercel/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/vercel/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>
+  );
+}

package/templates/vercel/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/vercel/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/vercel/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/vercel/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>
+  );
+};