create-ramonyx-app 2.0.1 → 2.0.2

package/README.md

@@ -2,16 +2,20 @@
 
 Scaffolder aplikasi Ramonyx — SSR React + hydration, file routing `src/routes`.
 
-> **Alpha (2.0.1)** — butuh **Node.js ≥ 24**.
+> **Alpha (2.0.2)** — butuh **Node.js ≥ 24**.
 
 ## Pemakaian
 
 ```bash
-pnpm create ramonyx-app aplikasi-saya
-# atau tanpa install:
-pnpm dlx create-ramonyx-app aplikasi-saya
+npm create ramonyx-app@latest aplikasi-saya
+# atau:
+pnpm create ramonyx-app@latest aplikasi-saya
+yarn create ramonyx-app aplikasi-saya
+bun create ramonyx-app aplikasi-saya
 ```
 
-Lanjutkan dengan `cd aplikasi-saya && pnpm install && pnpm build && pnpm start`.
+Pilih template dengan `--template minimal|api-auth|cloudflare|docs-blog`.
+Lanjutkan dengan manager yang sama: `npm install && npm run dev`,
+`pnpm install && pnpm dev`, `yarn && yarn dev`, atau `bun install && bun run dev`.
 
 Repo: https://github.com/RamonyxJS/ramonyx · Lisensi: MIT

package/dist/cli.js

@@ -6,18 +6,33 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 var packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
 var templateDir = join(packageRoot, "template");
+var templatesDir = join(packageRoot, "templates");
 var agentTemplateDir = join(packageRoot, "template-agent");
