create-jen-app 1.2.2 → 1.2.4

package/templates/ssr-isr/lib/compilers/vue.js

@@ -0,0 +1,90 @@
+import {
+  parse,
+  compileScript,
+  compileTemplate,
+  compileStyle,
+} from "@vue/compiler-sfc";
+import { log } from "../shared/log.js";
+export class VueCompiler {
+  compile(source, options) {
+    try {
+      const filename = options.filename || "component.vue";
+      const id = options.id || filename.replace(/[^a-z0-9]/gi, "_");
+      // Parse SFC
+      const parseResult = parse(source, { filename });
+      const descriptor = parseResult.descriptor;
+      let scriptCode = "";
+      let templateCode = "";
+      let styleCode = "";
+      // Compile script
+      if (descriptor.script || descriptor.scriptSetup) {
+        const scriptCompiled = compileScript(descriptor, {
+          id,
+          isProd: options.minified ?? false,
+        });
+        scriptCode = scriptCompiled.content;
+      }
+      // Compile template
+      if (descriptor.template) {
+        const templateCompiled = compileTemplate({
+          source: descriptor.template.content,
+          filename,
+          id,
+          compilerOptions: {
+            isCustomElement: (tag) => tag.startsWith("custom-"),
+          },
+        });
+        if (templateCompiled.errors.length > 0) {
+          return {
+            code: "",
+            error: `Template compilation error: ${templateCompiled.errors.join(", ")}`,
+          };
+        }
+        templateCode = templateCompiled.code;
+      }
+      // Compile styles (scoped)
+      if (descriptor.styles.length > 0) {
+        descriptor.styles.forEach((style, idx) => {
+          const styleCompiled = compileStyle({
+            source: style.content,
+            filename,
+            id,
+            scoped: style.scoped ?? false,
+          });
+          if (styleCompiled.errors.length > 0) {
+            log.warn(
+              `Style compilation warning at style[${idx}]: ${styleCompiled.errors.join(", ")}`,
+            );
+          }
+          styleCode += styleCompiled.code + "\n";
+        });
+      }
+      // Inject styles at runtime
+      let injectStyle = "";
+      if (styleCode.trim()) {
+        const escapedStyle = styleCode
+          .replace(/"/g, '\\"')
+          .replace(/\n/g, "\\n");
+        injectStyle = `
+const style = document.createElement('style');
+style.textContent = "${escapedStyle}";
+document.head.appendChild(style);
+`;
+      }
+      // Build final module
+      const finalCode = `
+${scriptCode || "export default {}"}
+${templateCode}
+${injectStyle}
+`;
+      return { code: finalCode };
+    } catch (err) {
+      const message = err.message || String(err);
+      log.error(`[Vue] Compilation error: ${message}`);
+      return { code: "", error: message };
+    }
+  }
+}
+export function createVueCompiler() {
+  return new VueCompiler();
+}

package/templates/ssr-isr/lib/core/config.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Rendering mode for routes in the application.
+ *
+ * - "ssr": Server-side rendering - renders on each request, optimal for dynamic content
+ * - "ssg": Static site generation - pre-renders routes at build time, fastest for static content
+ * - "isr": Incremental static regeneration - revalidates static pages on demand
+ * - "ppr": Partial pre-rendering - mixes static and dynamic content
+ */
+export type RenderMode = "ssr" | "ssg" | "isr" | "ppr";
+/**
+ * Complete configuration schema for the Jen.js framework.
+ * This type defines all available configuration options for a Jen.js application.
+ * Applications must provide a jen.config.js or jen.config.ts file exporting a FrameworkConfig object.
+ *
+ * @example
+ * ```typescript
+ * import type { FrameworkConfig } from "jenjs";
+ * export default {
+ *   siteDir: "src",
+ *   distDir: "dist",
+ *   routes: {
+ *     fileExtensions: [".tsx", ".ts", ".jsx", ".js"],
+ *     routeFilePattern: /^\(([^)]+)\)/,
+ *     enableIndexFallback: true
+ *   },
+ *   // ... rest of config
+ * } as FrameworkConfig;
+ * ```
+ */
+export type FrameworkConfig = {
+  /**
+   * Root directory where route files, components, and assets are located.
+   * Relative to project root (CWD). Example: "src", "site", "pages".
+   */
+  siteDir: string;
+  /**
+   * Output directory for build artifacts (compiled HTML, CSS, JavaScript).
+   * Relative to project root. Created automatically if it doesn't exist.
+   */
+  distDir: string;
+  /**
+   * Route discovery and file pattern configuration.
+   */
+  routes: {
+    /**
+     * File extensions to treat as route files.
+     * Examples: [".tsx", ".ts", ".jsx", ".js"]
+     */
+    fileExtensions: string[];
+    /**
+     * RegExp pattern to match route file names and extract route segment.
+     * Example: /^\(([^)]+)\)/ matches "(home).tsx" and captures "home"
+     */
+    routeFilePattern: RegExp;
+    /**
+     * Whether to serve /dir/index.html when accessing /dir/
+     */
+    enableIndexFallback: boolean;
+  };
+  /**
+   * Default rendering behavior for all routes.
+   */
+  rendering: {
+    /**
+     * Default render mode if not specified in route module exports.
+     */
+    defaultMode: RenderMode;
+    /**
+     * Default revalidation interval in seconds for ISR mode.
+     * Used if route doesn't specify custom revalidateSeconds.
+     */
+    defaultRevalidateSeconds: number;
+  };
+  /**
+   * HTML content to inject into every rendered page.
+   */
+  inject: {
+    /**
+     * Array of HTML strings to inject into <head>.
+     * Examples: meta tags, link tags, analytics scripts
+     */
+    head: string[];
+    /**
+     * Array of HTML strings to inject before closing </body>.
+     * Examples: analytics, logging scripts
+     */
+    bodyEnd: string[];
+  };
+  /**
+   * CSS and SCSS compilation configuration.
+   */
+  css: {
+    /**
+     * Path to global SCSS file to compile to styles.css.
+     * Relative to siteDir. Example: "styles/global.scss"
+     */
+    globalScss: string;
+    /**
+     * Maximum file size in bytes for critical CSS extraction.
+     * CSS larger than this may not be inlined in <head>.
+     */
+    criticalBudget?: number;
+    /**
+     * Whether to extract and inline critical CSS for above-the-fold content.
+     */
+    extractCritical?: boolean;
+  };
+  /**
+   * Static asset serving configuration.
+   */
+  assets: {
+    /**
+     * Directory containing public assets that should be copied to dist as-is.
+     * Relative to siteDir. Example: "public", "static"
+     */
+    publicDir: string;
+    /**
+     * HTTP Cache-Control header value for assets.
+     * Example: "public, max-age=31536000" for long-term caching
+     */
+    cacheControl: string;
+    /**
+     * Length of hash suffix for versioned asset filenames.
+     * Used for cache-busting. Example: 8 produces "app.a1b2c3d4.js"
+     */
+    hashLength?: number;
+  };
+  /**
+   * HTTP server configuration.
+   */
+  server: {
+    /**
+     * Port number for the development server.
+     * Example: 3000, 8080
+     */
+    port: number;
+    /**
+     * Hostname to bind the development server to.
+     * Example: "localhost", "0.0.0.0", "127.0.0.1"
+     */
+    hostname: string;
+  };
+  /**
+   * Optional build-time optimizations.
+   */
+  build?: {
+    /**
+     * Whether to minify HTML output in production builds.
+     */
+    minifyHtml?: boolean;
+    /**
+     * Whether to minify CSS output in production builds.
+     */
+    minifyCss?: boolean;
+    /**
+     * Whether to minify JavaScript output in production builds.
+     */
+    minifyJs?: boolean;
+    /**
+     * Whether to hash asset filenames for cache-busting.
+     * Example: "app.abc123.js" instead of "app.js"
+     */
+    hashAssets?: boolean;
+    /**
+     * Whether to generate an asset manifest JSON file for reverse lookups.
+     */
+    generateManifest?: boolean;
+    /**
+     * Whether to generate a sitemap.xml for SEO.
+     */
+    generateSitemap?: boolean;
+    /**
+     * Directory for storing build cache to enable incremental builds.
+     */
+    cacheDir?: string;
+    /**
+     * Whether to perform incremental builds (only rebuild changed files).
+     */
+    incrementalBuild?: boolean;
+    /**
+     * Whether to generate source maps for debugging in production.
+     */
+    sourceMap?: boolean;
+  };
+  /**
+   * Optional development server settings.
+   */
+  dev?: {
+    /**
+     * Whether to enable server-side rendering in development mode.
+     */
+    enableSSR?: boolean;
+    /**
+     * Whether to enable live reload on file changes.
+     */
+    liveReload?: boolean;
+    /**
+     * Custom port for development server (overrides server.port).
+     */
+    port?: number;
+  };
+  /**
+   * Optional SEO and search engine optimization settings.
+   */
+  seo?: {
+    /**
+     * Whether to automatically generate robots.txt.
+     */
+    generateRobotsTxt?: boolean;
+    /**
+     * Whether to automatically generate sitemap.xml.
+     */
+    generateSitemap?: boolean;
+    /**
+     * Base URL for sitemap entries.
+     * Example: "https://example.com"
+     */
+    sitemapBaseUrl?: string;
+  };
+};

package/templates/ssr-isr/lib/core/http.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage } from "node:http";
+/**
+ * Parses the HTTP Cookie header into an object of name-value pairs.
+ *
+ * Cookie format (RFC 6265):
+ * - Multiple cookies separated by semicolons
+ * - Each cookie is name=value with optional whitespace
+ * - Cookie values are URL-encoded and must be decoded
+ *
+ * Edge cases handled:
+ * - Missing or empty Cookie header returns empty object
+ * - Whitespace is trimmed from names and values
+ * - Values may contain equals signs (split only on first =)
+ * - Empty names or values are filtered out
+ * - Values are URL-decoded to handle special characters
+ *
+ * @param req Node.js IncomingMessage with headers property
+ *
+ * @returns Object with cookie names as keys and decoded values
+ *
+ * @example
+ * // Header: "sessionId=abc123; theme=dark; path=/admin"
+ * // Returns: { sessionId: "abc123", theme: "dark", path: "/admin" }
+ *
+ * // Header missing or empty
+ * // Returns: {}
+ */
+export declare function parseCookies(
+  req: IncomingMessage,
+): Record<string, string>;
+/**
+ * Converts Node.js headers object to a flat string-valued object.
+ *
+ * Header normalization:
+ * - Node.js headers may have array values (for multiple headers with same name)
+ * - Arrays are joined with comma-space to follow HTTP spec (RFC 2822)
+ * - Non-array string values are kept as-is
+ * - Header names are already lowercased by Node.js
+ *
+ * Motivation:
+ * Application code typically expects headers as a flat object with string values,
+ * not Node.js's mixed types. This normalizes the data structure for consistency.
+ *
+ * @param headers The headers object from IncomingMessage.headers
+ *
+ * @returns Flat object with header names (lowercase) as keys and string values
+ *
+ * @example
+ * // Input (from Node.js):
+ * { accept: "text/html", "accept-encoding": ["gzip", "deflate"], "content-type": "application/json" }
+ * // Output:
+ * { accept: "text/html", "accept-encoding": "gzip, deflate", "content-type": "application/json" }
+ */
+export declare function headersToObject(
+  headers: IncomingMessage["headers"],
+): Record<string, string>;

