create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/server/api-routes.js

@@ -0,0 +1,237 @@
+import { existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import esbuild from "esbuild";
+import { pathToFileURL } from "node:url";
+/** Cache directory for transpiled API routes. */
+const apiCacheDir = join(process.cwd(), "node_modules", ".jen", "api-cache");
+/**
+ * Transpile a TypeScript API route file to JavaScript.
+ * Uses esbuild to convert TS → JS, bundle dependencies, and output as ESM.
+ * The transpiled file is cached in node_modules/.jen/api-cache with a timestamp
+ * in the filename to allow side-by-side versions if the file changes.
+ *
+ * Bundles the route with external dependencies excluded (preact, jenjs).
+ * This enables tree-shaking of server-only exports like loader().
+ *
+ * @param filePath - Absolute path to .ts file
+ * @returns Path to transpiled .mjs file in cache directory
+ * @throws If esbuild fails to transpile
+ */
+async function transpileApiRoute(filePath) {
+  const outfile = join(
+    apiCacheDir,
+    basename(filePath).replace(/\.ts$/, `.${Date.now()}.mjs`),
+  );
+  await esbuild.build({
+    entryPoints: [filePath],
+    outfile,
+    format: "esm",
+    platform: "node",
+    target: "es2022",
+    bundle: true,
+    external: ["preact", "preact-render-to-string", "jenjs"],
+    write: true,
+  });
+  return outfile;
+}
+/**
+ * Attempt to route and handle an API request.
+ * Returns true if the request was handled (success or error response sent),
+ * false if no matching API route exists (caller should try next handler).
+ *
+ * Routing:
+ * - /api/endpoint → site/api/endpoint.ts
+ * - /api/users/123 → site/api/users/[id].ts (dynamic params supported)
+ * - /api/ (no segments) → 404
+ *
+ * Resolution order:
+ * 1. Try exact file match (e.g., /api/hello → api/hello.ts)
+ * 2. Try dynamic route match (e.g., /api/123 → api/[id].ts)
+ *
+ * Process:
+ * 1. Validate request starts with /api/
+ * 2. Resolve route file (exact or dynamic match)
+ * 3. Transpile if TypeScript
+ * 4. Load module and find handler for HTTP method
+ * 5. Parse request body
+ * 6. Call handler with context
+ * 7. Serialize response (Response, string, or object)
+ *
+ * All errors send JSON response with error message.
+ * HTTP 405 (Method Not Allowed) if method handler not exported.
+ * HTTP 404 if no matching route file.
+ * HTTP 500 if handler throws or transpilation fails.
+ *
+ * @param opts - Options containing request, response, and site directory
+ * @returns true if handled, false if no API route found
+ */
+export async function tryHandleApiRoute(opts) {
+  const { req, res, siteDir } = opts;
+  const url = new URL(
+    req.url ?? "/",
+    `http://${req.headers.host ?? "localhost"}`,
+  );
+  const method = (req.method ?? "GET").toUpperCase();
+  // Only handle /api/* requests
+  if (!url.pathname.startsWith("/api/")) return false;
+  // Extract path segments after /api/ prefix
+  const pathParts = url.pathname
+    .slice("/api/".length)
+    .split("/")
+    .filter(Boolean);
+  // /api/ with no segments is 404
+  if (pathParts.length === 0) {
+    res.statusCode = 404;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: "API route not found" }));
+    return true;
+  }
+  // Resolve route file (exact match or dynamic)
+  let apiFile = null;
+  let routeParams = {};
+  // Try exact file match: /api/hello/world → api/hello/world.ts
+  const exactPath = join(
+    process.cwd(),
+    siteDir,
+    "api",
+    `${pathParts.join("/")}.ts`,
+  );
+  if (existsSync(exactPath)) {
+    apiFile = exactPath;
+  } else {
+    // Try dynamic route match: /api/users/123 → api/users/[id].ts
+    const basePath = join(process.cwd(), siteDir, "api");
+    for (let i = pathParts.length; i >= 1; i--) {
+      const staticSegments = pathParts.slice(0, i);
+      const dynamicSegments = pathParts.slice(i);
+      // Simple approach: check api/[param].ts for /api/123
+      // TODO: Support nested dynamic routes like api/users/[id]/posts/[postId].ts
+      if (staticSegments.length === 0 && dynamicSegments.length === 1) {
+        const paramFile = join(basePath, `[${dynamicSegments[0]}].ts`);
+        if (existsSync(paramFile)) {
+          apiFile = paramFile;
+          routeParams[dynamicSegments[0]] = dynamicSegments[0];
+          break;
+        }
+      }
+    }
+  }
+  if (!apiFile) {
+    res.statusCode = 404;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: "API route not found" }));
+    return true;
+  }
+  // Transpile TypeScript to JavaScript
+  let moduleUrl = apiFile;
+  if (apiFile.endsWith(".ts")) {
+    moduleUrl = await transpileApiRoute(apiFile);
+  }
+  // Load module and get method handlers
+  let mod;
+  try {
+    // Cache-busting query param ensures fresh module (important in dev mode)
+    mod = await import(pathToFileURL(moduleUrl).href + `?t=${Date.now()}`);
+  } catch (err) {
+    res.statusCode = 500;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(
+      JSON.stringify({
+        error: "Failed to load API route",
+        details: err.message,
+      }),
+    );
+    return true;
+  }
+  // Get handler for the HTTP method
+  const handler = mod[method];
+  if (!handler) {
+    res.statusCode = 405;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.setHeader("allow", Object.keys(mod).join(", "));
+    res.end(JSON.stringify({ error: `${method} not allowed` }));
+    return true;
+  }
+  // Parse request body
+  const body = await readRequestBody(req);
+  // Build handler context
+  const ctx = {
+    req,
+    res,
+    url,
+    method,
+    query: Object.fromEntries(url.searchParams.entries()),
+    body,
+    params: routeParams,
+  };
+  // Execute handler and serialize response
+  try {
+    const result = await handler(ctx);
+    // If handler manually wrote response, don't double-send
+    if (res.writableEnded) return true;
+    // Serialize Response object
+    if (result instanceof Response) {
+      res.statusCode = result.status;
+      result.headers.forEach((v, k) => res.setHeader(k, v));
+      const buf = Buffer.from(await result.arrayBuffer());
+      res.end(buf);
+      return true;
+    }
+    // Serialize string as plain text
+    if (typeof result === "string") {
+      res.statusCode = 200;
+      res.setHeader("content-type", "text/plain; charset=utf-8");
+      res.end(result);
+      return true;
+    }
+    // Serialize object as JSON (null is valid)
+    res.statusCode = 200;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(result ?? null));
+    return true;
+  } catch (err) {
+    res.statusCode = 500;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(
+      JSON.stringify({ error: "Internal server error", details: err.message }),
+    );
+    return true;
+  }
+}
+/**
+ * Parse request body based on Content-Type header.
+ * Reads all chunks from the request stream and deserializes based on content type.
+ *
+ * - GET/HEAD: Returns null (no body expected)
+ * - JSON (application/json): Parses and returns object; falls back to { __raw } if invalid JSON
+ * - Other: Returns { __raw } with raw body string
+ *
+ * This function is shared between different request handlers in the framework.
+ *
+ * @param req - Node.js IncomingMessage to read body from
+ * @returns Parsed body object or null
+ */
+async function readRequestBody(req) {
+  const method = (req.method ?? "GET").toUpperCase();
+  // Methods without bodies per HTTP spec
+  if (method === "GET" || method === "HEAD") return null;
+  // Read all body chunks
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(Buffer.from(chunk));
+  }
+  if (chunks.length === 0) return null;
+  const raw = Buffer.concat(chunks).toString("utf8");
+  const ct = (req.headers["content-type"] ?? "").toString();
+  // Try to parse JSON
+  if (ct.includes("application/json")) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      // Return raw body if JSON parsing fails
+      return { __raw: raw };
+    }
+  }
+  // Return raw body for non-JSON content
+  return { __raw: raw };
+}

