create-ramonyx-app 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ramonymous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# create-ramonyx-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Scaffolder aplikasi Ramonyx — SSR React + hydration, file routing `src/routes`.
+
+> **Alpha (0.1.0)** — butuh **Node.js ≥ 24**.
+
+## Pemakaian
+
+```bash
+pnpm create ramonyx-app aplikasi-saya
+# atau tanpa install:
+pnpm dlx create-ramonyx-app aplikasi-saya
+```
+
+Lanjutkan dengan `cd aplikasi-saya && pnpm install && pnpm build && pnpm start`.
+
+Repo: https://github.com/RamonyxJS/ramonyx · Lisensi: MIT

package/dist/cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+// apps/create-app/src/cli.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var templateDir = join(dirname(fileURLToPath(import.meta.url)), "..", "template");
+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)
+
+Opsi:
+  --force, -f   Timpa berkas template walau direktori tujuan tidak kosong
+  --help, -h    Tampilkan bantuan ini
+`;
+function usage(exitCode) {
+  const write = exitCode === 0 ? console.log : console.error;
+  write(USAGE);
+  process.exit(exitCode);
+}
+var args = process.argv.slice(2);
+var force = false;
+var target;
+for (const arg of args) {
+  if (arg === "--force" || arg === "-f") {
+    force = true;
+  } else if (arg === "--help" || arg === "-h") {
+    usage(0);
+  } else if (arg.startsWith("-")) {
+    console.error(`error: flag tidak dikenal: ${arg}`);
+    usage(1);
+  } else if (target === void 0) {
+    target = arg;
+  } else {
+    console.error(`error: argumen tak terduga: ${arg}`);
+    usage(1);
+  }
+}
+if (target === void 0) {
+  console.error("error: direktori tujuan wajib");
+  usage(1);
+}
+var targetDir = resolve(target);
+var appName = basename(targetDir);
+if (existsSync(targetDir)) {
+  if (!statSync(targetDir).isDirectory()) {
+    console.error(`error: ${target} bukan direktori`);
+    process.exit(1);
+  }
+  const entries = readdirSync(targetDir);
+  if (entries.length > 0 && !force) {
+    console.error(`error: ${target} tidak kosong (pakai --force untuk menimpa berkas template)`);
+    process.exit(1);
+  }
+} else {
+  mkdirSync(targetDir, { recursive: true });
+}
+function copy(source, destination) {
+  if (statSync(source).isDirectory()) {
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(source)) {
+      copy(join(source, entry), join(destination, entry));
+    }
+    return;
+  }
+  const name = basename(source) === "gitignore" ? ".gitignore" : basename(source);
+  const text = readFileSync(source, "utf8").replaceAll("__APP_NAME__", appName);
+  writeFileSync(join(dirname(destination), name), text);
+}
+copy(templateDir, targetDir);
+console.log(`\u2713 App "${appName}" dibuat di ${targetDir}
+
+Langkah berikutnya:
+
+  cd ${target}
+  pnpm install   # atau npm install
+  pnpm start     # http://127.0.0.1:3000
+`);

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "create-ramonyx-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Scaffolder aplikasi Ramonyx (SSR React + hydration, file routing src/routes).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-ramonyx-app": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RamonyxJS/ramonyx"
+  }
 }

package/template/README.md

@@ -0,0 +1,28 @@
+# __APP_NAME__
+
+Aplikasi [Ramonyx](https://github.com/ramonyx/ramonyx) — framework full-stack TypeScript
+(Node ≥ 24): halaman **SSR React + hydration** dan route API, dengan konvensi folder
+`src/routes`.
+
+## Menjalankan
+
+```bash
+pnpm install
+pnpm build     # bundel klien (wajib sebelum start)
+pnpm start     # http://127.0.0.1:3000 (React build produksi: NODE_ENV=production)
+pnpm dev       # mode watch (jalankan `pnpm build` setelah mengubah UI klien)
+```
+
+## Struktur
+
+- `src/routes/page.tsx` — halaman (loader + komponen React; `layout.tsx`/`error.tsx` opsional)
+- `src/routes/api/halo/[nama].ts` — route API (`export const GET = route({ ... })`)
+- `src/routes/middleware.ts` — security headers + CSP nonce + aset `/assets/*`
+- `build.ts` — bundel klien (Vite) lewat `@ramonyx/bundler`
+- `ramonyx.config.ts` — port/host + strict validation
+
+## Endpoint contoh
+
+- `GET /` — halaman SSR (tombol counter membuktikan hydration)
+- `GET /api/halo/dunia` — JSON `{ "halo": "dunia" }`
+- `GET /api/rahasia` — contoh `HttpError` (403)

package/template/build.ts

@@ -0,0 +1,13 @@
+// Build client (React + hydration) lewat Vite — jalankan `pnpm build` sebelum `pnpm start`
+// di produksi. Hasil: `dist/client/client.js` disajikan di `/assets/client.js`.
+
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildClient } from "@ramonyx/bundler";
+import { loadPageRoutes } from "@ramonyx/compiler";
+
+const appDir = fileURLToPath(new URL(".", import.meta.url));
+const pages = await loadPageRoutes({ dir: join(appDir, "src/routes") });
+const result = await buildClient({ appDir, pages });
+
+console.log(`✓ client bundle: ${result.scriptPath} (${result.outDir})`);

package/template/gitignore

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

package/template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "node --import @ramonyx/compiler/register build.ts",
+    "start": "NODE_ENV=production node --import @ramonyx/compiler/register src/main.ts",
+    "dev": "node --watch --import @ramonyx/compiler/register src/main.ts"
+  },
+  "dependencies": {
+    "@ramonyx/adapter-runtime": "^0.1.0",
+    "@ramonyx/bundler": "^0.1.0",
+    "@ramonyx/compiler": "^0.1.0",
+    "@ramonyx/react": "^0.1.0",
+    "@ramonyx/security": "^0.1.0",
+    "@ramonyx/server": "^0.1.0",
+    "@ramonyx/ssr": "^0.1.0",
+    "ramonyx": "^0.1.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+# Konfigurasi pnpm untuk aplikasi Ramonyx.
+#
+# `esbuild` (loader runtime `@ramonyx/compiler/register`) menjalankan postinstall untuk
+# memverifikasi binary platform; pnpm ≥10 memblokir build script dependensi secara default.
+# npm/yarn tidak memblokir → baris ini hanya relevan untuk pengguna pnpm.
+allowBuilds:
+  esbuild: true

package/template/ramonyx.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "ramonyx";
+
+export default defineConfig({
+  app: {
+    strictValidation: true,
+  },
+  server: {
+    port: 3000,
+    host: "127.0.0.1",
+  },
+});

package/template/src/app.ts

@@ -0,0 +1,38 @@
+import { fileURLToPath } from "node:url";
+import { createRouteManifest, loadPageRoutes } from "@ramonyx/compiler";
+import { createReactRenderer } from "@ramonyx/react";
+import { createHandler } from "@ramonyx/server";
+import { createPageRoutes } from "@ramonyx/ssr";
+import type { FetchHandler } from "ramonyx";
+
+import middleware from "./routes/middleware.ts";
+
+/**
+ * Aplikasi __APP_NAME__: route API + halaman SSR React dari `src/routes` (file routing),
+ * dengan hydration klien (`/assets/client.js` — jalankan `pnpm build` dulu).
+ *
+ * Konvensi folder `src/routes`:
+ * - `page.tsx` — halaman (loader + komponen React; boleh `layout.tsx`, `error.tsx`);
+ * - `api/*.ts` — route API (`export const GET = route({ ... })`).
+ */
+export async function createApp(): Promise<FetchHandler> {
+  const dir = fileURLToPath(new URL("./routes", import.meta.url));
+
+  const [apiRoutes, pages] = await Promise.all([
+    createRouteManifest({ dir }),
+    loadPageRoutes({ dir }),
+  ]);
+
+  return createHandler({
+    strictValidation: true,
+    routes: [
+      ...apiRoutes,
+      ...createPageRoutes({
+        pages,
+        renderer: createReactRenderer(),
+        client: { script: "/assets/client.js" },
+      }),
+    ],
+    middleware,
+  });
+}