package/templates/ssr-isr/lib/core/http.js

@@ -0,0 +1,71 @@
+/**
+ * Parses the HTTP Cookie header into an object of name-value pairs.
+ *
+ * Cookie format (RFC 6265):
+ * - Multiple cookies separated by semicolons
+ * - Each cookie is name=value with optional whitespace
+ * - Cookie values are URL-encoded and must be decoded
+ *
+ * Edge cases handled:
+ * - Missing or empty Cookie header returns empty object
+ * - Whitespace is trimmed from names and values
+ * - Values may contain equals signs (split only on first =)
+ * - Empty names or values are filtered out
+ * - Values are URL-decoded to handle special characters
+ *
+ * @param req Node.js IncomingMessage with headers property
+ *
+ * @returns Object with cookie names as keys and decoded values
+ *
+ * @example
+ * // Header: "sessionId=abc123; theme=dark; path=/admin"
+ * // Returns: { sessionId: "abc123", theme: "dark", path: "/admin" }
+ *
+ * // Header missing or empty
+ * // Returns: {}
+ */
+export function parseCookies(req) {
+  const cookie = req.headers.cookie;
+  if (!cookie) return {};
+  const out = {};
+  for (const part of cookie.split(";")) {
+    const [k, ...rest] = part.trim().split("=");
+    const trimmedName = k.trim();
+    const trimmedValue = rest.join("=").trim();
+    if (trimmedName && trimmedValue) {
+      out[trimmedName] = decodeURIComponent(trimmedValue);
+    }
+  }
+  return out;
+}
+/**
+ * Converts Node.js headers object to a flat string-valued object.
+ *
+ * Header normalization:
+ * - Node.js headers may have array values (for multiple headers with same name)
+ * - Arrays are joined with comma-space to follow HTTP spec (RFC 2822)
+ * - Non-array string values are kept as-is
+ * - Header names are already lowercased by Node.js
+ *
+ * Motivation:
+ * Application code typically expects headers as a flat object with string values,
+ * not Node.js's mixed types. This normalizes the data structure for consistency.
+ *
+ * @param headers The headers object from IncomingMessage.headers
+ *
+ * @returns Flat object with header names (lowercase) as keys and string values
+ *
+ * @example
+ * // Input (from Node.js):
+ * { accept: "text/html", "accept-encoding": ["gzip", "deflate"], "content-type": "application/json" }
+ * // Output:
+ * { accept: "text/html", "accept-encoding": "gzip, deflate", "content-type": "application/json" }
+ */
+export function headersToObject(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (Array.isArray(v)) out[k] = v.join(", ");
+    else if (typeof v === "string") out[k] = v;
+  }
+  return out;
+}