package/templates/{static → ssr-isr}/lib/server/api.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 export declare function tryHandleApiRoute(opts: {
-    req: IncomingMessage;
-    res: ServerResponse;
-    siteDir: string;
+  req: IncomingMessage;
+  res: ServerResponse;
+  siteDir: string;
 }): Promise<boolean>;

package/templates/ssr-isr/lib/server/api.js

@@ -0,0 +1,108 @@
+import { existsSync } from "node:fs";
+import { join, normalize } from "node:path";
+import { pathToFileURL } from "node:url";
+const MAX_BODY_SIZE = 1024 * 1024; // 1MB
+const VALID_ROUTE_PATTERN = /^[a-zA-Z0-9_\-/]+$/; // Only alphanumeric, underscore, hyphen, forward slash
+function isValidRouteName(name) {
+  if (!name || name.length > 255) return false;
+  if (name.includes("..") || name.includes("\\") || name.startsWith("/"))
+    return false;
+  return VALID_ROUTE_PATTERN.test(name);
+}
+export async function tryHandleApiRoute(opts) {
+  const { req, res, siteDir } = opts;
+  const url = new URL(
+    req.url ?? "/",
+    `http://${req.headers.host ?? "localhost"}`,
+  );
+  if (!url.pathname.startsWith("/api/")) return false;
+  // /api/hello -> site/api/(hello).ts
+  let name = url.pathname.slice("/api/".length) || "home";
+  // Security: Validate route name to prevent path traversal
+  if (!isValidRouteName(name)) {
+    res.statusCode = 400;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: "Invalid API route format" }));
+    return true;
+  }
+  const file = join(process.cwd(), siteDir, "api", `(${name}).ts`);
+  // Ensure the resolved path is within the api directory (prevent directory traversal)
+  const apiDir = normalize(join(process.cwd(), siteDir, "api"));
+  if (!normalize(file).startsWith(apiDir)) {
+    res.statusCode = 403;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: "Forbidden" }));
+    return true;
+  }
+  if (!existsSync(file)) {
+    res.statusCode = 404;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(JSON.stringify({ error: "Not found" }));
+    return true;
+  }
+  // Use pathToFileURL to handle Windows paths correctly
+  const mod = await import(pathToFileURL(file).href + `?t=${Date.now()}`);
+  const handler = mod?.default;
+  if (typeof handler !== "function") {
+    res.statusCode = 500;
+    res.setHeader("content-type", "application/json; charset=utf-8");
+    res.end(
+      JSON.stringify({ error: "API route missing default export function" }),
+    );
+    return true;
+  }
+  const body = await readBody(req);
+  const ctx = {
+    req,
+    res,
+    url,
+    method: req.method ?? "GET",
+    query: Object.fromEntries(url.searchParams.entries()),
+    body,
+  };
+  const out = await handler(ctx);
+  if (res.writableEnded) return true;
+  if (out instanceof Response) {
+    res.statusCode = out.status;
+    out.headers.forEach((v, k) => res.setHeader(k, v));
+    const buf = Buffer.from(await out.arrayBuffer());
+    res.end(buf);
+    return true;
+  }
+  if (typeof out === "string") {
+    res.statusCode = 200;
+    res.setHeader("content-type", "text/plain; charset=utf-8");
+    res.end(out);
+    return true;
+  }
+  res.statusCode = 200;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(out ?? null));
+  return true;
+}
+async function readBody(req) {
+  const method = (req.method ?? "GET").toUpperCase();
+  if (method === "GET" || method === "HEAD") return null;
+  const chunks = [];
+  let totalSize = 0;
+  for await (const chunk of req) {
+    totalSize += chunk.length;
+    if (totalSize > MAX_BODY_SIZE) {
+      throw new Error(
+        `Request body exceeds maximum size of ${MAX_BODY_SIZE} bytes`,
+      );
+    }
+    chunks.push(Buffer.from(chunk));
+  }
+  if (chunks.length === 0) return null;
+  const raw = Buffer.concat(chunks).toString("utf8");
+  const ct = req.headers["content-type"] ?? "";
+  if (typeof ct === "string" && ct.includes("application/json")) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return { __raw: raw };
+    }
+  }
+  return { __raw: raw };
+}

