create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/runtime/islands.js

@@ -0,0 +1,110 @@
+/**
+ * Mark a component as an interactive island for partial hydration.
+ * Islands are components that require client-side interactivity while the rest of the page
+ * remains static HTML. This enables efficient selective hydration.
+ *
+ * How it works:
+ * - Marks component with metadata (__island, __hydrationStrategy)
+ * - Server renderer detects marked components and emits HTML comments with island metadata
+ * - Client JavaScript discovers islands from HTML comments and hydrates based on strategy
+ *
+ * Usage in route:
+ *   import { Island } from "jenjs";
+ *   import CounterImpl from "./counter.tsx";
+ *   export default function Page() {
+ *     const Counter = Island(CounterImpl, "load");
+ *     return <Counter count={5} />;
+ *   }
+ *
+ * Strategies:
+ * - "load": Best for above-the-fold critical interactive components
+ * - "idle": Good for secondary interactive elements (lighter priority)
+ * - "visible": Best for below-the-fold components; hydrates only when scrolled into view
+ *
+ * @param Component - The Preact component to mark as an island.
+ * @param strategy - Hydration timing strategy.
+ * @returns The same component with island metadata attached.
+ */
+export function Island(Component, strategy) {
+  // Mark component metadata for server-side detection during SSR
+  Component.__island = true;
+  Component.__hydrationStrategy = strategy;
+  return Component;
+}
+/**
+ * Generate an HTML comment marker that encodes island metadata.
+ * Server renderer calls this after rendering each island component.
+ * The marker is embedded in the HTML and later parsed by the client.
+ *
+ * Format: <!--__ISLAND_{STRATEGY}__:{id}:{componentPath}:{propsJson}-->
+ * Example: <!--__ISLAND_LOAD__:island-1:./counter.js:{"count":5}-->
+ *
+ * Note: '<' in JSON is escaped to '\\u003c' to prevent breaking HTML parsing
+ * (literal '<' in props could confuse the HTML parser or regex extraction).
+ *
+ * @param id - Unique identifier for the island (e.g., "island-1", "counter-2").
+ * @param componentPath - Path to the component module.
+ * @param strategy - Hydration timing strategy.
+ * @param props - Component props object (will be JSON.stringify'd).
+ * @returns HTML comment string encoding the island metadata.
+ */
+export function createIslandMarker(id, componentPath, strategy, props) {
+  const propsJson = JSON.stringify(props).replace(/</g, "\\u003c");
+  return `<!--__ISLAND_${strategy.toUpperCase()}__:${id}:${componentPath}:${propsJson}-->`;
+}
+/**
+ * Extract island metadata from server-rendered HTML.
+ * Client-side function that parses island markers from HTML comments.
+ * Called during page initialization to discover which components need hydration.
+ *
+ * Parsing strategy:
+ * - Regex finds HTML comments matching the island marker format
+ * - Extracts strategy, id, componentPath, and props from comment
+ * - Validates all fields are present and props are valid JSON
+ * - Logs warnings for invalid markers but continues processing remaining islands
+ *
+ * Return value includes only valid, parseable islands; invalid ones are skipped.
+ *
+ * @param html - Server-rendered HTML string (typically document.body.innerHTML or full page HTML).
+ * @returns Array of detected islands with complete metadata ready for hydration.
+ */
+export function extractIslandsFromHtml(html) {
+  const islands = [];
+  // Regex to match: <!--__ISLAND_{LOAD|IDLE|VISIBLE}__:id:componentPath:propsJson-->
+  const regex = /<!--__ISLAND_(LOAD|IDLE|VISIBLE)__:([^:]+):([^:]+):(.+?)-->/g;
+  let match;
+  while ((match = regex.exec(html)) !== null) {
+    const strategy = match[1].toLowerCase();
+    const id = match[2];
+    const componentPath = match[3];
+    // Unescape '<' back to literal character
+    const propsStr = match[4].replace(/\\u003c/g, "<");
+    // Validate required fields
+    if (!id || !componentPath) {
+      console.warn("Invalid island marker: missing id or componentPath");
+      continue;
+    }
+    try {
+      // Parse props JSON and validate it's an object
+      const props = JSON.parse(propsStr);
+      if (typeof props !== "object" || props === null) {
+        console.warn(
+          `Invalid props for island ${id}: expected object, got ${typeof props}`,
+        );
+        continue;
+      }
+      islands.push({
+        id,
+        component: componentPath,
+        strategy,
+        props,
+      });
+    } catch (err) {
+      console.warn(
+        `Failed to parse props for island ${id}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+  return islands;
+}

package/templates/ssr-isr/lib/runtime/render.d.ts

@@ -0,0 +1,40 @@
+import type { FrameworkConfig } from "../core/config.js";
+import type { RouteEntry } from "../core/routes/scan.js";
+/**
+ * Renders a route module to a complete HTML document.
+ * This function handles the entire server-side rendering pipeline:
+ * 1. Compiles TypeScript/JSX/Vue/Svelte to JavaScript if needed
+ * 2. Imports the compiled route module
+ * 3. Executes route-level middleware
+ * 4. Calls the loader to fetch data
+ * 5. Renders the component to HTML using Preact
+ * 6. Wraps the component HTML in a full document with hydration metadata if enabled
+ *
+ * Compilation is performed at request-time in development (for fast iteration) and at build-time in production.
+ * The route module must export a default Preact component and may optionally export a loader function,
+ * middleware, a Head component, and hydration strategy metadata.
+ *
+ * @param opts Configuration and context for rendering.
+ * @param opts.config The framework configuration.
+ * @param opts.route The route entry being rendered.
+ * @param opts.req The Node.js IncomingMessage (optional for SSG).
+ * @param opts.res The Node.js ServerResponse (optional for SSG).
+ * @param opts.url The parsed request URL.
+ * @param opts.params Dynamic route parameters extracted from the URL.
+ * @param opts.query Query string parameters.
+ * @param opts.headers HTTP request headers.
+ * @param opts.cookies Parsed cookies from the request.
+ * @returns The complete HTML document as a string.
+ * @throws Error if the route module fails to compile, import, or render.
+ */
+export declare function renderRouteToHtml(opts: {
+  config: FrameworkConfig;
+  route: RouteEntry;
+  req?: any;
+  res?: any;
+  url: URL;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+}): Promise<string>;

package/templates/ssr-isr/lib/runtime/render.js

@@ -0,0 +1,244 @@
+import {
+  createRouteMiddlewareContext,
+  executeRouteMiddleware,
+} from "../core/middleware-hooks.js";
+import { createIslandMarker } from "./islands.js";
+import { h } from "preact";
+import renderToString from "preact-render-to-string";
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+import { mkdirSync, existsSync } from "node:fs";
+import esbuild from "esbuild";
+import {
+  vueEsbuildPlugin,
+  svelteEsbuildPlugin,
+} from "../compilers/esbuild-plugins.js";
+/**
+ * Escapes HTML special characters to prevent injection attacks.
+ * Used when serializing user data or dynamic values into HTML attributes or script content.
+ *
+ * @param s The string to escape.
+ * @returns The escaped string safe for inclusion in HTML.
+ */
+function escapeHtml(s) {
+  return s
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+/**
+ * Resolves the cache directory path for compiled route modules.
+ * Transpiled TypeScript/JSX/Vue/Svelte routes are cached to avoid repeated compilation.
+ * Cache is stored in node_modules/.jen/cache to leverage .gitignore and keep the workspace clean.
+ * Path names are flattened to avoid nested directory creation issues on Windows.
+ *
+ * @param filePath The absolute path to the original source file.
+ * @returns The absolute path to the cached compiled output file.
+ */
+function getCachePath(filePath) {
+  const cacheDir = join(process.cwd(), "node_modules", ".jen", "cache");
+  if (!existsSync(cacheDir)) {
+    mkdirSync(cacheDir, { recursive: true });
+  }
+  // Flatten path to avoid directory structure issues.
+  const flatName = filePath.replace(/[\\/:]/g, "_").replace(/^_+/, "");
+  return join(cacheDir, flatName + ".mjs");
+}
+/**
+ * Renders a route module to a complete HTML document.
+ * This function handles the entire server-side rendering pipeline:
+ * 1. Compiles TypeScript/JSX/Vue/Svelte to JavaScript if needed
+ * 2. Imports the compiled route module
+ * 3. Executes route-level middleware
+ * 4. Calls the loader to fetch data
+ * 5. Renders the component to HTML using Preact
+ * 6. Wraps the component HTML in a full document with hydration metadata if enabled
+ *
+ * Compilation is performed at request-time in development (for fast iteration) and at build-time in production.
+ * The route module must export a default Preact component and may optionally export a loader function,
+ * middleware, a Head component, and hydration strategy metadata.
+ *
+ * @param opts Configuration and context for rendering.
+ * @param opts.config The framework configuration.
+ * @param opts.route The route entry being rendered.
+ * @param opts.req The Node.js IncomingMessage (optional for SSG).
+ * @param opts.res The Node.js ServerResponse (optional for SSG).
+ * @param opts.url The parsed request URL.
+ * @param opts.params Dynamic route parameters extracted from the URL.
+ * @param opts.query Query string parameters.
+ * @param opts.headers HTTP request headers.
+ * @param opts.cookies Parsed cookies from the request.
+ * @returns The complete HTML document as a string.
+ * @throws Error if the route module fails to compile, import, or render.
+ */
+export async function renderRouteToHtml(opts) {
+  const { config, route, url, params, query, headers, cookies } = opts;
+  // Transpile route file if needed. TypeScript and JSX require compilation to JavaScript.
+  // Vue and Svelte components also need transpilation to Preact-compatible JavaScript.
+  let moduleUrl = route.filePath;
+  const ext = route.filePath.slice(-4).toLowerCase();
+  const requiresTranspile = [".tsx", ".ts", ".vue", ".svelte"].some((e) =>
+    route.filePath.toLowerCase().endsWith(e),
+  );
+  if (requiresTranspile) {
+    const outfile = getCachePath(route.filePath);
+    await esbuild.build({
+      entryPoints: [route.filePath],
+      outfile,
+      format: "esm",
+      platform: "node", // Node platform for SSR supports built-ins like fs, path, etc.
+      target: "es2022",
+      bundle: true, // Bundle all local imports into a single file for simplicity.
+      external: ["preact", "preact-render-to-string", "jenjs"], // Keep framework imports external.
+      write: true,
+      plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
+    });
+    moduleUrl = outfile;
+  }
+  // Cache busting via query parameter ensures fresh module evaluation even if file is unchanged.
+  // This is critical because esbuild may use cached builds and we need the latest code for SSR.
+  let mod;
+  try {
+    mod = await import(pathToFileURL(moduleUrl).href + "?t=" + Date.now());
+  } catch (err) {
+    throw new Error(
+      `Failed to import route module ${route.filePath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  // Execute route middleware if present. Middleware runs only in server context (not during SSG with empty req/res).
+  // Middleware can access the request, manipulate context data, or short-circuit rendering by throwing redirect/json signals.
+  let middlewareData = {};
+  if (opts.req && opts.res) {
+    const middlewareCtx = createRouteMiddlewareContext({
+      req: opts.req,
+      res: opts.res,
+      url,
+      params,
+      query,
+      headers,
+      cookies,
+    });
+    const middlewares = [];
+    if (mod.middleware) {
+      if (Array.isArray(mod.middleware)) {
+        middlewares.push(...mod.middleware);
+      } else {
+        middlewares.push(mod.middleware);
+      }
+    }
+    try {
+      await executeRouteMiddleware(middlewares, middlewareCtx);
+      middlewareData = middlewareCtx.data || {};
+    } catch (err) {
+      // Middleware may throw special error messages to signal redirect or JSON responses.
+      // These are handled by the caller and should not be caught here.
+      if (err.message === "__REDIRECT__" || err.message === "__JSON__") {
+        throw err;
+      }
+      throw err;
+    }
+  }
+  // Build the loader context with request data and middleware results.
+  // The loader receives both raw request data and enriched data from middleware.
+  const loaderCtx = {
+    url,
+    params,
+    query,
+    headers,
+    cookies,
+    data: middlewareData, // Pass middleware data to loader.
+  };
+  // Call the optional loader function to fetch/prepare data for the page.
+  // Loader results are passed as props to the page component.
+  let data = null;
+  if (typeof mod.loader === "function") {
+    data = await mod.loader(loaderCtx);
+  }
+  if (!mod.default) {
+    throw new Error(
+      `Route module ${route.filePath} does not export a default component`,
+    );
+  }
+  const Page = mod.default;
+  // Check if hydration is disabled. Set to false for purely static pages with no client-side interactivity.
+  const shouldHydrate = mod.hydrate !== false;
+  const app = h(Page, { data, params, query });
+  // Render the page component to a static HTML string.
+  // Preact rendering at this stage is purely static; hydration happens on the client.
+  let bodyHtml = renderToString(app);
+  // Check for island components that need selective hydration on the client.
+  // Islands are opt-in interactive components within otherwise static pages.
+  // Each island is marked with __island and __hydrationStrategy metadata and will be hydrated by the client.
+  for (const [key, value] of Object.entries(mod)) {
+    if (
+      typeof value === "function" &&
+      value.__island &&
+      value.__hydrationStrategy
+    ) {
+      const strategy = value.__hydrationStrategy;
+      const componentPath = route.filePath;
+      const islandId = `island-${Math.random().toString(36).slice(2, 9)}`;
+      const marker = createIslandMarker(islandId, componentPath, strategy, {});
+      // Inject marker before closing app div.
+      bodyHtml = bodyHtml.replace("</div>", `${marker}</div>`);
+    }
+  }
+  // Collect all head elements from configuration and the route's Head component.
+  // Head components allow per-route customization of meta tags, title, links, etc.
+  const headParts = [];
+  headParts.push(...config.inject.head);
+  if (mod.Head) {
+    try {
+      const headNode = h(mod.Head, { data, params, query });
+      const headHtml = renderToString(headNode);
+      headParts.push(headHtml);
+    } catch (err) {
+      console.error(
+        `Failed to render Head component for ${route.filePath}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+  // Global stylesheet link is always injected. This file is compiled from SCSS in development and build time.
+  headParts.push(`<link rel="stylesheet" href="/styles.css">`);
+  // Build the complete HTML document with semantic structure.
+  // The div#app is the mount point for hydration on the client.
+  let html = `<!doctype html>
+<html>
+<head>
+${headParts.join("\n")}
+</head>
+<body>
+<div id="app">${bodyHtml}</div>`;
+  // Only inject hydration script if enabled for this route.
+  // Hydration-disabled routes are purely static and require no JavaScript.
+  if (shouldHydrate) {
+    // Serialize loader and route data for the client. Must escape </script to prevent injection attacks.
+    // The client uses this data to reconstruct the component tree and populate props.
+    const frameworkDataStr = JSON.stringify(
+      { data, params, query },
+      null,
+      2,
+    ).replace(/<\/script/gi, "<\\/script");
+    const hydrateFile = `/__hydrate?file=${encodeURIComponent(route.filePath)}`;
+    html += `
+  <script id="__FRAMEWORK_DATA__" type="application/json">
+  ${frameworkDataStr}
+  </script>
+  <script type="module">
+  import { hydrateClient } from "/__runtime/hydrate.js";
+  import { initializeIslands } from "/__runtime/island-hydration-client.js";
+  hydrateClient(${JSON.stringify(hydrateFile)});
+  initializeIslands();
+  </script>`;
+  }
+  // Inject any additional scripts or markup configured to run at the end of body.
+  // Useful for analytics, telemetry, or polyfills that should load after DOM is ready.
+  html += `
+${config.inject.bodyEnd.join("\n")}
+</body>
+</html>`;
+  return html;
+}

package/templates/ssr-isr/lib/server/api-routes.d.ts

@@ -0,0 +1,112 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * API route handler execution context.
+ * Contains request data and response objects passed to all API handler functions.
+ */
+export interface ApiRouteContext {
+  /** Node.js IncomingMessage with raw request properties. */
+  req: IncomingMessage;
+  /** Node.js ServerResponse for writing response. */
+  res: ServerResponse;
+  /** Request URL object with pathname, search, query parameters. */
+  url: URL;
+  /** HTTP method in uppercase (GET, POST, PUT, DELETE, PATCH, etc.). */
+  method: string;
+  /** Query string parameters parsed from URL (?key=value). */
+  query: Record<string, string>;
+  /** Parsed request body (JSON if Content-Type is application/json, else raw string). */
+  body: any;
+  /** Route path parameters extracted from dynamic segments (e.g., [id], [slug]). */
+  params: Record<string, string>;
+}
+/**
+ * API handler function executed for a specific HTTP method.
+ * Receives context with request data and response object.
+ *
+ * Return value is automatically serialized:
+ * - Response: Sent as-is with status and headers
+ * - string: Sent as text/plain; charset=utf-8
+ * - object: Sent as application/json (JSON.stringify'd)
+ * - null: Sent as JSON null
+ *
+ * Handler can also manually set response (res.write/res.end) and return null;
+ * the framework will not double-send if res.writableEnded is true.
+ *
+ * @param ctx - Execution context with request and response objects
+ * @returns Result value or promise resolving to result
+ */
+export type ApiHandler = (
+  ctx: ApiRouteContext,
+) =>
+  | Promise<Response | string | Record<string, any> | null>
+  | Response
+  | string
+  | Record<string, any>
+  | null;
+/**
+ * API route module interface.
+ * Exported from api/*.ts files as named exports for each HTTP method.
+ *
+ * Example api/users/[id].ts:
+ *   export const GET = async (ctx) => {
+ *     return { userId: ctx.params.id, ...userData };
+ *   };
+ *   export const DELETE = async (ctx) => {
+ *     deleteUser(ctx.params.id);
+ *     return { status: "deleted" };
+ *   };
+ *
+ * Supported methods:
+ * - GET: Retrieve data
+ * - POST: Create new resource
+ * - PUT: Replace resource
+ * - DELETE: Remove resource
+ * - PATCH: Partial update
+ * - HEAD: Like GET but no body
+ * - OPTIONS: Describe available methods
+ */
+export interface ApiRouteModule {
+  GET?: ApiHandler;
+  POST?: ApiHandler;
+  PUT?: ApiHandler;
+  DELETE?: ApiHandler;
+  PATCH?: ApiHandler;
+  HEAD?: ApiHandler;
+  OPTIONS?: ApiHandler;
+}
+/**
+ * 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 declare function tryHandleApiRoute(opts: {
+  req: IncomingMessage;
+  res: ServerResponse;
+  siteDir: string;
+}): Promise<boolean>;