+var TEMPLATES = {
+  minimal: "Welcome screen: SSR + hydration + API + form action",
+  "api-auth": "Session auth: login/logout, protected API, server action",
+  cloudflare: "Cloudflare Worker: R2 + KV binding example and wrangler config",
+  "docs-blog": "Static content: blog index + dynamic posts + SSG export"
+};
+var TEMPLATE_IDS = Object.keys(TEMPLATES);
 var USAGE = `create-ramonyx-app \u2014 buat aplikasi Ramonyx baru
 
 Penggunaan:
-  pnpm create ramonyx-app <dir>      # dari registry (setelah publikasi)
-  pnpm dlx create-ramonyx-app <dir>  # tanpa install
-  pnpm create:app <dir>              # di dalam repo (workspace)
+  npm create ramonyx-app@latest <dir>   # registry
+  pnpm create ramonyx-app@latest <dir>  # registry
+  yarn create ramonyx-app <dir>         # registry
+  bun create ramonyx-app <dir>          # registry
+  pnpm create:app <dir>                 # di dalam repo (workspace)
 
 Opsi:
   --force, -f       Timpa berkas template walau direktori tujuan tidak kosong
   --with-agent-docs Sertakan AGENTS.md + skill agent opt-in (tidak default)
+  --template <id>   Template: minimal (default), api-auth, cloudflare, docs-blog
+  --list-templates  Tampilkan template yang tersedia
   --help, -h        Tampilkan bantuan ini
+
+Catatan pnpm: bila scaffold masih 1.x, pakai
+  pnpm create ramonyx-app@2.0.1 <dir>
 `;
 function usage(exitCode) {
   const write = exitCode === 0 ? console.log : console.error;
@@ -27,12 +42,42 @@ function usage(exitCode) {
 var args = process.argv.slice(2);
 var force = false;
 var withAgentDocs = false;
+var template = "minimal";
 var target;
-for (const arg of args) {
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index] ?? "";
+  const next = () => {
+    const value = args[index + 1];
+    if (value === void 0 || value.startsWith("-")) {
+      console.error(`error: ${arg} membutuhkan nilai`);
+      usage(1);
+    }
+    index += 1;
+    return value;
+  };
   if (arg === "--force" || arg === "-f") {
     force = true;
   } else if (arg === "--with-agent-docs") {
     withAgentDocs = true;
+  } else if (arg === "--list-templates") {
+    for (const id of TEMPLATE_IDS) console.log(`${id.padEnd(12)} ${TEMPLATES[id]}`);
+    process.exit(0);
+  } else if (arg === "--template") {
+    const value = next();
+    if (!TEMPLATE_IDS.includes(value)) {
+      console.error(`error: template tidak dikenal: ${value}`);
+      console.error(`tersedia: ${TEMPLATE_IDS.join(", ")}`);
+      usage(1);
+    }
+    template = value;
+  } else if (arg.startsWith("--template=")) {
+    const value = arg.slice("--template=".length);
+    if (!TEMPLATE_IDS.includes(value)) {
+      console.error(`error: template tidak dikenal: ${value}`);
+      console.error(`tersedia: ${TEMPLATE_IDS.join(", ")}`);
+      usage(1);
+    }
+    template = value;
   } else if (arg === "--help" || arg === "-h") {
     usage(0);
   } else if (arg.startsWith("-")) {
@@ -77,14 +122,29 @@ function copy(source, destination) {
   writeFileSync(join(dirname(destination), name), text);
 }
 copy(templateDir, targetDir);
+if (template !== "minimal") {
+  const overlay = join(templatesDir, template);
+  if (!existsSync(overlay)) {
+    console.error(`error: berkas template ${template} tidak ditemukan di ${overlay}`);
+    process.exit(1);
+  }
+  copy(overlay, targetDir);
+}
 if (withAgentDocs) {
   copy(agentTemplateDir, targetDir);
 }
-console.log(`\u2713 App "${appName}" dibuat di ${targetDir}
+console.log(`\u2713 App "${appName}" dibuat di ${targetDir} (template: ${template})
 
 Langkah berikutnya:
 
   cd ${target}
-  pnpm install   # atau npm install
-  pnpm start     # http://127.0.0.1:3000
+
+Pilih SATU package manager (jangan campur lockfile):
+
+  npm install && npm run build && npm start
+  pnpm install && pnpm build && pnpm start
+  yarn && yarn build && yarn start
+  bun install && bun run build && bun run start
+
+Dev server: ganti "build && start" dengan "run dev" / "dev".
 ${withAgentDocs ? "\nAgent docs: AGENTS.md + .opencode/skills/ramonyx/SKILL.md sudah disertakan.\n" : ""}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ramonyx-app",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Scaffolder aplikasi Ramonyx (SSR React + hydration, file routing src/routes).",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "dist",
     "template",
+    "templates",
     "template-agent",
     "README.md",
     "LICENSE"

package/template/README.md

@@ -7,16 +7,25 @@ Aplikasi [Ramonyx](https://github.com/ramonyx/ramonyx) — framework full-stack
 ## Menjalankan
 
 ```bash
-pnpm install   # atau: bun install / npm install
-pnpm dev       # Vite + HMR + SSR (http://localhost:3000, satu port)
-pnpm build     # bundel klien (wajib sebelum start produksi)
-pnpm start     # http://127.0.0.1:3000 (NODE_ENV=production otomatis)
+npm install
+npm run dev     # Vite + HMR + SSR (http://localhost:3000, satu port)
+npm run build   # bundel klien (wajib sebelum start produksi)
+npm start       # http://127.0.0.1:3000 (NODE_ENV=production otomatis)
 ```
 
-Dengan Bun: `bun run dev`, `bun run build`, `bun run start`. Perintah memakai CLI **`ramonyx`**
-(`@ramonyx/devtools`) yang terpasang **lokal** di `node_modules/.bin`. Untuk memanggil CLI di luar
-package script, gunakan runner package manager: `bunx ramonyx …`, `pnpm exec ramonyx …`, atau
-`npx ramonyx …`. `ramonyx …` tanpa runner hanya tersedia setelah instalasi global.
+Semua package manager yang diuji bisa dipakai:
+
+| Manager | Install | Dev |
+| --- | --- | --- |
+| npm | `npm install` | `npm run dev` |
+| pnpm | `pnpm install` | `pnpm dev` |
+| Yarn | `yarn` | `yarn dev` |
+| Bun | `bun install` | `bun run dev` |
+
+Perintah memakai CLI **`ramonyx`** (`@ramonyx/devtools`) yang terpasang **lokal** di
+`node_modules/.bin`. Untuk memanggil CLI di luar package script, gunakan runner package manager:
+`npx ramonyx …`, `pnpm exec ramonyx …`, atau `bunx ramonyx …`. `ramonyx …` tanpa runner hanya
+tersedia setelah instalasi global.
 
 ## Struktur
 

package/template/package.json

@@ -11,15 +11,15 @@
     "dev": "ramonyx dev"
   },
   "dependencies": {
-    "@ramonyx/adapter-runtime": "^2.0.1",
-    "@ramonyx/bundler": "^2.0.1",
-    "@ramonyx/compiler": "^2.0.1",
-    "@ramonyx/devtools": "^2.0.1",
-    "@ramonyx/react": "^2.0.1",
-    "@ramonyx/security": "^2.0.1",
-    "@ramonyx/server": "^2.0.1",
-    "@ramonyx/ssr": "^2.0.1",
-    "ramonyx": "^2.0.1",
+    "@ramonyx/adapter-runtime": "^2.0.2",
+    "@ramonyx/bundler": "^2.0.2",
+    "@ramonyx/compiler": "^2.0.2",
+    "@ramonyx/devtools": "^2.0.2",
+    "@ramonyx/react": "^2.0.2",
+    "@ramonyx/security": "^2.0.2",
+    "@ramonyx/server": "^2.0.2",
+    "@ramonyx/ssr": "^2.0.2",
+    "ramonyx": "^2.0.2",
     "react": "19.3.1",
     "react-dom": "19.3.1"
   },

package/templates/api-auth/README.md

@@ -0,0 +1,33 @@
+# __APP_NAME__ — API auth starter
+
+A production-shaped starting point for session auth:
+
+- `POST /` — login server action (progressive enhancement; no JS required)
+- `GET /api/me` — current user or `401`
+- `POST /api/auth/logout` — revoke the cookie
+- `src/lib/auth.server.ts` — server-side session store, password verification, demo user store
+- `src/routes/middleware.ts` — security headers, CSP nonce, and CSRF (`_csrf` / `x-csrf-token`)
+  - CSRF cookie is not `Secure` by default so HTTP dev works; enable `csrfProtection({ secure: true })`
+    in production or terminate TLS with a Secure-only policy.
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Demo credentials: `demo` / `demo-password-123`.
+
+## Before production
+
+1. Set a random `SESSION_SECRET` (32+ characters) in the environment or binding.
+2. Replace `createMemoryUserStore()` and `createMemorySessionStore()` with database/KV adapters;
+   memory loses users and sessions on restart.
+3. Add login rate limiting and a production auth provider (Better Auth is documented in the
+   integration recipes). CSRF is enabled; JSON clients must send the cookie plus `x-csrf-token`.
+4. Serve over HTTPS so the session cookie's `Secure` attribute takes effect.
+
+The template uses a server-side session store so logout revokes the server record (not just the
+cookie). It deliberately keeps auth code in `src/lib/auth.server.ts`; never import it from a client
+component.

package/templates/api-auth/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "ramonyx build",
+    "start": "ramonyx start",
+    "dev": "ramonyx dev"
+  },
+  "dependencies": {
+    "@ramonyx/adapter-runtime": "^2.0.2",
+    "@ramonyx/bundler": "^2.0.2",
+    "@ramonyx/compiler": "^2.0.2",
+    "@ramonyx/devtools": "^2.0.2",
+    "@ramonyx/react": "^2.0.2",
+    "@ramonyx/security": "^2.0.2",
+    "@ramonyx/server": "^2.0.2",
+    "@ramonyx/ssr": "^2.0.2",
+    "ramonyx": "^2.0.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0"
+  },
+  "imports": {
+    "#routes": "./.ramonyx/routes.ts"
+  }
+}

package/templates/api-auth/src/lib/auth.server.ts

@@ -0,0 +1,81 @@
+// Server-only auth demo. Replace the memory stores with a database/KV adapter before production.
+import {
+  type AuthUser,
+  createMemorySessionStore,
+  createMemoryUserStore,
+  createSession,
+  hashPassword,
+  verifyPassword,
+} from "@ramonyx/security";
+import type { EnvReader } from "ramonyx";
+
+const users = createMemoryUserStore();
+// Server-side sessions make logout/revocation real. Replace with Redis/KV/DB in production.
+const sessions = createMemorySessionStore();
+const DEMO_USERNAME = "demo";
+const DEMO_PASSWORD = "demo-password-123";
+const DEV_SECRET = "dev-only-session-secret-change-me-32-chars";
+
+let seeded: Promise<void> | undefined;
+
+function ensureDemoUser(): Promise<void> {
+  seeded ??= (async () => {
+    if ((await users.getByUsername(DEMO_USERNAME)) !== null) return;
+    await users.create({
+      username: DEMO_USERNAME,
+      passwordHash: await hashPassword(DEMO_PASSWORD),
+      roles: ["user"],
+    });
+  })();
+  return seeded;
+}
+
+function sessionSecret(env: EnvReader): string {
+  const secret = env.get("SESSION_SECRET");
+  if (secret !== undefined && secret.length >= 32) return secret;
+  if (env.get("NODE_ENV") === "production") {
+    throw new Error("SESSION_SECRET wajib diisi (minimal 32 karakter) di production");
+  }
+  return DEV_SECRET;
+}
+
+export function sessionFor(env: EnvReader) {
+  return createSession({
+    secret: sessionSecret(env),
+    store: sessions,
+    cookie: { secure: env.get("NODE_ENV") === "production" },
+  });
+}
+
+export async function currentUser(env: EnvReader, request: Request): Promise<AuthUser | null> {
+  const data = await sessionFor(env).read(request);
+  const userId = typeof data?.userId === "string" ? data.userId : null;
+  return userId === null ? null : users.getById(userId);
+}
+
+export type LoginResult =
+  | { readonly ok: true; readonly cookie: string; readonly user: AuthUser }
+  | { readonly ok: false; readonly error: string };
+
+export async function login(env: EnvReader, formData: FormData): Promise<LoginResult> {
+  await ensureDemoUser();
+  const username = String(formData.get("username") ?? "").trim();
+  const password = String(formData.get("password") ?? "");
+  const user = await users.getByUsername(username);
+  if (user === null || user.passwordHash === undefined) {
+    return { ok: false, error: "Invalid username or password." };
+  }
+  const valid = password.length > 0 && (await verifyPassword(password, user.passwordHash));
+  if (!valid) {
+    return { ok: false, error: "Invalid username or password." };
+  }
+  const cookie = await sessionFor(env).commit({
+    userId: user.id,
+    username: user.username,
+  });
+  return { ok: true, cookie, user };
+}
+
+export async function logoutCookie(env: EnvReader, request: Request): Promise<string> {
+  return sessionFor(env).revoke(request);
+}

package/templates/api-auth/src/routes/api/auth/logout.ts

@@ -0,0 +1,7 @@
+import { route } from "ramonyx";
+import { logoutCookie } from "../../../lib/auth.server.ts";
+
+export const POST = route({
+  handler: async ({ env, request, json }) =>
+    json({ ok: true }, { headers: { "set-cookie": await logoutCookie(env, request) } }),
+});

package/templates/api-auth/src/routes/api/me.ts

@@ -0,0 +1,12 @@
+import { route } from "ramonyx";
+import { currentUser } from "../../lib/auth.server.ts";
+
+export const GET = route({
+  handler: async ({ env, request, json }) => {
+    const user = await currentUser(env, request);
+    if (user === null) {
+      return json({ error: "Unauthorized" }, 401);
+    }
+    return json({ user: { id: user.id, username: user.username } });
+  },
+});

package/templates/api-auth/src/routes/middleware.ts

@@ -0,0 +1,6 @@
+import { cspNonce, csrfProtection, securityHeaders } from "@ramonyx/security";
+import type { Middleware } from "ramonyx";
+
+// Root middleware applies to every page/API route (ADR-0061).
+// CSRF is double-submit: GET issues a cookie, forms echo `_csrf`, JSON clients send x-csrf-token.
+export default [securityHeaders(), cspNonce(), csrfProtection()] satisfies Middleware[];

package/templates/api-auth/src/routes/page.tsx

@@ -0,0 +1,92 @@
+import type { PageProps } from "@ramonyx/react";
+import { CSRF_REQUEST_HEADER } from "@ramonyx/security";
+import type { PageActionContext, PageLoaderContext } from "ramonyx";
+import { currentUser, login } from "../lib/auth.server.ts";
+
+export const metadata = {
+  title: "__APP_NAME__ — account",
+  description: "Session auth starter with a server action, protected API, and logout.",
+};
+
+export async function loader({ env, request }: PageLoaderContext) {
+  const user = await currentUser(env, request);
+  return {
+    user: user === null ? null : { id: user.id, username: user.username },
+    csrf: request.headers.get(CSRF_REQUEST_HEADER) ?? "",
+  };
+}
+
+export async function action({ env, formData }: PageActionContext) {
+  const result = await login(env, formData);
+  if (!result.ok) {
+    return { errors: { form: result.error } };
+  }
+  return { redirect: "/", headers: { "set-cookie": result.cookie } };
+}
+
+export default function Account({
+  data,
+  action,
+}: PageProps<{ user: { id: string; username: string } | null }>) {
+  return (
+    <main className="rw-main">
+      <section className="rw-hero">
+        <div className="rw-hero-copy">
+          <p className="rw-kicker">API auth starter</p>
+          <h1>
+            Sessions that survive a <span>server restart boundary.</span>
+          </h1>
+          <p className="rw-lede">
+            Signed, HTTP-only session cookies, a password-verified server action, a protected API,
+            and logout. The demo user store is in-memory; replace it before deploying.
+          </p>
+
+          {data.user === null ? (
+            <form method="post" className="rw-form">
+              <input type="hidden" name="_csrf" value={data.csrf} />
+              <label htmlFor="username">Username</label>
+              <input id="username" name="username" autoComplete="username" defaultValue="demo" />
+              <label htmlFor="password">Password</label>
+              <input
+                id="password"
+                name="password"
+                type="password"
+                autoComplete="current-password"
+                defaultValue="demo-password-123"
+              />
+              <button type="submit">Sign in</button>
+            </form>
+          ) : (
+            <div className="rw-actions">
+              <p className="rw-success" role="status">
+                Signed in as <strong>{data.user.username}</strong>
+              </p>
+              <form method="post" action="/api/auth/logout">
+                <input type="hidden" name="_csrf" value={data.csrf} />
+                <button type="submit" className="rw-quiet">
+                  Sign out
+                </button>
+              </form>
+              <a className="rw-button" href="/api/me">
+                Open /api/me
+              </a>
+            </div>
+          )}
+
+          {action?.errors?.form !== undefined ? (
+            <p className="rw-error" role="alert">
+              {action.errors.form}
+            </p>
+          ) : null}
+        </div>
+
+        <aside className="rw-status">
+          <p className="rw-label">DEMO CREDENTIALS</p>
+          <p className="rw-url">demo</p>
+          <p className="rw-status-sub">demo-password-123</p>
+          <p className="rw-status-sub">Set SESSION_SECRET before production.</p>
+        </aside>
+      </section>
+    </main>
+  );
+}

package/templates/cloudflare/README.md

@@ -0,0 +1,43 @@
+# __APP_NAME__ — Cloudflare R2 + KV starter
+
+Deploy the same Ramonyx route tree as a Cloudflare Worker with real R2/KV bindings.
+
+- `GET /api/storage?key=demo` — read KV + R2
+- `POST /api/storage` — `{ "key": "demo", "value": "hello" }`
+- `GET /` — HTML overview
+
+## Configure
+
+Edit `wrangler.toml` and replace the placeholder KV namespace ID. Create the resources first:
+
+```bash
+npx wrangler kv namespace create KV_STORE
+npx wrangler r2 bucket create __APP_NAME__-files
+npx wrangler secret put STORAGE_TOKEN   # random token, 16+ chars
+```
+
+Then:
+
+```bash
+npm install
+npm run dev              # Node: binding routes return 503
+npm run build:edge       # dist/edge/index.js
+npm run deploy           # build + wrangler deploy
+
+curl -H "Authorization: Bearer $STORAGE_TOKEN" \
+  https://your-worker.example/api/storage?key=demo
+```
+
+`npm` is shown for brevity. `pnpm install && pnpm dev`, `yarn && yarn dev`, and
+`bun install && bun run dev` work too; use the same manager for scripts.
+
+R2/KV are Cloudflare bindings, not Node packages. Use `wrangler dev`/Miniflare or the deployed
+Worker to exercise them; plain `ramonyx dev` has no bindings. The storage API requires
+`Authorization: Bearer <STORAGE_TOKEN>`; without the secret it returns 503. For local integration
+tests, the repo uses the edge smoke with Miniflare.
+
+## Notes
+
+- Keep the R2 bucket private unless you add a public custom domain.
+- Use random object keys; do not trust a client-provided filename.
+- The recipe `docs/recipes/cloudflare-r2-kv` covers upload/download streaming and limits.

package/templates/cloudflare/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "ramonyx build",
+    "start": "ramonyx start",
+    "dev": "ramonyx dev",
+    "build:edge": "ramonyx build --target edge",
+    "deploy": "ramonyx build --target edge && npx wrangler deploy"
+  },
+  "dependencies": {
+    "@ramonyx/adapter-runtime": "^2.0.2",
+    "@ramonyx/bundler": "^2.0.2",
+    "@ramonyx/compiler": "^2.0.2",
+    "@ramonyx/devtools": "^2.0.2",
+    "@ramonyx/react": "^2.0.2",
+    "@ramonyx/security": "^2.0.2",
+    "@ramonyx/server": "^2.0.2",
+    "@ramonyx/ssr": "^2.0.2",
+    "ramonyx": "^2.0.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0"
+  },
+  "imports": {
+    "#routes": "./.ramonyx/routes.ts"
+  }
+}