package/template/src/main.ts

@@ -0,0 +1,16 @@
+import { createNodeHost } from "@ramonyx/adapter-runtime";
+import { resolveConfig } from "ramonyx";
+
+import config from "../ramonyx.config.ts";
+import { createApp } from "./app.ts";
+
+const resolved = resolveConfig(config);
+const host = createNodeHost();
+const app = await createApp();
+
+const server = await host.serve(app, {
+  port: resolved.server.port,
+  host: resolved.server.host,
+});
+
+console.log(`__APP_NAME__ berjalan di ${server.url}`);

package/template/src/routes/api/halo/[nama].ts

@@ -0,0 +1,6 @@
+import { route } from "ramonyx";
+
+// Route API dinamis: `GET /api/halo/[nama]`.
+export const GET = route<{ nama: string }>({
+  handler: ({ params, json }) => json({ halo: params.nama }),
+});

package/template/src/routes/api/rahasia.ts

@@ -0,0 +1,8 @@
+import { HttpError, route } from "ramonyx";
+
+// Contoh error HTTP aman (status + pesan publik).
+export const GET = route({
+  handler: () => {
+    throw new HttpError(403, "Tidak untukmu");
+  },
+});

package/template/src/routes/layout.tsx

@@ -0,0 +1,16 @@
+import type { LayoutProps } from "@ramonyx/react";
+
+export default function RootLayout({ children }: LayoutProps) {
+  return (
+    <div className="shell">
+      <header className="topbar">
+        <strong>__APP_NAME__</strong>
+        <span>Ramonyx</span>
+      </header>
+      {children}
+      <footer className="kaki">
+        Dibuat dengan Ramonyx — <code>src/routes</code> berisi halaman & API.
+      </footer>
+    </div>
+  );
+}

