create-jen-app 1.2.1 → 1.2.3

package/templates/static/lib/server/runtimeServe.d.ts

@@ -1,4 +1,60 @@
+/**
+ * Generate the browser-safe hydration runtime code.
+ * Uses CDN-hosted Preact (esm.sh) for minimal payload and no bundler overhead.
+ * This runtime is injected into the page and provides hydration primitives.
+ *
+ * Note: In production, consider self-hosting the Preact bundle for better performance
+ * and reliability (no external CDN dependency).
+ *
+ * @returns ES module code string for browser hydration runtime
+ */
 export declare function runtimeHydrateModule(): string;
+/**
+ * Clear cached compiled module for a file path.
+ * Called when a source file changes during development to ensure fresh compilation
+ * on next request.
+ *
+ * @param filePath - Absolute file path to invalidate
+ */
 export declare function invalidateCache(filePath: string): void;
+/**
+ * Build a client-side hydration module for a route.
+ * Takes a route file path, extracts the default component export,
+ * transpiles to browser-executable JavaScript with Preact imports resolved.
+ *
+ * How it works:
+ * 1. Create a proxy file that re-exports only the default component
+ *    This allows tree-shaking to remove server-only exports (loader, middleware, etc.)
+ * 2. Use esbuild buildSync to transpile and bundle with Preact
+ * 3. Cache the result with ETag for HTTP conditional requests
+ * 4. Return JS code or fallback to empty component on error
+ *
+ * Transpilation:
+ * - Format: ESM (for client-side import)
+ * - Platform: browser (not Node.js)
+ * - JSX: Automatic via Preact JSX runtime
+ * - Sourcemap: Inline for debugging in browser DevTools
+ * - External: Preact and runtime libs (assumed available in browser)
+ *
+ * Caching:
+ * - Cache is per-file-path; invalidated via invalidateCache() when file changes
+ * - ETag allows HTTP 304 Not Modified responses
+ * - Development mode trusts explicit invalidation (file watcher triggers it)
+ *
+ * Error handling:
+ * - Failed builds return empty Page component (graceful degradation)
+ * - Errors are logged but don't stop request
+ *
+ * @param routeIdOrPath - File path to route component (e.g., "./routes/index.tsx")
+ *   Note: routeId support for future config-based resolution
+ * @returns ES module JavaScript code (browser-executable)
+ */
 export declare function buildHydrationModule(routeIdOrPath: string): string;
+/**
+ * Retrieve the ETag (cache hash) for a compiled hydration module.
+ * Used for HTTP conditional requests (If-None-Match, 304 Not Modified).
+ *
+ * @param filePath - Route file path
+ * @returns ETag hash string or null if not cached
+ */
 export declare function getHydrationEtag(filePath: string): string | null;

package/templates/static/lib/server/runtimeServe.js

@@ -19,13 +19,35 @@ import { buildSync } from "esbuild";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { basename, dirname } from "node:path";
+/**
+ * Cache for compiled hydration modules.
+ * Stores transpiled JS code and computed ETag hash per source file path.
+ * Cache is invalidated when files change (via invalidateCache).
+ */
 const cache = new Map();
+/**
+ * Compute SHA-1 hash (ETag) for a string.
+ * Used for HTTP cache validation and deduplicating compiled output.
+ *
+ * @param s - String to hash
+ * @returns Hex-encoded SHA-1 hash
+ */
 function etagOf(s) {
-    return createHash("sha1").update(s).digest("hex");
+  return createHash("sha1").update(s).digest("hex");
 }