package/templates/cloudflare/src/routes/api/storage.ts

@@ -0,0 +1,97 @@
+import { type EnvReader, HttpError, route } from "ramonyx";
+
+// Cloudflare KV + R2 bindings (ADR-0068). Node dev has no bindings → 503.
+interface KVNamespaceLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { readonly expirationTtl?: number }): Promise<void>;
+}
+
+interface R2ObjectLike {
+  readonly size?: number;
+  readonly httpEtag?: string;
+  text(): Promise<string>;
+}
+
+interface R2BucketLike {
+  get(key: string): Promise<R2ObjectLike | null>;
+  put(
+    key: string,
+    value: string,
+    options?: { readonly httpMetadata?: { readonly contentType?: string } },
+  ): Promise<unknown>;
+}
+
+function sameSecret(a: string, b: string): boolean {
+  let diff = a.length ^ b.length;
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    diff |= (a.charCodeAt(index) || 0) ^ (b.charCodeAt(index) || 0);
+  }
+  return diff === 0;
+}
+
+function authorize(env: EnvReader, request: Request): void {
+  const expected = env.get("STORAGE_TOKEN");
+  if (expected === undefined || expected.length < 16) {
+    throw new HttpError(503, "STORAGE_TOKEN belum dikonfigurasi");
+  }
+  const header = request.headers.get("authorization") ?? "";
+  const supplied = header.startsWith("Bearer ") ? header.slice(7) : "";
+  if (!sameSecret(expected, supplied)) {
+    throw new HttpError(401, "Unauthorized");
+  }
+}
+
+function bindings(env: EnvReader): { kv: KVNamespaceLike; bucket: R2BucketLike } {
+  const kv = env.getRaw?.("KV_STORE") as KVNamespaceLike | undefined;
+  const bucket = env.getRaw?.("R2_BUCKET") as R2BucketLike | undefined;
+  if (kv === undefined || bucket === undefined) {
+    throw new HttpError(503, "Binding KV_STORE/R2_BUCKET tidak tersedia");
+  }
+  return { kv, bucket };
+}
+
+function keyFrom(value: unknown): string {
+  const key = String(value ?? "demo").trim();
+  if (key.length === 0 || key.length > 100) {
+    throw new HttpError(400, "key wajib 1–100 karakter");
+  }
+  return key;
+}
+
+export const GET = route({
+  handler: async ({ env, request, json }) => {
+    authorize(env, request);
+    const key = keyFrom(new URL(request.url).searchParams.get("key"));
+    const { kv, bucket } = bindings(env);
+    const [kvValue, object] = await Promise.all([kv.get(key), bucket.get(key)]);
+    if (kvValue === null && object === null) {
+      return json({ error: "Not Found" }, 404);
+    }
+    return json({
+      key,
+      kv: kvValue,
+      r2: object === null ? null : await object.text(),
+      size: object?.size ?? null,
+      etag: object?.httpEtag ?? null,
+    });
+  },
+});
+
+export const POST = route({
+  handler: async ({ env, request, json }) => {
+    authorize(env, request);
+    const body = (await request.json()) as { key?: unknown; value?: unknown };
+    const key = keyFrom(body.key);
+    const value = String(body.value ?? "");
+    if (value.length > 1024) {
+      return json({ error: "value maksimal 1024 karakter" }, 400);
+    }
+    const { kv, bucket } = bindings(env);
+    await Promise.all([
+      kv.put(key, value, { expirationTtl: 3600 }),
+      bucket.put(key, value, { httpMetadata: { contentType: "text/plain; charset=utf-8" } }),
+    ]);
+    return json({ ok: true, key }, 201);
+  },
+});

