create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/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/ssr-isr/lib/server/ssr.js

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

package/templates/ssr-isr/lib/shared/log.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Structured logging utility for the Jen.js framework.
+ * Provides three log levels (info, warn, error) that output to appropriate streams.
+ *
+ * Usage:
+ * - log.info(): Development and progress messages
+ * - log.warn(): Warnings and non-fatal issues
+ * - log.error(): Critical errors that may require attention
+ *
+ * Format:
+ * All logs include an ISO 8601 timestamp and a level prefix.
+ * Example: "[2026-02-19T15:30:45.123Z] [INFO] Building 42 routes"
+ *
+ * Output:
+ * - info() -> console.log (stdout)
+ * - warn() -> console.warn (stderr)
+ * - error() -> console.error (stderr)
+ *
+ * This is used throughout the framework for build output, server status, and diagnostics.
+ */
+export declare const log: {
+  /**
+   * Logs an informational message with timestamp and [INFO] prefix.
+   * Used for progress updates, build completion, server startup, etc.
+   *
+   * @param msg Message to log
+   *
+   * @example log.info("Server running on port 3000");
+   */
+  info(msg: string): void;
+  /**
+   * Logs a warning message with timestamp and [WARN] prefix.
+   * Used for non-fatal issues, deprecated usage, or recoverable problems.
+   *
+   * @param msg Warning message to log
+   *
+   * @example log.warn("Configuration file not found, using defaults");
+   */
+  warn(msg: string): void;
+  /**
+   * Logs an error message with timestamp and [ERROR] prefix.
+   * Used for critical failures that require immediate attention.
+   *
+   * @param msg Error message to log
+   *
+   * @example log.error("Failed to compile SCSS: syntax error on line 42");
+   */
+  error(msg: string): void;
+};

package/templates/ssr-isr/lib/shared/log.js

@@ -0,0 +1,64 @@
+/**
+ * Get current timestamp in ISO 8601 format.
+ * Used to prefix all log messages with precise UTC time information for debugging and monitoring.
+ *
+ * @returns ISO 8601 timestamp string (e.g., "2026-02-19T15:30:45.123Z")
+ */
+function ts() {
+  return new Date().toISOString();
+}
+/**
+ * Structured logging utility for the Jen.js framework.
+ * Provides three log levels (info, warn, error) that output to appropriate streams.
+ *
+ * Usage:
+ * - log.info(): Development and progress messages
+ * - log.warn(): Warnings and non-fatal issues
+ * - log.error(): Critical errors that may require attention
+ *
+ * Format:
+ * All logs include an ISO 8601 timestamp and a level prefix.
+ * Example: "[2026-02-19T15:30:45.123Z] [INFO] Building 42 routes"
+ *
+ * Output:
+ * - info() -> console.log (stdout)
+ * - warn() -> console.warn (stderr)
+ * - error() -> console.error (stderr)
+ *
+ * This is used throughout the framework for build output, server status, and diagnostics.
+ */
+export const log = {
+  /**
+   * Logs an informational message with timestamp and [INFO] prefix.
+   * Used for progress updates, build completion, server startup, etc.
+   *
+   * @param msg Message to log
+   *
+   * @example log.info("Server running on port 3000");
+   */
+  info(msg) {
+    console.log(`[${ts()}] [INFO] ${msg}`);
+  },
+  /**
+   * Logs a warning message with timestamp and [WARN] prefix.
+   * Used for non-fatal issues, deprecated usage, or recoverable problems.
+   *
+   * @param msg Warning message to log
+   *
+   * @example log.warn("Configuration file not found, using defaults");
+   */
+  warn(msg) {
+    console.warn(`[${ts()}] [WARN] ${msg}`);
+  },
+  /**
+   * Logs an error message with timestamp and [ERROR] prefix.
+   * Used for critical failures that require immediate attention.
+   *
+   * @param msg Error message to log
+   *
+   * @example log.error("Failed to compile SCSS: syntax error on line 42");
+   */
+  error(msg) {
+    console.error(`[${ts()}] [ERROR] ${msg}`);
+  },
+};

package/templates/ssr-isr/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "jen-app",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node server.js dev",
+    "build": "node build.js"
+  },
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.28",
+    "esbuild": "^0.25.0",
+    "glob": "^13.0.5",
+    "preact": "^10.25.4",
+    "preact-render-to-string": "^6.5.13",
+    "sass": "^1.97.3",
+    "sirv": "^3.0.1",
+    "svelte": "^5.51.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}

package/templates/ssr-isr/server.js

