create-ramonyx-app 0.0.0-stage → 0.1.1

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.1)** — 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.1",
+  "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,30 @@
+# __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 dev       # Vite + HMR (http://localhost:5173) → SSR :3000
+pnpm build     # bundel klien (wajib sebelum start produksi)
+pnpm start     # http://127.0.0.1:3000 (NODE_ENV=production otomatis)
+```
+
+Perintah memakai CLI **`ramonyx`** (`@ramonyx/devtools`): `ramonyx dev|build|start|doctor`.
+
+## Struktur
+
+- `src/app.ts` — mengekspor `createApp(options?)` (dipakai CLI)
+- `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/*`
+- `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/gitignore

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

package/template/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "ramonyx build",
+    "start": "ramonyx start",
+    "dev": "ramonyx dev"
+  },
+  "dependencies": {
+    "@ramonyx/compiler": "^0.1.0",
+    "@ramonyx/devtools": "^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,63 @@
+import { fileURLToPath } from "node:url";
+import { createRouteManifest, loadPageRoutes, type ModuleImporter } 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";
+
+export interface CreateAppOptions {
+  /** URL bundle klien (produksi "/assets/client.js"; dev via entry Vite). */
+  readonly clientScript?: string;
+  /** Modul tambahan sebelum entry (mis. "/@vite/client"). */
+  readonly clientModules?: readonly string[];
+  /** Importer modul (dev: module graph Vite). */
+  readonly importer?: ModuleImporter;
+  /** Bangun ulang manifest tiap request (dev, tanpa restart). */
+  readonly reloadManifests?: boolean;
+  readonly strictValidation?: boolean;
+  /** SSR streaming untuk halaman (ADR-0047). */
+  readonly streaming?: boolean;
+}
+
+/**
+ * Aplikasi __APP_NAME__: route API + halaman SSR React dari `src/routes` (file routing),
+ * dengan hydration klien.
+ *
+ * Dijalankan lewat CLI: `ramonyx dev` (Vite + HMR), `ramonyx build` (bundle klien),
+ * `ramonyx start` (produksi — `NODE_ENV=production` otomatis).
+ */
+export async function createApp(options: CreateAppOptions = {}): Promise<FetchHandler> {
+  const dir = fileURLToPath(new URL("./routes", import.meta.url));
+  const client =
+    options.clientScript === undefined
+      ? undefined
+      : { script: options.clientScript, extraModules: options.clientModules };
+
+  const build = async (): Promise<FetchHandler> => {
+    const [apiRoutes, pages] = await Promise.all([
+      createRouteManifest({ dir, importer: options.importer }),
+      loadPageRoutes({ dir, importer: options.importer }),
+    ]);
+
+    return createHandler({
+      routes: [
+        ...apiRoutes,
+        ...createPageRoutes({
+          pages,
+          renderer: createReactRenderer(),
+          client,
+          streaming: options.streaming,
+        }),
+      ],
+      middleware,
+      strictValidation: options.strictValidation,
+    });
+  };
+
+  if (options.reloadManifests === true) {
+    return async (request) => (await build())(request);
+  }
+  return build();
+}

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>
+  );
+}