package/templates/cloudflare/src/routes/page.tsx

@@ -0,0 +1,48 @@
+export const metadata = {
+  title: "__APP_NAME__ — Cloudflare storage",
+  description: "Ramonyx on Cloudflare Workers with R2 object storage and KV metadata.",
+};
+
+export default function Home() {
+  return (
+    <main className="rw-main">
+      <section className="rw-hero">
+        <div className="rw-hero-copy">
+          <p className="rw-kicker">Cloudflare-native</p>
+          <h1>
+            Files in R2.
+            <br />
+            <span>Metadata in KV.</span>
+          </h1>
+          <p className="rw-lede">
+            This template ships a Worker artifact and real binding routes. The API reads and writes
+            both stores; the browser page is only a map of the surface.
+          </p>
+          <div className="rw-actions">
+            <a className="rw-button" href="/api/storage?key=demo">
+              Try the storage API
+            </a>
+            <a
+              className="rw-quiet"
+              href="https://ramonyx.devmoon.net/docs/recipes/cloudflare-r2-kv"
+            >
+              Read the R2 + KV recipe ↗
+            </a>
+          </div>
+          <pre className="rw-tree">{`GET  /api/storage?key=demo
+POST /api/storage
+  { "key": "demo", "value": "hello" }
+
+pnpm build:edge
+pnpm deploy`}</pre>
+        </div>
+        <aside className="rw-status">
+          <p className="rw-label">BINDINGS</p>
+          <p className="rw-url">KV_STORE</p>
+          <p className="rw-status-sub">R2_BUCKET</p>
+          <p className="rw-status-sub">Configure in wrangler.toml</p>
+        </aside>
+      </section>
+    </main>
+  );
+}

