create-ramonyx-app 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Scaffolder aplikasi Ramonyx — SSR React + hydration, file routing `src/routes`.
 
-> **Alpha (0.1.0)** — butuh **Node.js ≥ 24**.
+> **Alpha (0.2.0)** — butuh **Node.js ≥ 24**.
 
 ## Pemakaian
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ramonyx-app",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffolder aplikasi Ramonyx (SSR React + hydration, file routing src/routes).",
   "license": "MIT",
   "type": "module",

package/template/README.md

@@ -8,17 +8,19 @@ Aplikasi [Ramonyx](https://github.com/ramonyx/ramonyx) — framework full-stack
 
 ```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)
+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/*`
-- `build.ts` — bundel klien (Vite) lewat `@ramonyx/bundler`
 - `ramonyx.config.ts` — port/host + strict validation
 
 ## Endpoint contoh

package/template/package.json

@@ -6,19 +6,20 @@
     "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"
+    "build": "ramonyx build",
+    "start": "ramonyx start",
+    "dev": "ramonyx dev"
   },
   "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",
+    "@ramonyx/adapter-runtime": "^0.2.0",
+    "@ramonyx/bundler": "^0.2.0",
+    "@ramonyx/compiler": "^0.2.0",
+    "@ramonyx/devtools": "^0.2.0",
+    "@ramonyx/react": "^0.2.0",
+    "@ramonyx/security": "^0.2.0",
+    "@ramonyx/server": "^0.2.0",
+    "@ramonyx/ssr": "^0.2.0",
+    "ramonyx": "^0.2.0",
     "react": "19.3.1",
     "react-dom": "19.3.1"
   },

package/template/src/app.ts

@@ -1,38 +1,87 @@
 import { fileURLToPath } from "node:url";
-import { createRouteManifest, loadPageRoutes } from "@ramonyx/compiler";
+import { serveStatic } from "@ramonyx/adapter-runtime";
+import { createAssetResolver } from "@ramonyx/bundler";
+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 { createPageRoutes, createSeoRoutes } from "@ramonyx/ssr";
+import type { AppHooks, FetchHandler } from "ramonyx";
 
-import middleware from "./routes/middleware.ts";
+// Aset statis hanya untuk host Node (edge: platform menyajikan aset; `middleware.ts` tetap
+// edge-safe agar `ramonyx build --target edge` bisa membundelnya — ADR-0058).
+const clientDir = fileURLToPath(new URL("../dist/client", import.meta.url));
+// Resolver aset (ADR-0069): produksi memakai manifest (ber-hash); dev memakai fallback
+// (`fallbackToPath`) yang disajikan Vite dari `src/assets/**`.
+const assets = await createAssetResolver(clientDir, { fallbackToPath: true });
+const staticAssets = serveStatic({
+  dir: clientDir,
+  prefix: "/assets",
+  immutable: true,
+  headers: { "x-content-type-options": "nosniff" },
+});
+
+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;
+  /** Cache data loader (ADR-0066) — halaman ber-`revalidate` memakainya. */
+  readonly cache?: import("ramonyx").Cache;
+  /** Hook aplikasi (plugin/CLI — ADR-0065/0067). */
+  readonly hooks?: AppHooks;
+}
 
 /**
  * Aplikasi __APP_NAME__: route API + halaman SSR React dari `src/routes` (file routing),
- * dengan hydration klien (`/assets/client.js` — jalankan `pnpm build` dulu).
+ * dengan hydration klien.
  *
- * Konvensi folder `src/routes`:
- * - `page.tsx` — halaman (loader + komponen React; boleh `layout.tsx`, `error.tsx`);
- * - `api/*.ts` — route API (`export const GET = route({ ... })`).
+ * Dijalankan lewat CLI: `ramonyx dev` (Vite + HMR), `ramonyx build` (bundle klien),
+ * `ramonyx start` (produksi — `NODE_ENV=production` otomatis).
  */
-export async function createApp(): Promise<FetchHandler> {
+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 }),
+    ]);
+    // /sitemap.xml + /robots.txt dari manifest halaman (ADR-0059).
+    const seoRoutes = await createSeoRoutes({ pages });
 
-  const [apiRoutes, pages] = await Promise.all([
-    createRouteManifest({ dir }),
-    loadPageRoutes({ dir }),
-  ]);
+    return createHandler({
+      routes: [
+        ...apiRoutes,
+        ...seoRoutes,
+        ...createPageRoutes({
+          pages,
+          renderer: createReactRenderer(),
+          client,
+          streaming: options.streaming,
+          cache: options.cache,
+          hooks: options.hooks,
+          assets,
+        }),
+      ],
+      middleware: [staticAssets],
+      strictValidation: options.strictValidation,
+      hooks: options.hooks,
+    });
+  };
 
