alepha 0.15.0 → 0.15.2

package/src/vite/tasks/buildServer.ts

@@ -1,6 +1,6 @@
 import { readFile, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { AlephaError } from "alepha";
+import { type Alepha, AlephaError } from "alepha";
 import type * as vite from "vite";
 import type { UserConfig } from "vite";
 import { analyzer as viteAnalyzer } from "vite-bundle-analyzer";
@@ -27,11 +27,6 @@ export interface BuildServerOptions {
    */
   clientDir?: string;
 
-  /**
-   * Override Vite config options.
-   */
-  config?: UserConfig;
-
   /**
    * If true, generate build stats report.
    */
@@ -48,6 +43,11 @@ export interface BuildServerOptions {
    * Add more entry point conditions for SSR module resolution (e.g., "bun").
    */
   conditions?: string[];
+
+  /**
+   * Alepha instance to set SSR manifest for pre-rendering.
+   */
+  alepha: Alepha;
 }
 
 export interface BuildServerResult {
@@ -55,6 +55,16 @@ export interface BuildServerResult {
    * The filename of the built server entry (e.g., "abc123.js").
    */
   entryFile: string;
+
+  /**
+   * SSR manifest data for module preloading.
+   * Can be used to set in alepha store for pre-rendering.
+   */
+  manifest?: {
+    base?: string;
+    client?: Record<string, any>;
+    preload?: Record<string, string>;
+  };
 }
 
 /**
@@ -67,7 +77,7 @@ export interface BuildServerResult {
 export async function buildServer(
   opts: BuildServerOptions,
 ): Promise<BuildServerResult> {
-  const { build: viteBuild, mergeConfig } = await importVite();
+  const { build: viteBuild, resolveConfig } = await importVite();
   const plugins: any[] = [];
 
   const viteReact = await importViteReact();
@@ -93,6 +103,7 @@ export async function buildServer(
     conditions.unshift(...opts.conditions);
   }
 
+  // note: we still can override this config via config file (vite.config.ts)
   const viteBuildServerConfig: UserConfig = {
     mode: "production",
     logLevel: opts.silent ? "silent" : undefined,
@@ -121,24 +132,32 @@ export async function buildServer(
       },
     },
     esbuild: { legalComments: "none", keepNames: true },
-    customLogger: logger,
+    customLogger: logger, // mock logger to avoid noisy output
     plugins,
   };
 
+  // create inline config by merging alepha built-in + extended config
+
   let result: vite.Rollup.RollupOutput | vite.Rollup.RollupOutput[];
   try {
-    result = (await viteBuild(
-      mergeConfig(viteBuildServerConfig, opts.config || {}),
-    )) as vite.Rollup.RollupOutput | vite.Rollup.RollupOutput[];
+    result = (await viteBuild(viteBuildServerConfig)) as
+      | vite.Rollup.RollupOutput
+      | vite.Rollup.RollupOutput[];
   } catch (error) {
-    // Flush buffered logs on failure so user can see what happened
+    // flush buffered logs on failure so user can see what happened
     logger?.flush();
     throw error;
   }
 
-  // Extract resolved config to get externals
-  const resolvedConfig = (result as any).resolvedConfig;
-  const externals: string[] = resolvedConfig?.ssr?.external ?? [];
+  // resolve final config to read externals
+  const resolvedConfig = await resolveConfig(viteBuildServerConfig, "build");
+
+  // extract resolved config to get externals
+  const externals: string[] = [];
+
+  if (Array.isArray(resolvedConfig?.ssr?.external)) {
+    externals.push(...resolvedConfig.ssr.external);
+  }
 
   // Generate package.json with externals
   await generateExternals({
@@ -161,21 +180,44 @@ export async function buildServer(
   // Embed SSR manifests if client was built
   // This bundles all manifest data into index.js for serverless deployments
   let manifest = "";
+  let manifestData:
+    | {
+        base?: string;
+        client?: Record<string, any>;
+        preload?: Record<string, string>;
+      }
+    | undefined;
+
   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,
+    // Strip unused fields from client manifest to reduce bundle size
+    const strippedClientManifest = stripClientManifest(clientManifest);
+
+    // Get base path from resolved config (defaults to "/" if not set)
+    // Normalize: ensure it starts with "/" and doesn't end with "/" (unless it's just "/")
+    let base = resolvedConfig.base || "/";
+    if (!base.startsWith("/")) {
+      base = `/${base}`;
+    }
+    if (base.length > 1 && base.endsWith("/")) {
+      base = base.slice(0, -1);
+    }
+
+    manifestData = {
+      base: base !== "/" ? base : undefined, // Only include if not default
+      client: strippedClientManifest,
       preload: preloadManifest,
     };
 
-    manifest = `__alepha.set("alepha.react.ssr.manifest", ${JSON.stringify(combined)});\n`;
+    manifest = `__alepha.set("alepha.react.ssr.manifest", ${JSON.stringify(manifestData)});\n`;
+
+    // Set manifest in alepha store for pre-rendering
+    opts.alepha.store.set("alepha.react.ssr.manifest" as any, manifestData);
 
     // Remove .vite directory - no longer needed at runtime
     await rm(viteDir, { recursive: true, force: true });
@@ -191,7 +233,7 @@ export async function buildServer(
     `${warning}\n${template}${manifest}import './server/${entryFile}';\n`.trim(),
   );
 
-  return { entryFile };
+  return { entryFile, manifest: manifestData };
 }
 
 /**
@@ -206,6 +248,27 @@ async function loadJsonFile(path: string): Promise<any> {
   }
 }
 
+/**
+ * Strip unused fields from client manifest to reduce bundle size.
+ * Only keeps: file, isEntry, imports, css
+ */
+function stripClientManifest(
+  manifest: Record<string, any> | undefined,
+): Record<string, any> | undefined {
+  if (!manifest) return undefined;
+
+  const stripped: Record<string, any> = {};
+  for (const [key, entry] of Object.entries(manifest)) {
+    stripped[key] = {
+      file: entry.file,
+      ...(entry.isEntry && { isEntry: entry.isEntry }),
+      ...(entry.imports?.length && { imports: entry.imports }),
+      ...(entry.css?.length && { css: entry.css }),
+    };
+  }
+  return stripped;
+}
+
 /**
  * Extract entry filename from Vite build result.
  */

package/src/vite/tasks/copyAssets.ts

@@ -1,9 +1,10 @@
 import { cp, mkdir } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
-import { importAlepha } from "../helpers/importAlepha.ts";
+import type { Alepha } from "alepha";
 
 export interface CopyAssetsOptions {
+  alepha: Alepha;
   /**
    * Entry point for the built Alepha application.
    */
@@ -17,7 +18,7 @@ export interface CopyAssetsOptions {
   /**
    * @default process.cwd()
    */
-  root?: string;
+  root: string;
 
   /**
    * Add Runner for logging (@see Alepha CLI)
@@ -38,8 +39,8 @@ export interface CopyAssetsOptions {
  * Used by modules like AlephaServerSwagger to distribute UI files.
  */
 export async function copyAssets(opts: CopyAssetsOptions): Promise<void> {
-  const root = opts.root ?? process.cwd();
-  const alepha = await importAlepha(opts.entry);
+  const root = opts.root;
+  const alepha = opts.alepha;
   const assets = alepha.store.get("alepha.build.assets");
 
   if (!assets || assets.length === 0) {

package/src/vite/tasks/generateSitemap.ts

@@ -1,11 +1,11 @@
+import { writeFile } from "node:fs/promises";
 import type { Alepha } from "alepha";
-import { importAlepha } from "../helpers/importAlepha.ts";
 
 export interface GenerateSitemapOptions {
   /**
-   * Entry point for the built Alepha application.
+   * Alepha instance to use for generating the sitemap.
    */
-  entry: string;
+  alepha: Alepha;
 
   /**
    * Base URL for the sitemap (e.g., "https://example.com").
@@ -13,52 +13,93 @@ export interface GenerateSitemapOptions {
   baseUrl: string;
 
   /**
-   * Optional HTML template (for React SSR).
+   * Output file path for the sitemap. If provided, writes the sitemap to disk.
    */
-  template?: string;
+  output?: string;
+
+  /**
+   * Add Runner for logging (@see Alepha CLI)
+   */
+  run?: (opts: {
+    name: string;
+    handler: () => Promise<void>;
+  }) => Promise<string>;
 }
 
 /**
  * Generate sitemap.xml from Alepha page primitives.
  *
- * This task loads the built Alepha application,
- * queries all page primitives, and generates a sitemap.xml
+ * Queries all page primitives and generates a sitemap.xml
  * containing URLs for all accessible pages.
  */
 export async function generateSitemap(
   opts: GenerateSitemapOptions,
 ): Promise<string> {
-  const alepha = await importAlepha(opts.entry);
+  const pages = getSitemapPages(opts.alepha);
 
-  if (opts.template) {
-    alepha.set("alepha.react.server.template", opts.template);
+  // Nothing to generate
+  if (pages.length === 0) {
+    return "";
   }
 
-  if (!alepha.isConfigured()) {
-    await alepha.events.emit("configure", alepha);
-    (alepha as any).configured = true;
+  let result = "";
+
+  const fn = async () => {
+    result = generateSitemapFromPages(pages, opts.baseUrl);
+    if (opts.output) {
+      await writeFile(opts.output, result);
+    }
+  };
+
+  if (opts.run) {
+    await opts.run({
+      name: "generate sitemap",
+      handler: fn,
+    });
+  } else {
+    await fn();
   }
 
-  return generateSitemapFromAlepha(alepha, opts.baseUrl);
+  return result;
 }
 
-function generateSitemapFromAlepha(alepha: Alepha, baseUrl: string): string {
+/**
+ * Get all pages that should be included in the sitemap.
+ */
+function getSitemapPages(alepha: Alepha): any[] {
   const pages = alepha.primitives("page") as any[];
-  const urls: string[] = [];
-
-  for (const page of pages) {
+  return pages.filter((page) => {
     const options = page.options;
-
     // Skip pages with children (parent pages that can't be rendered directly)
     if (options.children) {
-      continue;
+      return false;
+    }
+    // Include pages without parameters or static pages with entries
+    if (!options.schema?.params) {
+      return true;
+    }
+    if (
+      options.static &&
+      typeof options.static === "object" &&
+      options.static.entries
+    ) {
+      return true;
     }
+    return false;
+  });
+}
+
+function generateSitemapFromPages(pages: any[], baseUrl: string): string {
+  const urls: string[] = [];
+  const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+  for (const page of pages) {
+    const options = page.options;
 
-    // Only include static pages or pages without parameters
     if (!options.schema?.params) {
       // Simple page without parameters
       const path = options.path || "";
-      const url = `${baseUrl.replace(/\/$/, "")}${path === "" ? "/" : path}`;
+      const url = `${normalizedBaseUrl}${path === "" ? "/" : path}`;
       urls.push(url);
     } else if (
       options.static &&
@@ -71,7 +112,7 @@ function generateSitemapFromAlepha(alepha: Alepha, baseUrl: string): string {
           options.path || "",
           entry.params || {},
         );
-        const url = `${baseUrl.replace(/\/$/, "")}${path}`;
+        const url = `${normalizedBaseUrl}${path}`;
         urls.push(url);
       }
     }

package/src/vite/tasks/index.ts

@@ -13,11 +13,9 @@
 export * from "./buildClient.ts";
 export * from "./buildServer.ts";
 export * from "./copyAssets.ts";
-export * from "./devServer.ts";
 export * from "./generateCloudflare.ts";
 export * from "./generateDocker.ts";
 export * from "./generateExternals.ts";
 export * from "./generateSitemap.ts";
 export * from "./generateVercel.ts";
 export * from "./prerenderPages.ts";
-export * from "./runAlepha.ts";

package/src/vite/tasks/prerenderPages.ts

@@ -1,6 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import type { Alepha } from "alepha";
-import { importAlepha } from "../helpers/importAlepha.ts";
 import {
   compressFile,
   type ViteCompressOptions,
@@ -8,9 +7,9 @@ import {
 
 export interface PrerenderPagesOptions {
   /**
-   * Entry point for the built Alepha application.
+   * Alepha instance to use for pre-rendering.
    */
-  entry: string;
+  alepha: Alepha;
 
   /**
    * Client dist directory for output files.
@@ -21,6 +20,14 @@ export interface PrerenderPagesOptions {
    * Optional compression options.
    */
   compress?: ViteCompressOptions | boolean;
+
+  /**
+   * Add Runner for logging (@see Alepha CLI)
+   */
+  run?: (opts: {
+    name: string;
+    handler: () => Promise<void>;
+  }) => Promise<string>;
 }
 
 export interface PrerenderPagesResult {
@@ -33,45 +40,63 @@ export interface PrerenderPagesResult {
 /**
  * Pre-render static pages defined in the Alepha application.
  *
- * This task loads the built Alepha application, queries all page
- * primitives with `static: true`, and generates static HTML files
- * for each page. Supports pages with parameterized routes via
- * `static.entries` configuration.
+ * Queries all page primitives with `static: true` and generates
+ * static HTML files for each page. Supports pages with parameterized
+ * routes via `static.entries` configuration.
  */
 export async function prerenderPages(
   opts: PrerenderPagesOptions,
 ): Promise<PrerenderPagesResult> {
-  const alepha = await importAlepha(opts.entry);
+  const alepha = opts.alepha;
+  const pages = getStaticPages(alepha);
 
-  const now = Date.now();
+  // Nothing to pre-render
+  if (pages.length === 0) {
+    return { count: 0 };
+  }
+
+  let result: PrerenderPagesResult = { count: 0 };
 
-  if (!alepha.isConfigured()) {
-    await alepha.events.emit("configure", alepha);
-    (alepha as any).configured = true;
+  const fn = async () => {
+    // TODO: running configure here is a temporary workaround
+    if (!alepha.isConfigured()) {
+      await alepha.events.emit("configure", alepha);
+    }
+    result = await prerenderFromAlepha(pages, opts.dist, opts.compress);
+  };
+
+  if (opts.run) {
+    await opts.run({
+      name: "pre-render pages",
+      handler: fn,
+    });
+  } else {
+    await fn();
   }
 
-  return await prerenderFromAlepha(alepha, opts.dist, opts.compress);
+  return result;
+}
+
+/**
+ * Get all static pages from the Alepha instance.
+ */
+function getStaticPages(alepha: Alepha): any[] {
+  const pages = alepha.primitives("page") as any[];
+  return pages.filter((page) => {
+    const options = page.options;
+    return options.static && !options.children;
+  });
 }
 
 async function prerenderFromAlepha(
-  alepha: Alepha,
+  pages: any[],
   dist: string,
   compress?: ViteCompressOptions | boolean,
 ): Promise<PrerenderPagesResult> {
   let count = 0;
-  const pages = alepha.primitives("page") as any[];
 
   for (const page of pages) {
     const options = page.options;
-
-    if (options.children) {
-      continue;
-    }
-
-    if (!options.static) {
-      continue;
-    }
-
     const config = typeof options.static === "object" ? options.static : {};
 
     if (!options.schema?.params) {

package/src/websocket/index.ts

@@ -58,17 +58,21 @@ export * from "./providers/NodeWebSocketServerProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * Provides real-time bidirectional communication using WebSockets.
+ * | type | quality | stability |
+ * |------|---------|-----------|
+ * | backend | rare | experimental |
  *
- * The WebSockets module enables building real-time applications using the `$websocket` primitive
- * on class properties. It provides automatic connection management, message routing, type-safe
- * message handling, and seamless integration with other Alepha modules.
+ * Real-time bidirectional communication.
  *
- * On the server side (Node.js), it uses the 'ws' library to create a WebSocket server.
- * On the client side (browser), it uses the native WebSocket API.
+ * **Features:**
+ * - WebSocket server definition
+ * - Named communication channels
+ * - Type-safe message handling
+ * - Connection lifecycle management
+ * - Room/channel grouping
+ * - Browser compatibility
  *
- * @see {@link $websocket}
- * @module alepha.websockets
+ * @module alepha.websocket
  */
 export const AlephaWebSocket = $module({
   name: "alepha.websocket",