package/templates/cloudflare/wrangler.toml

@@ -0,0 +1,15 @@
+name = "__APP_NAME__"
+main = "dist/edge/index.js"
+compatibility_date = "2026-10-18"
+
+# Static client assets produced by `ramonyx build --target edge`.
+[assets]
+directory = "dist/client"
+
+[[kv_namespaces]]
+binding = "KV_STORE"
+id = "replace-with-your-kv-namespace-id"
+
+[[r2_buckets]]
+binding = "R2_BUCKET"
+bucket_name = "__APP_NAME__-files"

package/templates/docs-blog/README.md

@@ -0,0 +1,21 @@
+# __APP_NAME__ — docs/blog starter
+
+A content-first Ramonyx app with a static export:
+
+- `/` — post index
+- `/blog/[slug]` — prerendered posts via `getStaticPaths()`
+- `pnpm build:static` — HTML into `dist/static`, ready for Pages, Workers Assets, or any static host
+
+## Run
+
+```bash
+pnpm install
+pnpm dev
+pnpm build:static
+```
+
+Add posts in `src/data/posts.ts`; the dynamic route and static path list update together. Replace
+the in-memory post list with markdown/files or a CMS when you need real content workflow.
+
+The docs site (`apps/docs` in the repository) is a larger example of the same SSR + static export
+model.