package/template/src/routes/middleware.ts

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { extname, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cspNonce, securityHeaders } from "@ramonyx/security";
+import type { Middleware } from "ramonyx";
+
+const clientDir = fileURLToPath(new URL("../../dist/client", import.meta.url));
+
+const CONTENT_TYPES: Record<string, string> = {
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+};
+
+/** Aset statis hasil `pnpm build` di `/assets/*` (guard traversal). */
+const staticAssets: Middleware = async (context, next) => {
+  const url = new URL(context.request.url);
+  if (context.request.method !== "GET" || !url.pathname.startsWith("/assets/")) {
+    return next();
+  }
+
+  const relativePath = decodeURIComponent(url.pathname.slice("/assets/".length));
+  const filePath = resolve(clientDir, relativePath);
+  if (!filePath.startsWith(clientDir + sep)) {
+    return next();
+  }
+
+  try {
+    const data = await readFile(filePath);
+    return new Response(data, {
+      headers: {
+        "content-type": CONTENT_TYPES[extname(filePath)] ?? "application/octet-stream",
+        "cache-control": "no-store",
+      },
+    });
+  } catch {
+    return next();
+  }
+};
+
+export default [securityHeaders(), cspNonce(), staticAssets] satisfies Middleware[];

package/template/src/routes/page.tsx

@@ -0,0 +1,37 @@
+import type { PageProps } from "@ramonyx/react";
+import { useState } from "react";
+
+export const metadata = { title: "__APP_NAME__" };
+
+export async function loader() {
+  return { pesan: "Halo dari SSR Ramonyx", fitur: ["SSR React", "hydration", "route API"] };
+}
+
+/** Komponen interaktif: server merender 0, klik menambah setelah hydration. */
+function Counter() {
+  const [hitungan, setHitungan] = useState(0);
+  return (
+    <p>
+      <button type="button" onClick={() => setHitungan((nilai) => nilai + 1)}>
+        Klik saya: {hitungan}
+      </button>
+    </p>
+  );
+}
+
+export default function Beranda({ data }: PageProps<{ pesan: string; fitur: string[] }>) {
+  return (
+    <main>
+      <h1>{data.pesan}</h1>
+      <ul>
+        {data.fitur.map((item) => (
+          <li key={item}>{item}</li>
+        ))}
+      </ul>
+      <Counter />
+      <p>
+        Coba API dinamis: <a href="/api/halo/dunia">/api/halo/dunia</a>
+      </p>
+    </main>
+  );
+}