@@ -0,0 +1,128 @@
+import { createServer } from "node:http";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import esbuild from "esbuild";
+
+const colors = {
+  reset: "\x1b[0m",
+  dim: "\x1b[2m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+};
+
+const ts = () => new Date().toISOString().replace("T", " ").slice(0, 19);
+
+const __filename = fileURLToPath(import.meta.url);
+const currentDir = dirname(__filename);
+const rootDir = join(currentDir, ".");
+
+const mode = process.argv[2] ?? "dev";
+const isDev = mode === "dev";
+
+// Embedded Minifier Logic
+const Minifier = {
+  html(input) {
+    return input
+      .replace(/<!--[\s\S]*?-->/g, "")
+      .replace(/>\s+</g, "><")
+      .replace(/\s+/g, " ")
+      .replace(/\s*([{};:,=])\s*/g, "$1")
+      .trim();
+  },
+  css(input) {
+    return input
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/.*/g, "")
+      .replace(/\s*([{}:;,])\s*/g, "$1")
+      .replace(/\s+/g, " ")
+      .replace(/;\s*}/g, "}")
+      .trim();
+  },
+};
+
+async function main() {
+  console.log(
+    `${colors.dim}[${ts()}]${colors.reset} ${colors.cyan}[INFO]${colors.reset} Starting SSR+ISR server in ${isDev ? "DEV" : "PROD"} mode...`,
+  );
+
+  const configPath = join(currentDir, "jen.config.ts");
+  const outdir = join(currentDir, ".esbuild");
+
+  await esbuild.build({
+    entryPoints: [configPath],
+    outdir,
+    format: "esm",
+    platform: "node",
+    target: "es2022",
+    minify: true,
+    jsx: "automatic",
+    jsxImportSource: "preact",
+    bundle: true,
+    loader: { ".ts": "ts" },
+    logLevel: "silent",
+  });
+
+  const configFile = join(outdir, "jen.config.js");
+  const config = (await import(pathToFileURL(configFile).href)).default;
+
+  const appPath = pathToFileURL(join(rootDir, "lib/server/app.js")).href;
+  const { createApp } = await import(appPath);
+
+  // Load banner
+  const bannerPath = pathToFileURL(join(rootDir, "lib/cli/banner.js")).href;
+  const { printBanner } = await import(bannerPath);
+
+  const app = await createApp({
+    config,
+    mode: isDev ? "dev" : "prod",
+  });
+
+  const server = createServer(async (req, res) => {
+    // Intercept response to minify
+    const originalEnd = res.end;
+    res.end = function (chunk, encoding, callback) {
+      if (chunk) {
+        const type = res.getHeader("content-type");
+        if (typeof type === "string") {
+          if (type.includes("text/html")) {
+            try {
+              chunk = Minifier.html(chunk.toString());
+              res.removeHeader("content-length");
+            } catch (e) {
+              console.error(
+                `${colors.dim}[${ts()}]${colors.reset} ${colors.red}[ERROR]${colors.reset} HTML Minification failed:`,
+                e,
+              );
+            }
+          } else if (type.includes("text/css")) {
+            try {
+              chunk = Minifier.css(chunk.toString());
+              res.removeHeader("content-length");
+            } catch (e) {
+              console.error(
+                `${colors.dim}[${ts()}]${colors.reset} ${colors.red}[ERROR]${colors.reset} CSS Minification failed:`,
+                e,
+              );
+            }
+          }
+        }
+      }
+      return originalEnd.call(this, chunk, encoding, callback);
+    };
+
+    try {
+      await app.handle(req, res);
+    } catch (err) {
+      res.statusCode = 500;
+      res.setHeader("content-type", "text/plain; charset=utf-8");
+      res.end("Internal Server Error\n\n" + (err?.stack ?? String(err)));
+    }
+  });
+
+  server.listen(config.server.port, config.server.hostname, () => {
+    const actualPort = server.address().port;
+    printBanner(actualPort, isDev ? "development" : "production");
+  });
+}
+
+main().catch(console.error);

package/templates/ssr-isr/site/pages/(index).tsx

@@ -0,0 +1,11 @@
+export default function HomePage() {
+  return (
+    <main>
+      <h1>Welcome to Jen.js (SSR + ISR)</h1>
+      <p>
+        This is a server-rendered page with incremental static regeneration.
+      </p>
+      <p>Current time: {new Date().toLocaleString()}</p>
+    </main>
+  );
+}

package/templates/ssr-isr/site/styles/global.scss

@@ -0,0 +1,37 @@
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html {
+  font-family:
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue",
+    Arial, sans-serif;
+  line-height: 1.5;
+  color: #333;
+}
+
+body {
+  background-color: #f5f5f5;
+}
+
+main {
+  max-width: 1200px;
+  margin: 0 auto;
+  padding: 2rem;
+  background: white;
+  border-radius: 8px;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+h1 {
+  font-size: 2.5rem;
+  margin-bottom: 1rem;
+  color: #0066cc;
+}
+
+p {
+  margin-bottom: 1rem;
+  font-size: 1.1rem;
+}