package/templates/docs-blog/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "ramonyx build",
+    "start": "ramonyx start",
+    "dev": "ramonyx dev",
+    "build:static": "ramonyx build --static"
+  },
+  "dependencies": {
+    "@ramonyx/adapter-runtime": "^2.0.2",
+    "@ramonyx/bundler": "^2.0.2",
+    "@ramonyx/compiler": "^2.0.2",
+    "@ramonyx/devtools": "^2.0.2",
+    "@ramonyx/react": "^2.0.2",
+    "@ramonyx/security": "^2.0.2",
+    "@ramonyx/server": "^2.0.2",
+    "@ramonyx/ssr": "^2.0.2",
+    "ramonyx": "^2.0.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0"
+  },
+  "imports": {
+    "#routes": "./.ramonyx/routes.ts"
+  }
+}

package/templates/docs-blog/src/data/posts.ts

@@ -0,0 +1,45 @@
+export interface Post {
+  readonly slug: string;
+  readonly title: string;
+  readonly summary: string;
+  readonly body: readonly string[];
+  readonly published: string;
+}
+
+export const posts: readonly Post[] = [
+  {
+    slug: "hello-ramonyx",
+    title: "A content site with no client runtime",
+    summary: "Every page is server-rendered HTML that can also be exported statically.",
+    published: "2026-10-24",
+    body: [
+      "This starter renders a blog index and a dynamic post route on the server. No client-side data fetching is required for reading.",
+      "Run `pnpm build:static` to prerender every post into dist/static. The same route tree also runs with `pnpm build && pnpm start` for SSR.",
+    ],
+  },
+  {
+    slug: "markdown-next",
+    title: "Replace the demo data with Markdown",
+    summary:
+      "The post list is deliberately small and typed so a file/markdown source can replace it.",
+    published: "2026-10-24",
+    body: [
+      "`src/data/posts.ts` is the only content source. Swap it for a filesystem loader or a CMS client and keep the page contract.",
+      "Keep slugs validated and escape rendered HTML; never interpolate untrusted Markdown output without sanitizing it.",
+    ],
+  },
+  {
+    slug: "deploy-anywhere",
+    title: "Deploy to static hosting or a Node server",
+    summary: "The same pages can be exported, served by Ramonyx, or bundled for an edge target.",
+    published: "2026-10-24",
+    body: [
+      "Static export produces HTML and hashed assets, so it works on Pages, Workers Assets, or any object store with a CDN.",
+      "For dynamic features later, switch to the Node or edge target and add API routes without changing the blog URLs.",
+    ],
+  },
+];
+
+export function findPost(slug: string): Post | null {
+  return posts.find((post) => post.slug === slug) ?? null;
+}