+/**
+ * Generate the browser-safe hydration runtime code.
+ * Uses CDN-hosted Preact (esm.sh) for minimal payload and no bundler overhead.
+ * This runtime is injected into the page and provides hydration primitives.
+ *
+ * Note: In production, consider self-hosting the Preact bundle for better performance
+ * and reliability (no external CDN dependency).
+ *
+ * @returns ES module code string for browser hydration runtime
+ */
 export function runtimeHydrateModule() {
-    // Browser-safe runtime (ESM) using CDN preact (fast + zero bundler)
-    return `
+  // Browser-safe runtime (ESM) using CDN preact (fast + zero bundler)
+  return `
 import { hydrate } from "https://esm.sh/preact@10.25.4";
 import { h } from "https://esm.sh/preact@10.25.4";
 
@@ -50,76 +72,115 @@ export async function hydrateClient(entryPath) {
 }
 `;
 }
+/**
+ * Clear cached compiled module for a file path.
+ * Called when a source file changes during development to ensure fresh compilation
+ * on next request.
+ *
+ * @param filePath - Absolute file path to invalidate
+ */
 export function invalidateCache(filePath) {
-    cache.delete(filePath);
+  cache.delete(filePath);
 }
+/**
+ * Build a client-side hydration module for a route.
+ * Takes a route file path, extracts the default component export,
+ * transpiles to browser-executable JavaScript with Preact imports resolved.
+ *
+ * How it works:
+ * 1. Create a proxy file that re-exports only the default component
+ *    This allows tree-shaking to remove server-only exports (loader, middleware, etc.)
+ * 2. Use esbuild buildSync to transpile and bundle with Preact
+ * 3. Cache the result with ETag for HTTP conditional requests
+ * 4. Return JS code or fallback to empty component on error
+ *
+ * Transpilation:
+ * - Format: ESM (for client-side import)
+ * - Platform: browser (not Node.js)
+ * - JSX: Automatic via Preact JSX runtime
+ * - Sourcemap: Inline for debugging in browser DevTools
+ * - External: Preact and runtime libs (assumed available in browser)
+ *
+ * Caching:
+ * - Cache is per-file-path; invalidated via invalidateCache() when file changes
+ * - ETag allows HTTP 304 Not Modified responses
+ * - Development mode trusts explicit invalidation (file watcher triggers it)
+ *
+ * Error handling:
+ * - Failed builds return empty Page component (graceful degradation)
+ * - Errors are logged but don't stop request
+ *
+ * @param routeIdOrPath - File path to route component (e.g., "./routes/index.tsx")
+ *   Note: routeId support for future config-based resolution
+ * @returns ES module JavaScript code (browser-executable)
+ */
 export function buildHydrationModule(routeIdOrPath) {
-    // routeIdOrPath is now a route ID like "route_index" or "route_blog_slug"
-    // or a fallback filePath for backwards compatibility
-    let filePath = routeIdOrPath;
-    // For now, keep simple direct file path support
-    // In production, we'd resolve routeId -> filePath via config
-    if (!existsSync(filePath)) {
-        return `export default function Page(){ return null }`;
-    }
-    const key = filePath;
-    // Simple dev cache: check if file content changed?
-    // Actually, for dev speed, we trust explicit invalidation or just rebuild on request.
-    // Since buildSync is fast for single files, let's just rebuild if not in cache.
-    // The cache is populated. If invalidation happens, it's removed.
-    if (cache.has(key)) {
-        return cache.get(key).js;
-    }
-    // Use a proxy entry to allow tree-shaking of server-only exports (like loader)
-    const fileName = basename(filePath);
-    const dir = dirname(filePath);
-    const proxyContent = `export { default } from "./${fileName}";`;
-    try {
-        const jsOutput = buildSync({
-            stdin: {
-                contents: proxyContent,
-                resolveDir: dir,
-                sourcefile: "hydration-proxy.tsx",
-                loader: "tsx",
-            },
-            format: "esm",
-            platform: "browser",
-            bundle: true,
-            write: false,
-            sourcemap: "inline",
-            jsx: "automatic",
-            jsxImportSource: "preact",
-            define: {
-                "process.env.NODE_ENV": JSON.stringify("development"),
-            },
-            external: [
-                "preact",
-                "preact/hooks",
-                "preact/jsx-runtime",
-                "preact-render-to-string",
-            ],
-            // Plugins not supported in buildSync, only in build()
-            // plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
-        }).outputFiles?.[0]?.text;
-        if (!jsOutput) {
-            console.error("[HYDRATION] Failed to build module for:", filePath);
-            return `export default function Page(){ return null }`;
-        }
-        const out = `
-import { h } from "https://esm.sh/preact@10.25.4";
-import { Fragment } from "https://esm.sh/preact@10.25.4";
-import { jsx, jsxs } from "https://esm.sh/preact@10.25.4/jsx-runtime";
-` + jsOutput;
-        const etag = etagOf(out);
-        cache.set(key, { js: out, etag });
-        return out;
-    }
-    catch (err) {
-        console.error("[HYDRATION] Build error for", filePath, ":", err);
-        return `export default function Page(){ return null }`;
+  // routeIdOrPath is a file path; future versions may support route IDs via config
+  let filePath = routeIdOrPath;
+  // Return fallback if file doesn't exist
+  if (!existsSync(filePath)) {
+    return `export default function Page(){ return null }`;
+  }
+  const key = filePath;
+  // Return cached result if available (invalidated by invalidateCache)
+  if (cache.has(key)) {
+    return cache.get(key).js;
+  }
+  // Create proxy file to enable tree-shaking of server-only exports (loader, middleware, etc.)
+  // The proxy re-exports only the default component, letting esbuild eliminate other exports
+  const fileName = basename(filePath);
+  const dir = dirname(filePath);
+  const proxyContent = `export { default } from "./${fileName}";`;
+  try {
+    // Transpile proxy with esbuild for browser-safe JavaScript
+    const jsOutput = buildSync({
+      stdin: {
+        contents: proxyContent,
+        resolveDir: dir, // Resolve imports relative to route directory
+        sourcefile: "hydration-proxy.tsx",
+        loader: "tsx", // Support TypeScript and JSX
+      },
+      format: "esm",
+      platform: "browser", // Browser-specific optimizations
+      bundle: true, // Inline dependencies (except external)
+      write: false, // Return code instead of writing file
+      sourcemap: "inline", // Include source map for debugging
+      jsx: "automatic", // Automatic JSX transform (Preact)
+      jsxImportSource: "preact",
+      define: {
+        "process.env.NODE_ENV": JSON.stringify("development"),
+      },
+      // Preact and runtime must be available in browser (loaded separately)
+      external: [
+        "preact",
+        "preact/hooks",
+        "preact/jsx-runtime",
+        "preact-render-to-string",
+      ],
+      // TODO: Add plugin support for Vue/Svelte components
+      // plugins: [vueEsbuildPlugin(), svelteEsbuildPlugin()],
+    }).outputFiles?.[0]?.text;
+    if (!jsOutput) {
+      console.error("[HYDRATION] Failed to build module for:", filePath);
+      return `export default function Page(){ return null }`;
     }
+    // Cache result with ETag
+    const etag = etagOf(jsOutput);
+    cache.set(key, { js: jsOutput, etag });
+    return jsOutput;
+  } catch (err) {
+    console.error("[HYDRATION] Build error for", filePath, ":", err);
+    return `export default function Page(){ return null }`;
+  }
 }
+/**
+ * Retrieve the ETag (cache hash) for a compiled hydration module.
+ * Used for HTTP conditional requests (If-None-Match, 304 Not Modified).
+ *
+ * @param filePath - Route file path
+ * @returns ETag hash string or null if not cached
+ */
 export function getHydrationEtag(filePath) {
-    const v = cache.get(filePath);
-    return v?.etag ?? null;
+  const v = cache.get(filePath);
+  return v?.etag ?? null;
 }

package/templates/static/lib/server/ssr.d.ts

@@ -0,0 +1,161 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FrameworkConfig } from "../core/config.js";
+import type { RouteEntry } from "../core/routes/scan.js";
+/**
+ * Server-side rendering context passed to render() function.
+ * Contains all necessary information to render a page on the server.
+ */
+export interface SSRContext {
+  req: IncomingMessage;
+  res: ServerResponse;
+  url: URL;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+}
+/**
+ * Server-side props context passed to getServerSideProps().
+ * Provides access to request, params, and query string.
+ */
+export interface GetServerSidePropsContext {
+  req: IncomingMessage;
+  res: ServerResponse;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  url: URL;
+}
+/**
+ * Return type from getServerSideProps().
+ * Can return notFound for 404, redirect for redirects, or props for rendering.
+ */
+export type GetServerSidePropsResult<T = any> =
+  | {
+      props: T;
+    }
+  | {
+      notFound: true;
+    }
+  | {
+      redirect: {
+        destination: string;
+        permanent?: boolean;
+      };
+    };
+/**
+ * Cache configuration and TTL management.
+ */
+export interface CacheConfig {
+  enabled: boolean;
+  ttlSeconds: number;
+}
+/**
+ * Configure the SSR HTML cache behavior.
+ *
+ * @param config Cache configuration options
+ */
+export declare function configureSsrCache(config: Partial<CacheConfig>): void;
+/**
+ * Clear the entire SSR render cache.
+ * Useful in development or when data has changed.
+ */
+export declare function clearSsrCache(): void;
+/**
+ * Clear a specific cached page by URL pathname.
+ *
+ * @param pathname URL pathname to invalidate
+ */
+export declare function invalidateSsrCache(pathname: string): void;
+/**
+ * Core SSR render function: converts a component/template to HTML string.
+ * This is the main entry point for server-side rendering in Jen.js.
+ *
+ * Handles:
+ * 1. Cache lookup for performance
+ * 2. Module compilation (TS/JSX/Vue/Svelte → JS)
+ * 3. Route middleware execution
+ * 4. Loader function invocation (getServerSideProps pattern)
+ * 5. Component rendering to HTML string
+ * 6. Head management and hydration script injection
+ * 7. HTML caching for subsequent requests
+ *
+ * @param config Framework configuration
+ * @param route Route entry being rendered
+ * @param ctx Complete SSR context with request/response and metadata
+ * @returns Complete HTML document as a string
+ * @throws Error if rendering fails
+ *
+ * @example
+ * ```typescript
+ * const html = await render(config, route, {
+ *   req, res, url, params, query, headers, cookies
+ * });
+ * res.setHeader("content-type", "text/html; charset=utf-8");
+ * res.end(html);
+ * ```
+ */
+export declare function render(
+  config: FrameworkConfig,
+  route: RouteEntry,
+  ctx: SSRContext,
+): Promise<string>;
+/**
+ * Advanced SSR render with optional caching control.
+ * Allows per-request cache bypass for revalidation.
+ *
+ * @param config Framework configuration
+ * @param route Route entry being rendered
+ * @param ctx Complete SSR context
+ * @param options Render options
+ * @param options.cache Whether to use/update cache (default: true)
+ * @returns Complete HTML document
+ *
+ * @example
+ * ```typescript
+ * const html = await renderWithOptions(config, route, ctx, {
+ *   cache: false // Bypass cache for this request
+ * });
+ * ```
+ */
+export declare function renderWithOptions(
+  config: FrameworkConfig,
+  route: RouteEntry,
+  ctx: SSRContext,
+  options?: {
+    cache?: boolean;
+  },
+): Promise<string>;
+/**
+ * Manual HTML rendering of a component to string (no full document).
+ * Useful when you need just the component HTML without head/body wrapper.
+ *
+ * This is a low-level API primarily for internal use.
+ * For typical routing, use render() instead.
+ *
+ * @param config Framework configuration
+ * @param route Route to render
+ * @param ctx SSR context
+ * @returns Just the component body HTML (no <!doctype>, no <head>, no hydration)
+ */
+export declare function renderComponentToString(
+  config: FrameworkConfig,
+  route: RouteEntry,
+  ctx: SSRContext,
+): Promise<string>;
+/**
+ * Get cache statistics for monitoring and debugging.
+ *
+ * @returns Cache statistics
+ */
+export declare function getSsrCacheStats(): {
+  size: number;
+  enabled: boolean;
+  ttlSeconds: number;
+  entries: {
+    pathname: string;
+    age: number;
+    size: number;
+  }[];
+};

package/templates/static/lib/server/ssr.js

@@ -0,0 +1,219 @@
+/*
+ * This file is part of Jen.js.
+ * Copyright (C) 2026 oopsio
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { renderRouteToHtml } from "../runtime/render.js";
+/**
+ * HTML rendering cache for performance optimization.
+ * Cache key is URL pathname. Useful for frequently accessed pages.
+ * In production, consider using Redis or external cache for distributed rendering.
+ */
+const renderCache = new Map();
+let cacheConfig = {
+  enabled: true,
+  ttlSeconds: 3600, // Default: 1 hour
+};
+/**
+ * Configure the SSR HTML cache behavior.
+ *
+ * @param config Cache configuration options
+ */
+export function configureSsrCache(config) {
+  cacheConfig = { ...cacheConfig, ...config };
+}
+/**
+ * Clear the entire SSR render cache.
+ * Useful in development or when data has changed.
+ */
+export function clearSsrCache() {
+  renderCache.clear();
+}
+/**
+ * Clear a specific cached page by URL pathname.
+ *
+ * @param pathname URL pathname to invalidate
+ */
+export function invalidateSsrCache(pathname) {
+  renderCache.delete(pathname);
+}
+/**
+ * Get cached HTML for a page if it exists and hasn't expired.
+ *
+ * @param pathname URL pathname
+ * @returns Cached HTML string, or null if not cached/expired
+ */
+function getCachedHtml(pathname) {
+  if (!cacheConfig.enabled) return null;
+  const cached = renderCache.get(pathname);
+  if (!cached) return null;
+  const age = (Date.now() - cached.timestamp) / 1000;
+  if (age > cacheConfig.ttlSeconds) {
+    renderCache.delete(pathname);
+    return null;
+  }
+  return cached.html;
+}
+/**
+ * Cache rendered HTML for a page.
+ *
+ * @param pathname URL pathname
+ * @param html Complete HTML string to cache
+ */
+function cacheHtml(pathname, html) {
+  if (!cacheConfig.enabled) return;
+  renderCache.set(pathname, { html, timestamp: Date.now() });
+}
+/**
+ * Core SSR render function: converts a component/template to HTML string.
+ * This is the main entry point for server-side rendering in Jen.js.
+ *
+ * Handles:
+ * 1. Cache lookup for performance
+ * 2. Module compilation (TS/JSX/Vue/Svelte → JS)
+ * 3. Route middleware execution
+ * 4. Loader function invocation (getServerSideProps pattern)
+ * 5. Component rendering to HTML string
+ * 6. Head management and hydration script injection
+ * 7. HTML caching for subsequent requests
+ *
+ * @param config Framework configuration
+ * @param route Route entry being rendered
+ * @param ctx Complete SSR context with request/response and metadata
+ * @returns Complete HTML document as a string
+ * @throws Error if rendering fails
+ *
+ * @example
+ * ```typescript
+ * const html = await render(config, route, {
+ *   req, res, url, params, query, headers, cookies
+ * });
+ * res.setHeader("content-type", "text/html; charset=utf-8");
+ * res.end(html);
+ * ```
+ */
+export async function render(config, route, ctx) {
+  const pathname = ctx.url.pathname;
+  // Check cache first
+  const cached = getCachedHtml(pathname);
+  if (cached) {
+    return cached;
+  }
+  // Render the page
+  const html = await renderRouteToHtml({
+    config,
+    route,
+    req: ctx.req,
+    res: ctx.res,
+    url: ctx.url,
+    params: ctx.params,
+    query: ctx.query,
+    headers: ctx.headers,
+    cookies: ctx.cookies,
+  });
+  // Cache for next request
+  cacheHtml(pathname, html);
+  return html;
+}
+/**
+ * Advanced SSR render with optional caching control.
+ * Allows per-request cache bypass for revalidation.
+ *
+ * @param config Framework configuration
+ * @param route Route entry being rendered
+ * @param ctx Complete SSR context
+ * @param options Render options
+ * @param options.cache Whether to use/update cache (default: true)
+ * @returns Complete HTML document
+ *
+ * @example
+ * ```typescript
+ * const html = await renderWithOptions(config, route, ctx, {
+ *   cache: false // Bypass cache for this request
+ * });
+ * ```
+ */
+export async function renderWithOptions(config, route, ctx, options = {}) {
+  const { cache = true } = options;
+  const pathname = ctx.url.pathname;
+  // Check cache if enabled
+  if (cache) {
+    const cached = getCachedHtml(pathname);
+    if (cached) return cached;
+  }
+  // Render the page
+  const html = await renderRouteToHtml({
+    config,
+    route,
+    req: ctx.req,
+    res: ctx.res,
+    url: ctx.url,
+    params: ctx.params,
+    query: ctx.query,
+    headers: ctx.headers,
+    cookies: ctx.cookies,
+  });
+  // Cache if enabled
+  if (cache) {
+    cacheHtml(pathname, html);
+  }
+  return html;
+}
+/**
+ * Manual HTML rendering of a component to string (no full document).
+ * Useful when you need just the component HTML without head/body wrapper.
+ *
+ * This is a low-level API primarily for internal use.
+ * For typical routing, use render() instead.
+ *
+ * @param config Framework configuration
+ * @param route Route to render
+ * @param ctx SSR context
+ * @returns Just the component body HTML (no <!doctype>, no <head>, no hydration)
+ */
+export async function renderComponentToString(config, route, ctx) {
+  // For now, we render the full HTML and extract the body
+  const html = await renderRouteToHtml({
+    config,
+    route,
+    req: ctx.req,
+    res: ctx.res,
+    url: ctx.url,
+    params: ctx.params,
+    query: ctx.query,
+    headers: ctx.headers,
+    cookies: ctx.cookies,
+  });
+  // Extract body content
+  const bodyMatch = html.match(/<div id="app">([\s\S]*?)<\/div>/);
+  return bodyMatch ? bodyMatch[1] : "";
+}
+/**
+ * Get cache statistics for monitoring and debugging.
+ *
+ * @returns Cache statistics
+ */
+export function getSsrCacheStats() {
+  return {
+    size: renderCache.size,
+    enabled: cacheConfig.enabled,
+    ttlSeconds: cacheConfig.ttlSeconds,
+    entries: Array.from(renderCache.entries()).map(([key, value]) => ({
+      pathname: key,
+      age: (Date.now() - value.timestamp) / 1000,
+      size: value.html.length,
+    })),
+  };
+}