alepha 0.14.3 → 0.14.4

package/src/server/compress/providers/ServerCompressProvider.ts

@@ -136,12 +136,71 @@ export class ServerCompressProvider {
 
     if (typeof body === "object" && body instanceof ReadableStream) {
       this.setHeaders(response, encoding);
-      response.body = Readable.fromWeb(body).pipe(
-        compressor.stream({ params }),
+      // For streaming responses, use flush mode to avoid buffering
+      response.body = this.createFlushingCompressStream(
+        body,
+        compressor.stream,
+        encoding,
+        params,
       );
     }
   }
 
+  /**
+   * Create a compressed stream that flushes after each chunk.
+   * This is essential for streaming SSR - ensures each chunk is sent immediately.
+   */
+  protected createFlushingCompressStream(
+    input: ReadableStream,
+    createCompressor: (options?: any) => Transform,
+    encoding: string,
+    params: Record<number, any>,
+  ): ReadableStream<Uint8Array> {
+    const compressor = createCompressor({
+      params,
+      flush: zlib.constants.Z_SYNC_FLUSH,
+    });
+    const reader = Readable.fromWeb(input);
+
+    return new ReadableStream<Uint8Array>({
+      start(controller) {
+        compressor.on("data", (chunk: Buffer) => {
+          controller.enqueue(new Uint8Array(chunk));
+        });
+
+        compressor.on("end", () => {
+          controller.close();
+        });
+
+        compressor.on("error", (err) => {
+          controller.error(err);
+        });
+
+        reader.on("data", (chunk: Buffer) => {
+          compressor.write(chunk);
+          // Force flush after each chunk for streaming
+          // Cast to any because flush() exists on zlib streams but not in Transform type
+          const zlibStream = compressor as any;
+          if (encoding === "gzip") {
+            zlibStream.flush(zlib.constants.Z_SYNC_FLUSH);
+          } else if (encoding === "br") {
+            zlibStream.flush(zlib.constants.BROTLI_OPERATION_FLUSH);
+          } else if (encoding === "zstd") {
+            zlibStream.flush();
+          }
+        });
+
+        reader.on("end", () => {
+          compressor.end();
+        });
+
+        reader.on("error", (err) => {
+          controller.error(err);
+        });
+      },
+    });
+  }
+
   protected getParams(
     encoding: keyof typeof ServerCompressProvider.compressors,
   ): Record<number, any> {

package/src/server/core/helpers/ServerReply.ts

@@ -12,9 +12,9 @@ export class ServerReply {
   public body?: any;
 
   /**
-   * Redirect to a given URL with optional status code (default 302).
+   * Redirect to a given URL with optional status code (default 301).
    */
-  public redirect(url: string, status: number = 302): void {
+  public redirect(url: string, status: number = 301): void {
     this.status = status;
     this.headers.location = url;
   }

package/src/server/core/providers/ServerProvider.ts

@@ -27,6 +27,9 @@ export class ServerProvider {
   protected readonly internalServerErrorMessage = "Internal Server Error";
 
   public get hostname(): string {
+    if (this.alepha.isViteDev()) {
+      return `http://localhost:${this.alepha.env.SERVER_PORT}`;
+    }
     return ""; // no hostname in serverless mode
   }
 
@@ -116,9 +119,16 @@ export class ServerProvider {
     // if response.body is web stream
     if (response.body instanceof ReadableStream) {
       res.writeHead(response.status, response.headers);
+      // Flush headers immediately and disable Nagle's algorithm for streaming
+      res.flushHeaders();
+      res.socket?.setNoDelay(true);
       try {
         for await (const chunk of response.body) {
-          res.write(chunk);
+          const canContinue = res.write(chunk);
+          // If the internal buffer is full, wait for it to drain
+          if (!canContinue) {
+            await new Promise<void>((resolve) => res.once("drain", resolve));
+          }
         }
       } catch (error) {
         this.log.error("Error piping proxy response stream", error);

package/src/server/static/providers/ServerStaticProvider.ts

@@ -136,6 +136,16 @@ export class ServerStaticProvider {
       const { headers, reply } = request;
       let path = filepath;
 
+      // 01/26 - when calling "/directory", redirect to "/directory/"
+      if (
+        options.path &&
+        options.path === request.url.pathname &&
+        !options.path.endsWith("/")
+      ) {
+        reply.redirect(`${options.path}/`);
+        return;
+      }
+
       const encoding = headers["accept-encoding"];
       if (encoding) {
         if (hasBr && encoding.includes("br")) {

package/src/server/swagger/providers/ServerSwaggerProvider.ts

@@ -80,10 +80,6 @@ export class ServerSwaggerProvider {
       }
 
       this.json = await this.setupSwaggerPlugin(options);
-
-      if (this.json) {
-        this.log.info("Swagger documentation generated successfully.");
-      }
     },
   });
 
@@ -115,6 +111,8 @@ export class ServerSwaggerProvider {
 
     if (options.ui !== false) {
       await this.configureSwaggerUi(prefix, options);
+    } else {
+      this.log.info(`Swagger API available at ${prefix}/json`);
     }
 
     return json;
@@ -362,7 +360,6 @@ export class ServerSwaggerProvider {
       },
       handler: () => json,
     });
-    this.log.info(`Swagger API available at ${prefix}/json`);
   }
 
   protected async configureSwaggerUi(
@@ -428,9 +425,9 @@ window.onload = function() {
       },
     });
 
-    this.log.info(
-      `Swagger UI available at ${this.serverProvider.hostname}${prefix}/`,
-    );
+    this.log.info("SwaggerUI OK", {
+      url: `${this.serverProvider.hostname}${prefix}`,
+    });
   }
 
   protected async getAssetPath(

package/src/vite/helpers/importViteReact.ts

@@ -0,0 +1,13 @@
+import { createRequire } from "node:module";
+
+export const importViteReact = async (): Promise<any> => {
+  // Add React plugin for JSX/TSX compilation
+  try {
+    const { default: viteReact } = createRequire(import.meta.url)(
+      "@vitejs/plugin-react",
+    );
+    return viteReact;
+  } catch {
+    // @vitejs/plugin-react not installed, skip
+  }
+};

package/src/vite/index.ts

@@ -4,9 +4,8 @@ import type { Alepha } from "alepha";
 export * from "./helpers/boot.ts";
 export * from "./helpers/createBufferedLogger.ts";
 // Plugins (public API)
-export * from "./plugins/viteAlepha.ts";
-export * from "./plugins/viteAlephaBuild.ts";
 export * from "./plugins/viteAlephaDev.ts";
+export * from "./plugins/viteAlephaSsrPreload.ts";
 export * from "./plugins/viteCompress.ts";
 // Tasks (for CLI integration)
 export * from "./tasks/index.ts";
@@ -14,22 +13,3 @@ export * from "./tasks/index.ts";
 declare global {
   var __cli_alepha: Alepha;
 }
-
-/**
- * Plugin vite for Alepha framework.
- *
- * This module provides Vite plugins and configurations to integrate Alepha applications with Vite's build and development processes.
- *
- * @example
- * ```ts
- * import { defineConfig } from "vite";
- * import { viteAlepha } from "alepha/vite";
- *
- * export default defineConfig({
- *   plugins: [viteAlepha()],
- *   // other Vite configurations...
- * });
- * ```
- *
- * @module alepha.vite
- */

package/src/vite/plugins/viteAlephaDev.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { Plugin, ResolvedConfig } from "vite";
+import type { Plugin, ResolvedConfig, UserConfig } from "vite";
 import { boot } from "../helpers/boot.ts";
+import { importVite } from "../helpers/importVite.ts";
 import { createAlephaRunner, isViteInternalPath } from "../tasks/runAlepha.ts";
 
 export interface ViteAlephaDevOptions {
@@ -44,9 +45,20 @@ export async function viteAlephaDev(
     debug: options.debug,
   });
 
+  const { loadEnv } = await importVite();
+  const env = loadEnv("development", process.cwd(), "SERVER");
+
+  const config: UserConfig = {};
+  if (env.SERVER_PORT) {
+    config.server = {
+      port: parseInt(env.SERVER_PORT, 10),
+    };
+  }
+
   return {
     name: "alepha-dev",
     apply: "serve",
+    config: () => config,
     configResolved(resolvedConfig: ResolvedConfig) {
       runner.setConfig(resolvedConfig);
     },
@@ -103,6 +115,9 @@ export async function viteAlephaDev(
       }
     },
     async configureServer(server) {
+      if (env.SERVER_PORT) {
+        server.config.server.port = parseInt(env.SERVER_PORT, 10);
+      }
       const middleware = (
         req: IncomingMessage,
         res: ServerResponse,

package/src/vite/plugins/viteAlephaSsrPreload.ts

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import type { Plugin } from "vite";
+
+/**
+ * Preload manifest mapping short keys to source paths.
+ * Generated at build time, consumed by SSRManifestProvider at runtime.
+ */
+export interface PreloadManifest {
+  [key: string]: string;
+}
+
+/**
+ * Vite plugin that generates a preload manifest for SSR module preloading.
+ *
+ * Instead of injecting source paths directly into $page definitions (which would
+ * leak component paths in the browser bundle), this plugin:
+ *
+ * 1. Collects all lazy import paths from $page definitions during transform
+ * 2. Generates a manifest file mapping short keys to resolved source paths
+ * 3. Injects only the short key into $page definitions
+ *
+ * The manifest is written to `.vite/preload-manifest.json` alongside Vite's
+ * other manifests. The CLI build command moves all manifests to
+ * `dist/server/.ssr/` where SSRManifestProvider loads them at runtime.
+ *
+ * Before:
+ * ```typescript
+ * $page({
+ *   path: '/users/:id',
+ *   lazy: () => import('./UserDetail.tsx'),
+ * })
+ * ```
+ *
+ * After:
+ * ```typescript
+ * $page({
+ *   path: '/users/:id',
+ *   lazy: () => import('./UserDetail.tsx'),
+ *   [Symbol.for("alepha.page.preload")]: "a1b2c3",
+ * })
+ * ```
+ *
+ * Manifest (.alepha/preload-manifest.json):
+ * ```json
+ * {
+ *   "a1b2c3": "src/pages/UserDetail.tsx"
+ * }
+ * ```
+ */
+export function viteAlephaSsrPreload(): Plugin {
+  let root = "";
+  const preloadMap = new Map<string, string>(); // key -> sourcePath
+
+  /**
+   * Generate a short hash key for a source path.
+   * Uses first 8 chars of MD5 hash for brevity while avoiding collisions.
+   */
+  function generateKey(sourcePath: string): string {
+    return createHash("md5").update(sourcePath).digest("hex").slice(0, 8);
+  }
+
+  return {
+    name: "alepha-preload",
+    configResolved(config) {
+      root = config.root;
+    },
+    transform(code, id) {
+      // Only process TypeScript/JavaScript files
+      if (!id.match(/\.[tj]sx?$/)) {
+        return null;
+      }
+
+      // Skip node_modules
+      if (id.includes("node_modules")) {
+        return null;
+      }
+
+      // Quick check if file contains $page with lazy
+      if (!code.includes("$page") || !code.includes("lazy")) {
+        return null;
+      }
+
+      // Collect all insertions first, then apply in reverse order
+      const insertions: Array<{ position: number; text: string }> = [];
+
+      // Find all $page({ occurrences
+      const pageStartRegex = /\$page\s*\(\s*\{/g;
+      let pageMatch: RegExpExecArray | null = pageStartRegex.exec(code);
+
+      while (pageMatch !== null) {
+        const startIndex = pageMatch.index;
+        const objectStartIndex = startIndex + pageMatch[0].length - 1; // Position of '{'
+
+        // Find the matching closing brace using brace counting
+        let braceCount = 1;
+        let i = objectStartIndex + 1;
+        while (i < code.length && braceCount > 0) {
+          if (code[i] === "{") braceCount++;
+          else if (code[i] === "}") braceCount--;
+          i++;
+        }
+
+        // Malformed, skip
+        if (braceCount !== 0) {
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        const objectEndIndex = i - 1; // Position of matching '}'
+        const pageContent = code.slice(objectStartIndex, objectEndIndex + 1);
+
+        // Skip if already has preload symbol
+        if (pageContent.includes("alepha.page.preload")) {
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        // Find lazy: () => import('...') within this $page block
+        const lazyRegex =
+          /lazy\s*:\s*\(\s*\)\s*=>\s*import\s*\(\s*['"]([^'"]+)['"]\s*\)/;
+        const lazyMatch = lazyRegex.exec(pageContent);
+
+        if (!lazyMatch) {
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        const importPath = lazyMatch[1];
+
+        // Resolve the import path relative to the current file
+        const currentDir = dirname(id);
+        let resolvedPath: string;
+
+        if (importPath.startsWith(".")) {
+          // Relative import
+          resolvedPath = resolve(currentDir, importPath);
+        } else if (importPath.startsWith("/")) {
+          // Absolute import from root
+          resolvedPath = resolve(root, importPath.slice(1));
+        } else {
+          // Package import - skip preloading for external packages
+          pageMatch = pageStartRegex.exec(code);
+          continue;
+        }
+
+        // Make path relative to root for SSR manifest lookup
+        let relativePath = relative(root, resolvedPath);
+
+        // Normalize path separators for cross-platform compatibility
+        relativePath = relativePath.replace(/\\/g, "/");
+
+        // Handle extension - Vite resolves .jsx imports to .tsx files
+        // Try to use .tsx when the source has .jsx since TypeScript is more common
+        if (!relativePath.match(/\.[tj]sx?$/)) {
+          relativePath = `${relativePath}.tsx`;
+        } else if (relativePath.endsWith(".jsx")) {
+          // Import said .jsx but actual file is likely .tsx
+          relativePath = relativePath.replace(/\.jsx$/, ".tsx");
+        } else if (relativePath.endsWith(".js")) {
+          // Import said .js but actual file is likely .ts
+          relativePath = relativePath.replace(/\.js$/, ".ts");
+        }
+
+        // Generate short key and store mapping
+        const key = generateKey(relativePath);
+        preloadMap.set(key, relativePath);
+
+        // Check if we need a comma (look at character before closing brace)
+        const beforeBrace = code.slice(0, objectEndIndex).trimEnd();
+        const needsComma = !beforeBrace.endsWith(",");
+        // Use Symbol.for() so it can be looked up at runtime without importing
+        // Only inject the short key, not the full path
+        const preloadProperty = `${needsComma ? "," : ""} [Symbol.for("alepha.page.preload")]: "${key}"`;
+
+        insertions.push({ position: objectEndIndex, text: preloadProperty });
+
+        pageMatch = pageStartRegex.exec(code);
+      }
+
+      if (insertions.length === 0) {
+        return null;
+      }
+
+      // Apply insertions in reverse order to preserve positions
+      let result = code;
+      for (let j = insertions.length - 1; j >= 0; j--) {
+        const { position, text } = insertions[j];
+        result = result.slice(0, position) + text + result.slice(position);
+      }
+
+      return {
+        code: result,
+        map: null,
+      };
+    },
+    writeBundle(options) {
+      // Only process client build (outputs to dist/public or similar)
+      // Skip server build which outputs to dist/server
+      const outDir = options.dir || "";
+      if (outDir.includes("server")) {
+        return;
+      }
+
+      // Write the preload manifest to the same .vite directory Vite uses
+      // The CLI build command will move all manifests to dist/server/.ssr/
+      if (preloadMap.size > 0) {
+        const viteDir = join(outDir, ".vite");
+
+        // Ensure .vite directory exists
+        if (!existsSync(viteDir)) {
+          mkdirSync(viteDir, { recursive: true });
+        }
+
+        const manifest: PreloadManifest = Object.fromEntries(preloadMap);
+        const manifestPath = join(viteDir, "preload-manifest.json");
+        writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+      }
+    },
+  };
+}

package/src/vite/tasks/buildClient.ts

@@ -2,6 +2,8 @@ import type { UserConfig } from "vite";
 import { analyzer as viteAnalyzer } from "vite-bundle-analyzer";
 import { createBufferedLogger } from "../helpers/createBufferedLogger.ts";
 import { importVite } from "../helpers/importVite.ts";
+import { importViteReact } from "../helpers/importViteReact.ts";
+import { viteAlephaSsrPreload } from "../plugins/viteAlephaSsrPreload.ts";
 import {
   type ViteCompressOptions,
   viteCompress,
@@ -62,6 +64,12 @@ export async function buildClient(opts: BuildClientOptions): Promise<void> {
   const { build: viteBuild, mergeConfig } = await importVite();
   const plugins: any[] = [];
 
+  const viteReact = await importViteReact();
+  if (viteReact) plugins.push(viteReact());
+
+  // Add preload plugin for SSR module preloading
+  plugins.push(viteAlephaSsrPreload());
+
   const compress: ViteCompressOptions | undefined = opts.precompress
     ? typeof opts.precompress === "object"
       ? opts.precompress
@@ -93,6 +101,9 @@ export async function buildClient(opts: BuildClientOptions): Promise<void> {
     build: {
       chunkSizeWarningLimit: 1000,
       outDir: opts.dist,
+      // Generate manifest for SSR module preloading
+      manifest: true,
+      ssrManifest: true,
       rollupOptions: {
         output: {
           entryFileNames: "entry.[hash].js",

package/src/vite/tasks/buildServer.ts

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { AlephaError } from "alepha";
 import type * as vite from "vite";
@@ -6,6 +6,8 @@ import type { UserConfig } from "vite";
 import { analyzer as viteAnalyzer } from "vite-bundle-analyzer";
 import { createBufferedLogger } from "../helpers/createBufferedLogger.ts";
 import { importVite } from "../helpers/importVite.ts";
+import { importViteReact } from "../helpers/importViteReact.ts";
+import { viteAlephaSsrPreload } from "../plugins/viteAlephaSsrPreload.ts";
 import { generateExternals } from "./generateExternals.ts";
 
 export interface BuildServerOptions {
@@ -63,6 +65,13 @@ export async function buildServer(
   const { build: viteBuild, mergeConfig } = await importVite();
   const plugins: any[] = [];
 
+  const viteReact = await importViteReact();
+  if (viteReact && opts.clientDir) {
+    plugins.push(viteReact());
+  }
+
+  plugins.push(viteAlephaSsrPreload());
+
   if (opts.stats) {
     plugins.push(
       viteAnalyzer({
@@ -85,7 +94,7 @@ export async function buildServer(
       noExternal: true,
     },
     build: {
-      sourcemap: true, // or "hidden" if you don't want to expose source maps
+      sourcemap: true,
       ssr: opts.entry,
       outDir: `${opts.distDir}/server`,
       minify: true,
@@ -138,6 +147,29 @@ export async function buildServer(
     template = `__alepha.set("alepha.react.server.template", \`${index.replace(/>\s*</g, "><").trim()}\`);\n`;
   }
 
+  // Embed SSR manifests if client was built
+  // This bundles all manifest data into index.js for serverless deployments
+  let manifest = "";
+  if (opts.clientDir) {
+    const viteDir = `${opts.distDir}/${opts.clientDir}/.vite`;
+    const ssrManifest = await loadJsonFile(`${viteDir}/ssr-manifest.json`);
+    const clientManifest = await loadJsonFile(`${viteDir}/manifest.json`);
+    const preloadManifest = await loadJsonFile(
+      `${viteDir}/preload-manifest.json`,
+    );
+
+    const combined = {
+      ssr: ssrManifest,
+      client: clientManifest,
+      preload: preloadManifest,
+    };
+
+    manifest = `__alepha.set("alepha.react.ssr.manifest", ${JSON.stringify(combined)});\n`;
+
+    // Remove .vite directory - no longer needed at runtime
+    await rm(viteDir, { recursive: true, force: true });
+  }
+
   const warning =
     "// This file was automatically generated. DO NOT MODIFY." +
     "\n" +
@@ -145,12 +177,24 @@ export async function buildServer(
 
   await writeFile(
     `${opts.distDir}/index.js`,
-    `${warning}\nimport './server/${entryFile}';\n\n${template}`.trim(),
+    `${warning}\n${template}${manifest}import './server/${entryFile}';\n`.trim(),
   );
 
   return { entryFile };
 }
 
+/**
+ * Load a JSON file, returning undefined if it doesn't exist.
+ */
+async function loadJsonFile(path: string): Promise<any> {
+  try {
+    const content = await readFile(path, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Extract entry filename from Vite build result.
  */

package/src/vite/tasks/devServer.ts

@@ -0,0 +1,69 @@
+import type { InlineConfig } from "vite";
+import { importVite } from "../helpers/importVite.ts";
+import { importViteReact } from "../helpers/importViteReact.ts";
+import { viteAlephaDev } from "../plugins/viteAlephaDev.ts";
+import { viteAlephaSsrPreload } from "../plugins/viteAlephaSsrPreload.ts";
+
+export interface DevServerOptions {
+  /**
+   * Path to the server entry file.
+   * If not provided, will auto-detect.
+   */
+  entry?: string;
+
+  /**
+   * Port to run the dev server on.
+   */
+  port?: number;
+
+  /**
+   * Host to bind the dev server to.
+   */
+  host?: string | boolean;
+
+  /**
+   * Enable debug logging.
+   */
+  debug?: boolean;
+}
+
+/**
+ * Start Vite development server with Alepha plugins.
+ *
+ * This task starts the Vite dev server with all required plugins:
+ * - @vitejs/plugin-react (JSX/TSX compilation)
+ * - viteAlephaDev (Alepha server integration)
+ * - viteAlephaSsrPreload (SSR module preloading)
+ */
+export async function devServer(opts: DevServerOptions = {}): Promise<void> {
+  const { createServer, mergeConfig } = await importVite();
+  const plugins: any[] = [];
+
+  // Add React plugin for JSX/TSX compilation
+  const viteReact = await importViteReact();
+  if (viteReact) plugins.push(viteReact());
+
+  // Add SSR preload plugin
+  plugins.push(viteAlephaSsrPreload());
+
+  // Add Alepha dev plugin
+  plugins.push(
+    await viteAlephaDev({
+      serverEntry: opts.entry,
+      debug: opts.debug,
+    }),
+  );
+
+  const config: InlineConfig = {
+    plugins,
+    server: {
+      port: opts.port,
+      host: opts.host,
+    },
+  };
+
+  const server = await createServer(mergeConfig(config, {}));
+  await server.listen();
+
+  // server.printUrls();
+}