package/templates/ssr-isr/lib/core/middleware-hooks.d.ts

@@ -0,0 +1,219 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * Context object passed to route middleware functions.
+ * Provides access to request data and response methods.
+ *
+ * Route middleware executes before the page loader and renderer.
+ * Middleware can:
+ * - Check authentication and authorization
+ * - Validate or transform request data
+ * - Set response headers or status codes
+ * - Attach data for use in loaders and page components
+ * - Short-circuit rendering by calling redirect() or json()
+ *
+ * Execution flow:
+ * 1. Route middleware array executes sequentially
+ * 2. Each middleware receives this context
+ * 3. Middleware can call next() implicitly by returning/not throwing
+ * 4. Early termination via redirect() or json() throws a sentinel error
+ * 5. After middleware, the loader runs with middleware.data pre-populated
+ *
+ * Example use cases:
+ * - Authentication: Check user session, throw redirect to login if needed
+ * - Data enrichment: Populate ctx.data with user info for the page
+ * - Response control: Set custom headers, status codes, CORS headers
+ * - Request validation: Validate params/query, return error JSON if invalid
+ */
+export interface RouteMiddlewareContext {
+  /**
+   * Node.js IncomingMessage with request method, URL, headers, etc.
+   * Direct access for advanced use cases not covered by the context.
+   */
+  req: IncomingMessage;
+  /**
+   * Node.js ServerResponse for sending responses.
+   * Methods status(), setHeader(), redirect(), and json() wrap this.
+   */
+  res: ServerResponse;
+  /**
+   * Parsed URL object with pathname, searchParams, host, etc.
+   * Same URL available in LoaderContext; middleware and loader see the same URL.
+   */
+  url: URL;
+  /**
+   * Route parameters extracted from the URL path by route matching.
+   * For route "/posts/:id" matching "/posts/42", yields { id: "42" }.
+   */
+  params: Record<string, string>;
+  /**
+   * Query string parameters from the URL search string.
+   * For "/search?q=test&limit=10", yields { q: "test", limit: "10" }.
+   */
+  query: Record<string, string>;
+  /**
+   * HTTP request headers as a normalized object.
+   * Keys are lowercase; values are strings or comma-separated lists.
+   */
+  headers: Record<string, string>;
+  /**
+   * Parsed HTTP cookies as an object.
+   * Keys are cookie names; values are decoded cookie values.
+   */
+  cookies: Record<string, string>;
+  /**
+   * Data object that middleware can populate.
+   * Data is passed to the loader and page component.
+   * Useful for sharing computed values (user info, locale, etc.) from middleware to components.
+   *
+   * @example
+   * ctx.data.userId = 42;  // Set in auth middleware
+   * ctx.data.locale = 'en'; // Set in i18n middleware
+   * // Then in loader and page: function Page({ data }) { ... data.userId ... }
+   */
+  data?: Record<string, any>;
+  /**
+   * Sets the HTTP response status code.
+   * Default is 200 (OK) unless changed by middleware.
+   * Returns this for method chaining.
+   *
+   * @param code HTTP status code (200, 404, 500, etc.)
+   * @returns This context for chaining with other methods
+   *
+   * @example ctx.status(404).json({ error: "Not found" });
+   */
+  status: (code: number) => RouteMiddlewareContext;
+  /**
+   * Sets an HTTP response header.
+   * Multiple calls with the same key overwrite previous values.
+   * Returns this for method chaining.
+   *
+   * @param key Header name (Content-Type, Set-Cookie, etc.)
+   * @param value Header value
+   * @returns This context for chaining
+   *
+   * @example ctx.setHeader("Cache-Control", "no-cache").setHeader("X-Custom", "value");
+   */
+  setHeader: (key: string, value: string) => RouteMiddlewareContext;
+  /**
+   * Sends a redirect response and stops middleware execution.
+   * Sets Location header and sends the response.
+   * Default status code is 302 (temporary redirect); 301 is permanent.
+   *
+   * Throws a sentinel error ("__REDIRECT__") to stop further execution.
+   * This error is caught by executeRouteMiddleware() and not re-thrown.
+   *
+   * @param url Destination URL for the redirect
+   * @param statusCode HTTP status code; defaults to 302 (temporary redirect)
+   * @throws Error with message "__REDIRECT__" to stop execution
+   *
+   * @example
+   * if (!user) ctx.redirect("/login", 302);  // Never returns; throw is implicit
+   */
+  redirect: (url: string, statusCode?: number) => never;
+  /**
+   * Sends a JSON response and stops middleware execution.
+   * Sets Content-Type and sends JSON-stringified data.
+   * Useful for API errors or early JSON responses.
+   *
+   * Throws a sentinel error ("__JSON__") to stop further execution.
+   * This error is caught and not re-thrown.
+   *
+   * @param data Object or value to JSON-encode and send
+   * @param statusCode HTTP status code; defaults to 200 (OK)
+   * @throws Error with message "__JSON__" to stop execution
+   *
+   * @example
+   * if (!params.id) ctx.json({ error: "Missing id" }, 400);  // Never returns
+   */
+  json: (data: any, statusCode?: number) => never;
+}
+/**
+ * Middleware function that executes for a specific route before rendering.
+ *
+ * Signature:
+ * - Accepts RouteMiddlewareContext
+ * - Returns nothing (void or Promise<void>)
+ * - Can be sync or async
+ *
+ * Behavior:
+ * - Return/resolve to continue to next middleware or rendering
+ * - Call ctx.redirect() or ctx.json() to send response and stop
+ * - Throw an error to propagate error to error handler
+ * - Modifying ctx.data shares values with loader and page
+ *
+ * @example
+ * const authMiddleware: RouteMiddleware = async (ctx) => {
+ *   const user = await getUser(ctx.cookies.sessionId);
+ *   if (!user) ctx.redirect("/login");
+ *   ctx.data.user = user;  // Available in loader and page
+ * };
+ */
+export type RouteMiddleware = (
+  ctx: RouteMiddlewareContext,
+) => Promise<void> | void;
+/**
+ * Type definitions note:
+ * Route module types (middleware field, hydrate field) are defined in core/types.ts.
+ * This module provides the middleware execution engine and context object.
+ */
+/**
+ * Creates a middleware context object from request data.
+ * Called by the renderer before executing route middleware.
+ *
+ * Initializes:
+ * - All request data (req, res, url, params, query, headers, cookies)
+ * - Empty data object for middleware to populate
+ * - Helper methods (status, setHeader, redirect, json) as chainable methods
+ *
+ * @param opts Configuration with raw request data
+ * @param opts.req Node.js IncomingMessage
+ * @param opts.res Node.js ServerResponse
+ * @param opts.url Parsed URL from request
+ * @param opts.params Route parameters from URL path
+ * @param opts.query Query string parameters
+ * @param opts.headers Normalized headers object
+ * @param opts.cookies Parsed cookies from Cookie header
+ *
+ * @returns Initialized RouteMiddlewareContext ready for middleware execution
+ */
+export declare function createRouteMiddlewareContext(opts: {
+  req: IncomingMessage;
+  res: ServerResponse;
+  url: URL;
+  params: Record<string, string>;
+  query: Record<string, string>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+}): RouteMiddlewareContext;
+/**
+ * Executes an array of route middleware sequentially for a route.
+ *
+ * Execution model:
+ * 1. Iterates through middlewares in order
+ * 2. Each middleware is awaited (even if synchronous)
+ * 3. Middleware can populate ctx.data for use by loader and page
+ * 4. If middleware calls ctx.redirect() or ctx.json(), error is caught and re-thrown
+ * 5. Other errors are propagated immediately
+ *
+ * Control flow:
+ * - Normal completion: all middlewares finish and function returns
+ * - Early exit: middleware calls ctx.redirect() or ctx.json()
+ * - Error: middleware throws or ctx.redirect()/json() throws sentinel error
+ *
+ * Side effects:
+ * - Response headers, status, and body may be sent by middleware
+ * - ctx.data may be modified by middleware
+ * - Should only be called in server context (SSR); not during SSG build
+ *
+ * @param middlewares Array of middleware functions to execute
+ * @param ctx RouteMiddlewareContext created by createRouteMiddlewareContext()
+ *
+ * @returns Promise that resolves if all middlewares complete normally
+ * @throws Error with message "__REDIRECT__" if middleware calls ctx.redirect()
+ * @throws Error with message "__JSON__" if middleware calls ctx.json()
+ * @throws Error from middleware if it throws
+ */
+export declare function executeRouteMiddleware(
+  middlewares: RouteMiddleware[],
+  ctx: RouteMiddlewareContext,
+): Promise<void>;