-  return createHandler({
-    strictValidation: true,
-    routes: [
-      ...apiRoutes,
-      ...createPageRoutes({
-        pages,
-        renderer: createReactRenderer(),
-        client: { script: "/assets/client.js" },
-      }),
-    ],
-    middleware,
-  });
+  if (options.reloadManifests === true) {
+    return async (request) => (await build())(request);
+  }
+  return build();
 }

package/template/src/assets/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="Logo">
+  <rect width="32" height="32" rx="7" fill="#7cc4ff"/>
+  <text x="16" y="22" font-family="system-ui, sans-serif" font-size="18" font-weight="700" text-anchor="middle" fill="#0f1115">R</text>
+</svg>

package/template/src/routes/[...slug]/page.tsx

@@ -0,0 +1,19 @@
+import type { PageProps } from "@ramonyx/react";
+
+export const metadata = { title: "Tidak ditemukan", status: 404 };
+/** Halaman 404 catch-all — tidak diprerender (rutenya tak terbatas). */
+export const prerender = false;
+
+export default function TidakDitemukan({ params }: PageProps<unknown>) {
+  return (
+    <main>
+      <h1>404 — Tidak ditemukan</h1>
+      <p>
+        Halaman <code>/{params.slug}</code> tidak ada.
+      </p>
+      <p>
+        <a href="/">Kembali ke beranda</a>
+      </p>
+    </main>
+  );
+}

package/template/src/routes/middleware.ts

@@ -1,42 +1,10 @@
-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[];
+/**
+ * Middleware aplikasi — **edge-safe** (Web Crypto + web standard saja; tanpa `node:*`),
+ * sehingga `ramonyx build --target edge` dapat membundelnya.
+ *
+ * Penyajian aset statis (`serveStatic`) adalah urusan host Node dan dipasang di `src/app.ts`.
+ */
+export default [securityHeaders(), cspNonce()] satisfies Middleware[];

package/template/src/routes/page.tsx

@@ -1,10 +1,30 @@
 import type { PageProps } from "@ramonyx/react";
+import { Image } from "@ramonyx/react/assets";
+import type { PageActionContext } from "ramonyx";
 import { useState } from "react";
 
-export const metadata = { title: "__APP_NAME__" };
+export const metadata = {
+  title: "__APP_NAME__",
+  description: "Aplikasi Ramonyx — SSR React, file routing, dan server actions.",
+};
+/** Cache data loader 60 dtk (ADR-0066) — hapus atau sesuaikan bila data harus selalu segar. */
+export const revalidate = 60;
 
-export async function loader() {
-  return { pesan: "Halo dari SSR Ramonyx", fitur: ["SSR React", "hydration", "route API"] };
+export async function loader({ assets }: { assets?: { url(path: string): string | undefined } }) {
+  return {
+    pesan: "Halo dari SSR Ramonyx",
+    fitur: ["SSR React", "hydration", "route API"],
+    logo: assets?.url("logo.svg"),
+  };
+}
+
+/** Mutasi form: POST ke path yang sama (progressive enhancement — ADR-0057). */
+export function action({ formData }: PageActionContext) {
+  const nama = String(formData.get("nama") ?? "").trim();
+  if (nama.length < 2) {
+    return { errors: { nama: "Nama minimal 2 karakter" } };
+  }
+  return { message: `Halo, ${nama}!` };
 }
 
 /** Komponen interaktif: server merender 0, klik menambah setelah hydration. */
@@ -19,16 +39,30 @@ function Counter() {
   );
 }
 
-export default function Beranda({ data }: PageProps<{ pesan: string; fitur: string[] }>) {
+export default function Beranda({
+  data,
+  action,
+}: PageProps<{ pesan: string; fitur: string[]; logo?: string }>) {
   return (
     <main>
-      <h1>{data.pesan}</h1>
+      <h1>
+        <Image src={data.logo} alt="Logo" width={32} height={32} /> {data.pesan}
+      </h1>
       <ul>
         {data.fitur.map((item) => (
           <li key={item}>{item}</li>
         ))}
       </ul>
       <Counter />
+      <h2>Form dengan action</h2>
+      <form method="post">
+        <label>
+          Nama: <input name="nama" />
+        </label>
+        <button type="submit">Kirim</button>
+      </form>
+      {action?.errors?.nama !== undefined ? <p role="alert">{action.errors.nama}</p> : null}
+      {action?.message !== undefined ? <p role="status">{action.message}</p> : null}
       <p>
         Coba API dinamis: <a href="/api/halo/dunia">/api/halo/dunia</a>
       </p>

package/template/build.ts

@@ -1,13 +0,0 @@
-// 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/src/main.ts

@@ -1,16 +0,0 @@
-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}`);