package/templates/docs-blog/src/routes/blog/[slug]/page.tsx

@@ -0,0 +1,41 @@
+import type { PageProps } from "@ramonyx/react";
+import { HttpError, type PageLoaderContext } from "ramonyx";
+import { findPost, type Post, posts } from "../../../data/posts.ts";
+
+export const metadata = {
+  title: "__APP_NAME__ — post",
+  description: "A prerendered Ramonyx blog post.",
+};
+
+export function getStaticPaths() {
+  return posts.map((post) => ({ slug: post.slug }));
+}
+
+export function loader({ params }: PageLoaderContext<{ slug: string }>) {
+  const post = findPost(params.slug);
+  if (post === null) {
+    throw new HttpError(404, "Post not found");
+  }
+  return { post };
+}
+
+export default function PostPage({ data }: PageProps<{ post: Post }>) {
+  return (
+    <main className="rw-main">
+      <article className="rw-section" style={{ maxWidth: "72ch" }}>
+        <p className="rw-label">{data.post.published}</p>
+        <h1>{data.post.title}</h1>
+        {data.post.body.map((paragraph) => (
+          <p key={paragraph} className="rw-lede">
+            {paragraph}
+          </p>
+        ))}
+        <p>
+          <a className="rw-quiet" href="/">
+            ← All notes
+          </a>
+        </p>
+      </article>
+    </main>
+  );
+}

