create-jen-app 1.2.3 → 1.2.4

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.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;
+}

package/templates/ssr-isr/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+
+    "strict": true,
+    "skipLibCheck": true,
+
+    "baseUrl": ".",
+    "paths": {
+      "@src/*": ["lib/*"]
+    },
+
+    "types": ["node"],
+
+    "outDir": "dist",
+    "rootDir": ".",
+
+    "allowJs": false,
+    "resolveJsonModule": true,
+
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "site/**/*.ts",
+    "site/**/*.tsx",
+    "server.ts",
+    "build.ts",
+    "jen.config.ts"
+  ],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/static/build.js

@@ -1,21 +1,3 @@
-/*
- * 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 { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { readdir, stat, readFile, writeFile } from "node:fs/promises";
@@ -25,6 +7,30 @@ const __filename = fileURLToPath(import.meta.url);
 const currentDir = dirname(__filename);
 const rootDir = join(currentDir, ".");
 
+async function analyze() {
+  console.log("[ANALYZE] Loading bundle analyzer...");
+  const analyzerPath = pathToFileURL(
+    join(rootDir, "lib/build/bundle-analyzer.js"),
+  ).href;
+  const { runBundleAnalyzer } = await import(analyzerPath);
+  const configPath = join(currentDir, "jen.config.ts");
+  const outdir = join(currentDir, ".esbuild");
+  await esbuild.build({
+    entryPoints: [configPath],
+    outdir,
+    format: "esm",
+    platform: "node",
+    target: "es2022",
+    bundle: true,
+    loader: { ".ts": "ts" },
+    logLevel: "silent",
+  });
+  const configFile = join(outdir, "jen.config.js");
+  const config = (await import(pathToFileURL(configFile).href)).default;
+  await runBundleAnalyzer(config);
+  console.log("[ANALYZE] Bundle analysis complete!");
+}
+
 // Embedded Minifier Logic
 const Minifier = {
   html(input) {
@@ -47,6 +53,12 @@ const Minifier = {
 };
 
 async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("analyze")) {
+    await analyze();
+    return;
+  }
+
   console.log("[BUILD] Starting build...");
 
   const configPath = join(currentDir, "jen.config.ts");

package/templates/static/jen.config.ts

@@ -1,21 +1,3 @@
-/*
- * 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/>.
- */
-
 const config: FrameworkConfig = {
   siteDir: "site",
   distDir: "dist",

package/templates/static/jenjs.d.ts

@@ -1,21 +1,3 @@
-/*
- * 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/>.
- */
-
 declare module "@jenjs/master" {
   export * from "@jenjs/master";
 }

package/templates/static/lib/api/(hello).js

@@ -1,20 +1,3 @@
-/*
- * 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/>.
- */
 export default async function handler(ctx) {
   return {
     ok: true,

package/templates/static/lib/api/examples/files/[...slug].js

@@ -0,0 +1,22 @@
+/**
+ * Example Catch-All API Route: GET /api/files/[...slug]
+ *
+ * Example showing catch-all dynamic routes for file paths
+ * Matches: /api/files/a, /api/files/a/b, /api/files/a/b/c, etc.
+ */
+export default async function handler(req, res) {
+  const { slug } = req.params;
+  // slug will be an array of path segments
+  // /api/files/docs/readme.md -> slug = ['docs', 'readme.md']
+  // /api/files/a/b/c -> slug = ['a', 'b', 'c']
+  const filePath = Array.isArray(slug) ? slug.join("/") : slug;
+  if (req.method === "GET") {
+    res.status(200).json({
+      message: "File resource",
+      path: filePath,
+      segments: slug,
+    });
+  } else {
+    res.status(405).json({ error: "Method not allowed" });
+  }
+}

package/templates/static/lib/api/examples/hello.js

@@ -0,0 +1,11 @@
+/**
+ * Example API Route: GET /api/hello
+ *
+ * Basic example showing JSON response
+ */
+export default function handler(req, res) {
+  res.status(200).json({
+    message: "Hello from Jen.js API!",
+    timestamp: new Date().toISOString(),
+  });
+}