create-jen-app 1.2.2 → 1.2.4

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

@@ -0,0 +1,438 @@
+import { existsSync, watch } from "node:fs";
+import { join, extname } from "node:path";
+import sirv from "sirv";
+import { createScssCompiler } from "../css/compiler.js";
+import { scanRoutes } from "../core/routes/scan.js";
+import { matchRoute } from "../core/routes/match.js";
+import { log } from "../shared/log.js";
+import { Kernel } from "../middleware/kernel.js";
+import { renderRouteToHtml } from "../runtime/render.js";
+import { HMR_CLIENT_SCRIPT } from "../runtime/hmr.js";
+import { headersToObject, parseCookies } from "../core/http.js";
+import { tryHandleApiRoute } from "./api-routes.js";
+import { resolve } from "node:path";
+import {
+  buildHydrationModule,
+  runtimeHydrateModule,
+  invalidateCache,
+} from "./runtimeServe.js";
+import {
+  invalidateVueCache,
+  invalidateSvelteCache,
+} from "../compilers/esbuild-plugins.js";
+/**
+ * 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 async function createApp(opts) {
+  const { config, mode, viteServer } = opts;
+  /**
+   * Set of active Server-Sent Events (SSE) connections for Hot Module Replacement.
+   * Clients maintain a persistent SSE connection to receive change notifications.
+   * Each response object in this set receives change events for CSS updates and full reloads.
+   */
+  const hmrClients = new Set();
+  if (mode === "dev") {
+    const sitePath = join(process.cwd(), config.siteDir);
+    log.info(`[HMR] Watching ${sitePath} for changes...`);
+    /**
+     * Debounce timer prevents multiple rapid change notifications.
+     * Filesystem watchers often emit multiple events for a single file change.
+     * This delay coalesces rapid changes into a single notification (100ms threshold).
+     */
+    let debounceTimer;
+    try {
+      watch(sitePath, { recursive: true }, (eventType, filename) => {
+        if (!filename) return;
+        /**
+         * Filter out files that should not trigger HMR notifications.
+         * Temporary files, build artifacts, and hidden files cause infinite loops
+         * or are not meant for hot reload.
+         */
+        if (
+          filename.startsWith(".") ||
+          filename.includes("node_modules") ||
+          filename.endsWith("~") ||
+          filename.endsWith(".tmp") ||
+          filename.endsWith(".esbuild.mjs") || // Ignore build artifacts
+          filename.includes("\\.") || // Windows hidden files
+          filename.includes("/.") // Unix hidden files
+        ) {
+          return;
+        }
+        // Debounce to avoid double events
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          const ext = extname(filename);
+          // Normalize path
+          const fullPath = join(sitePath, filename);
+          log.info(`[HMR] Change detected: ${filename}`);
+          if (ext === ".css" || ext === ".scss") {
+            /**
+             * For CSS/SCSS changes, send a style-update event.
+             * This allows the client to reload CSS without full page reload,
+             * preserving component state and providing better developer experience.
+             */
+            const cssName = filename.replace(/\.scss$/, ".css");
+            for (const client of hmrClients) {
+              client.write(
+                `event: style-update\ndata: ${JSON.stringify({ file: cssName })}\n\n`,
+              );
+            }
+          } else {
+            /**
+             * For JavaScript/TypeScript/component changes, invalidate build caches
+             * and send a full reload event.
+             * Cache invalidation ensures the latest code is loaded on next request.
+             */
+            invalidateCache(fullPath);
+            if (ext === ".vue") invalidateVueCache(fullPath);
+            if (ext === ".svelte") invalidateSvelteCache(fullPath);
+            // Full reload for JS/TS/Vue/Svelte/Other
+            for (const client of hmrClients) {
+              client.write(`event: reload\ndata: {}\n\n`);
+            }
+          }
+        }, 100);
+      });
+    } catch (err) {
+      log.warn(`[HMR] Watch failed: ${err}`);
+    }
+  }
+  /**
+   * Scans the site directory for route files and compiles route patterns.
+   * Routes are discovered by filename pattern and file extensions configured in config.
+   * See scanRoutes() for details on route naming conventions.
+   */
+  const routes = scanRoutes(config);
+  log.info(`Routes discovered: ${routes.length}`);
+  for (const r of routes) log.info(`  ${r.urlPath} -> ${r.filePath}`);
+  const serveAssets = sirv(join(process.cwd(), config.siteDir), {
+    dev: mode === "dev",
+    etag: true,
+  });
+  const serveDist = sirv(join(process.cwd(), config.distDir), {
+    dev: mode === "dev",
+    etag: true,
+  });
+  const middlewares = [
+    async (ctx, next) => {
+      log.info(`${ctx.req.method} ${ctx.url.pathname}`);
+      await next();
+    },
+    async (ctx, next) => {
+      // runtime internal modules
+      if (ctx.url.pathname === "/__runtime/hydrate.js") {
+        ctx.res.statusCode = 200;
+        ctx.res.setHeader(
+          "content-type",
+          "application/javascript; charset=utf-8",
+        );
+        ctx.res.end(runtimeHydrateModule());
+        return;
+      }
+      if (ctx.url.pathname === "/__runtime/island-hydration-client.js") {
+        ctx.res.statusCode = 200;
+        ctx.res.setHeader(
+          "content-type",
+          "application/javascript; charset=utf-8",
+        );
+        const islandCode = `
+import { hydrate } from "https://esm.sh/preact@10";
+import { h } from "https://esm.sh/preact@10";
+
+function extractIslands() {
+  const islands = [];
+  const html = document.documentElement.outerHTML;
+  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 component = match[3];
+    const propsStr = match[4].replace(/\\\\u003c/g, "<");
+    try {
+      islands.push({
+        id, component, strategy,
+        props: JSON.parse(propsStr),
+      });
+    } catch (e) {
+      console.warn('Failed to parse island ' + id);
+    }
+  }
+  return islands;
+}
+
+async function hydrateIsland(island) {
+  const target = document.getElementById(island.id);
+  if (!target) {
+    console.warn('Island target #' + island.id + ' not found');
+    return;
+  }
+  try {
+    const hydrationUrl = '/__hydrate?file=' + encodeURIComponent(island.component);
+    const mod = await import(hydrationUrl);
+    const Component = mod.default;
+    if (!Component) {
+      console.warn('Component not exported from ' + island.component);
+      return;
+    }
+    const app = h(Component, island.props);
+    hydrate(app, target);
+  } catch (err) {
+    console.error('Failed to hydrate island ' + island.id + ':', err);
+  }
+}
+
+function hydrateWithStrategy(islands) {
+  for (const island of islands) {
+    switch (island.strategy) {
+      case 'load':
+        hydrateIsland(island);
+        break;
+      case 'idle':
+        if ('requestIdleCallback' in window) {
+          requestIdleCallback(() => hydrateIsland(island));
+        } else {
+          setTimeout(() => hydrateIsland(island), 2000);
+        }
+        break;
+      case 'visible':
+        if ('IntersectionObserver' in window) {
+          const target = document.getElementById(island.id);
+          if (target) {
+            const observer = new IntersectionObserver((entries) => {
+              if (entries[0].isIntersecting) {
+                hydrateIsland(island);
+                observer.disconnect();
+              }
+            }, { threshold: 0.1 });
+            observer.observe(target);
+          }
+        } else {
+          setTimeout(() => hydrateIsland(island), 3000);
+        }
+        break;
+    }
+  }
+}
+
+export function initializeIslands() {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => {
+      const islands = extractIslands();
+      hydrateWithStrategy(islands);
+    });
+  } else {
+    const islands = extractIslands();
+    hydrateWithStrategy(islands);
+  }
+}
+
+initializeIslands();
+`;
+        ctx.res.end(islandCode);
+        return;
+      }
+      // HMR Endpoint (SSE)
+      if (ctx.url.pathname === "/__hmr" && mode === "dev") {
+        ctx.res.statusCode = 200;
+        ctx.res.setHeader("content-type", "text/event-stream");
+        ctx.res.setHeader("cache-control", "no-cache");
+        ctx.res.setHeader("connection", "keep-alive");
+        ctx.res.write("data: connected\n\n");
+        hmrClients.add(ctx.res);
+        ctx.req.on("close", () => {
+          hmrClients.delete(ctx.res);
+        });
+        return;
+      }
+      if (ctx.url.pathname === "/__hydrate") {
+        const file = ctx.url.searchParams.get("file");
+        if (!file) {
+          ctx.res.statusCode = 400;
+          ctx.res.end("missing file");
+          return;
+        }
+        const js = buildHydrationModule(file);
+        ctx.res.statusCode = 200;
+        ctx.res.setHeader(
+          "content-type",
+          "application/javascript; charset=utf-8",
+        );
+        ctx.res.setHeader("cache-control", "no-store");
+        ctx.res.end(js);
+        return;
+      }
+      await next();
+    },
+    async (ctx, next) => {
+      // API routes
+      const handled = await tryHandleApiRoute({
+        req: ctx.req,
+        res: ctx.res,
+        siteDir: config.siteDir,
+      });
+      if (handled) return;
+      await next();
+    },
+    async (ctx, next) => {
+      // dist
+      if (mode === "prod") {
+        await new Promise((resolve) => {
+          serveDist(ctx.req, ctx.res, () => resolve());
+        });
+        if (ctx.res.writableEnded || ctx.res.headersSent) return;
+      }
+      await next();
+    },
+    async (ctx, next) => {
+      // SCSS Compilation (Dev)
+      if (mode === "dev" && ctx.url.pathname.endsWith(".css")) {
+        let scssFile = null;
+        const basePath = resolve(process.cwd());
+        if (ctx.url.pathname === "/styles.css") {
+          // Global SCSS
+          if (config.css?.globalScss) {
+            // Already includes siteDir if needed, but add it if it doesn't
+            const scssPath = config.css.globalScss.startsWith(config.siteDir)
+              ? config.css.globalScss
+              : join(config.siteDir, config.css.globalScss);
+            scssFile = join(basePath, scssPath);
+            console.log(
+              "[DEBUG CSS] Looking for global SCSS:",
+              scssFile,
+              "exists:",
+              existsSync(scssFile),
+            );
+          } else {
+            console.log("[DEBUG CSS] No config.css.globalScss found");
+          }
+        } else {
+          // Map /foo.css -> siteDir/foo.scss
+          const rel = ctx.url.pathname.slice(1);
+          const tryPath = join(
+            basePath,
+            config.siteDir,
+            rel.replace(/\.css$/, ".scss"),
+          );
+          if (existsSync(tryPath)) {
+            scssFile = tryPath;
+          }
+        }
+        if (scssFile && existsSync(scssFile)) {
+          const compiler = createScssCompiler();
+          const result = compiler.compile({
+            inputPath: scssFile,
+            minified: false,
+            sourceMap: true,
+          });
+          if (result.error) {
+            ctx.res.statusCode = 500;
+            ctx.res.setHeader("content-type", "text/css");
+            ctx.res.end(
+              `/* SCSS Error: ${result.error.replace(/\*\//g, "* /")} */ body::before { position:fixed; top:0; left:0; width:100%; content: "SCSS Error: ${result.error
+                .replace(/\\/g, "\\\\")
+                .replace(
+                  /"/g,
+                  '\\"',
+                )}"; display: block; background: red; color: white; padding: 1em; z-index:9999; white-space: pre-wrap; }`,
+            );
+            return;
+          }
+          ctx.res.statusCode = 200;
+          ctx.res.setHeader("content-type", "text/css");
+          ctx.res.end(result.css);
+          return;
+        }
+      }
+      await next();
+    },
+    async (ctx, next) => {
+      // site assets in dev
+      if (mode === "dev") {
+        await new Promise((resolve) => {
+          serveAssets(ctx.req, ctx.res, () => resolve());
+        });
+        if (ctx.res.writableEnded || ctx.res.headersSent) return;
+      }
+      await next();
+    },
+    async (ctx, next) => {
+      // SSR
+      if (ctx.req.method !== "GET") return next();
+      const m = matchRoute(routes, ctx.url.pathname);
+      if (!m) return next();
+      const reqHeaders = headersToObject(ctx.req.headers);
+      const cookies = parseCookies(ctx.req);
+      const query = {};
+      for (const [k, v] of ctx.url.searchParams.entries()) query[k] = v;
+      try {
+        const html = await renderRouteToHtml({
+          config,
+          route: m.route,
+          req: ctx.req,
+          res: ctx.res,
+          url: ctx.url,
+          params: m.params,
+          query,
+          headers: reqHeaders,
+          cookies,
+        });
+        let finalHtml = html;
+        if (mode === "dev") {
+          // Inject HMR client
+          finalHtml = html.replace(
+            "</body>",
+            `<script>${HMR_CLIENT_SCRIPT}</script></body>`,
+          );
+        }
+        ctx.res.statusCode = 200;
+        ctx.res.setHeader("content-type", "text/html; charset=utf-8");
+        ctx.res.end(finalHtml);
+      } catch (err) {
+        // Middleware may have sent a response (redirect/json)
+        if (err.message === "__REDIRECT__" || err.message === "__JSON__") {
+          return; // Response already sent
+        }
+        throw err;
+      }
+    },
+    async (ctx) => {
+      ctx.res.statusCode = 404;
+      ctx.res.setHeader("content-type", "text/plain; charset=utf-8");
+      ctx.res.end("404 Not Found");
+    },
+  ];
+  const kernel = new Kernel();
+  middlewares.forEach((m) => kernel.use(m));
+  return {
+    async handle(req, res) {
+      await kernel.handle(req, res);
+    },
+  };
+}

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

@@ -0,0 +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/ssr-isr/lib/server/runtimeServe.js

@@ -0,0 +1,169 @@
+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");
+}
+/**
+ * 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 `
+import { hydrate } from "https://esm.sh/preact@10.25.4";
+import { h } from "https://esm.sh/preact@10.25.4";
+
+function getFrameworkData() {
+  const el = document.getElementById("__FRAMEWORK_DATA__");
+  if (!el) return null;
+  try { return JSON.parse(el.textContent || "null"); } catch { return null; }
+}
+
+export async function hydrateClient(entryPath) {
+  const data = getFrameworkData();
+  const mod = await import(entryPath);
+  const Page = mod.default;
+  const app = h(Page, {
+    data: data?.data ?? null,
+    params: data?.params ?? {},
+    query: data?.query ?? {}
+  });
+  const root = document.getElementById("app");
+  if (!root) return;
+  hydrate(app, root);
+}
+`;
+}
+/**
+ * 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);
+}
+/**
+ * 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 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;
+}