package/templates/docs-blog/src/routes/page.tsx

@@ -0,0 +1,47 @@
+import { posts } from "../data/posts.ts";
+
+export const metadata = {
+  title: "__APP_NAME__ — notes",
+  description: "A static-first blog and docs starter built with Ramonyx.",
+};
+
+export default function Home() {
+  return (
+    <main className="rw-main">
+      <section className="rw-hero">
+        <div className="rw-hero-copy">
+          <p className="rw-kicker">Docs / blog starter</p>
+          <h1>
+            Write once.
+            <br />
+            <span>Render as HTML.</span>
+          </h1>
+          <p className="rw-lede">
+            Typed posts, a dynamic route, and a static export. The reading experience needs no
+            client JavaScript.
+          </p>
+          <div className="rw-actions">
+            <a className="rw-button" href="/blog/hello-ramonyx">
+              Read the first post
+            </a>
+            <a className="rw-quiet" href="https://ramonyx.devmoon.net/docs/deployment">
+              Deployment guide ↗
+            </a>
+          </div>
+          <div className="rw-steps">
+            {posts.map((post, index) => (
+              <article className="rw-step" key={post.slug}>
+                <span className="rw-step-index">{String(index + 1).padStart(2, "0")}</span>
+                <h2>
+                  <a href={`/blog/${post.slug}`}>{post.title}</a>
+                </h2>
+                <p>{post.summary}</p>
+                <code>{post.published}</code>
+              </article>
+            ))}
+          </div>
+        </div>
+      </section>
+    </main>
+  );
+}