package/templates/ssr-isr/lib/server/app.d.ts

@@ -0,0 +1,44 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FrameworkConfig } from "../core/config.js";
+/**
+ * Server mode determines rendering strategy and asset serving behavior.
+ * - "dev": Development mode with HMR, live SCSS compilation, file watching
+ * - "prod": Production mode with pre-built assets, no live compilation
+ */
+type AppMode = "dev" | "prod";
+/**
+ * Creates and configures the main HTTP application handler.
+ *
+ * Initializes the middleware chain for handling requests in the following order:
+ * 1. Request logging
+ * 2. Internal runtime modules (hydration, HMR)
+ * 3. API route handling
+ * 4. Static dist directory serving (prod mode)
+ * 5. SCSS compilation (dev mode)
+ * 6. Site assets serving (dev mode)
+ * 7. Server-side rendering (SSR) of route pages
+ * 8. 404 fallback
+ *
+ * In development mode, sets up file watching on the site directory to enable:
+ * - Hot Module Replacement (HMR) via Server-Sent Events (SSE)
+ * - Hot CSS reload for SCSS changes
+ * - Full page reload for JavaScript/TypeScript/framework file changes
+ * - Module and compiler cache invalidation
+ *
+ * @param opts Configuration object
+ * @param opts.config Jen.js framework configuration with routes, directories, etc.
+ * @param opts.mode "dev" for development or "prod" for production
+ * @param opts.viteServer Optional Vite dev server instance for HMR (dev mode only)
+ *
+ * @returns Promise resolving to an object with handle() method for processing HTTP requests
+ *
+ * @throws {Error} If route scanning fails due to invalid route patterns
+ */
+export declare function createApp(opts: {
+  config: FrameworkConfig;
+  mode: AppMode;
+  viteServer?: any;
+}): Promise<{
+  handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}>;
+export {};