alepha 0.15.2 → 0.15.4

package/src/react/router/primitives/$page.browser.spec.tsx

@@ -34,7 +34,7 @@ describe("$page browser tests", () => {
     const router = alepha.inject(ReactRouter);
 
     await act(async () => {
-      await router.go("/");
+      await router.push("/");
     });
 
     await waitFor(() => {
@@ -64,7 +64,7 @@ describe("$page browser tests", () => {
 
     // Navigate to home
     await act(async () => {
-      await router.go("/");
+      await router.push("/");
     });
 
     await waitFor(() => {
@@ -73,7 +73,7 @@ describe("$page browser tests", () => {
 
     // Navigate to about
     await act(async () => {
-      await router.go("/about");
+      await router.push("/about");
     });
 
     await waitFor(() => {
@@ -119,7 +119,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/user/123");
+        await router.push("/user/123");
       });
 
       await waitFor(() => {
@@ -153,7 +153,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/async");
+        await router.push("/async");
       });
 
       await waitFor(
@@ -204,7 +204,7 @@ describe("$page browser tests", () => {
 
       // Try to access protected - should redirect to login
       await act(async () => {
-        await router.go("/protected");
+        await router.push("/protected");
       });
 
       await waitFor(() => {
@@ -215,7 +215,7 @@ describe("$page browser tests", () => {
       isAuthenticated = true;
 
       await act(async () => {
-        await router.go("/protected");
+        await router.push("/protected");
       });
 
       await waitFor(() => {
@@ -248,7 +248,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/error");
+        await router.push("/error");
       });
 
       await waitFor(() => {
@@ -294,7 +294,7 @@ describe("$page browser tests", () => {
 
       // Navigate to home - should show layout and home
       await act(async () => {
-        await router.go("/");
+        await router.push("/");
       });
 
       await waitFor(() => {
@@ -306,7 +306,7 @@ describe("$page browser tests", () => {
 
       // Navigate to about - layout should persist
       await act(async () => {
-        await router.go("/about");
+        await router.push("/about");
       });
 
       await waitFor(() => {
@@ -348,7 +348,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/page");
+        await router.push("/page");
       });
 
       await waitFor(() => {
@@ -404,7 +404,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/section/page");
+        await router.push("/section/page");
       });
 
       await waitFor(() => {
@@ -441,7 +441,7 @@ describe("$page browser tests", () => {
 
       // Navigate to home
       await act(async () => {
-        await router.go("/");
+        await router.push("/");
       });
 
       await waitFor(() => {
@@ -452,7 +452,7 @@ describe("$page browser tests", () => {
 
       // Navigate away from home to about
       await act(async () => {
-        await router.go("/about");
+        await router.push("/about");
       });
 
       await waitFor(() => {
@@ -490,7 +490,7 @@ describe("$page browser tests", () => {
 
       // Navigate to home first
       await act(async () => {
-        await router.go("/");
+        await router.push("/");
       });
 
       await waitFor(() => {
@@ -503,7 +503,7 @@ describe("$page browser tests", () => {
 
       // Navigate to about - onEnter should be called
       await act(async () => {
-        await router.go("/about");
+        await router.push("/about");
       });
 
       await waitFor(() => {
@@ -533,7 +533,7 @@ describe("$page browser tests", () => {
 
       // Navigate to home - onEnter should be called
       await act(async () => {
-        await router.go("/");
+        await router.push("/");
       });
 
       await waitFor(() => {
@@ -582,7 +582,7 @@ describe("$page browser tests", () => {
 
       // Navigate to child1
       await act(async () => {
-        await router.go("/child1");
+        await router.push("/child1");
       });
 
       await waitFor(() => {
@@ -595,7 +595,7 @@ describe("$page browser tests", () => {
 
       // Navigate to child2 - parent onEnter should NOT be called again
       await act(async () => {
-        await router.go("/child2");
+        await router.push("/child2");
       });
 
       await waitFor(() => {
@@ -633,7 +633,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/user/abc123");
+        await router.push("/user/abc123");
       });
 
       await waitFor(() => {
@@ -678,7 +678,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/search?q=typescript&page=2");
+        await router.push("/search?q=typescript&page=2");
       });
 
       await waitFor(() => {
@@ -728,7 +728,7 @@ describe("$page browser tests", () => {
 
       // Navigate with query params
       await act(async () => {
-        await router.go("/search?q=alepha&page=5");
+        await router.push("/search?q=alepha&page=5");
       });
 
       await waitFor(() => {
@@ -783,7 +783,7 @@ describe("$page browser tests", () => {
       const router = alepha.inject(ReactRouter);
 
       await act(async () => {
-        await router.go("/users/john/posts?sort=popular&limit=20");
+        await router.push("/users/john/posts?sort=popular&limit=20");
       });
 
       await waitFor(() => {
@@ -835,7 +835,7 @@ describe("$page browser tests", () => {
 
       // Navigate without query params - should use defaults
       await act(async () => {
-        await router.go("/search");
+        await router.push("/search");
       });
 
       await waitFor(() => {

package/src/react/router/primitives/$page.spec.tsx

@@ -521,38 +521,6 @@ describe("$page primitive tests", () => {
     expect(functionRendered.html).toBe("Function animation");
   });
 
-  test("$page - match method (not implemented)", ({ expect }) => {
-    class App {
-      page = $page({
-        path: "/test",
-        component: () => "test",
-      });
-    }
-
-    const app = alepha.inject(App);
-
-    expect(app.page.match("/test")).toBe(false);
-    expect(app.page.match("/other")).toBe(false);
-  });
-
-  test("$page - pathname method", ({ expect }) => {
-    class App {
-      withPath = $page({
-        path: "/test/:id",
-        component: () => "test",
-      });
-
-      withoutPath = $page({
-        component: () => "test",
-      });
-    }
-
-    const app = alepha.inject(App);
-
-    expect(app.withPath.pathname({})).toBe("/test/:id");
-    expect(app.withoutPath.pathname({})).toBe("");
-  });
-
   test("$page - complex schema with nested objects", async ({ expect }) => {
     class App {
       complex = $page({

package/src/react/router/primitives/$page.ts

@@ -368,10 +368,7 @@ export interface PagePrimitiveOptions<
   [PAGE_PRELOAD_KEY]?: string;
 }
 
-export type ErrorHandler = (
-  error: Error,
-  state: ReactRouterState,
-) => ReactNode | Redirection | undefined;
+// ---------------------------------------------------------------------------------------------------------------------
 
 export class PagePrimitive<
   TConfig extends PageConfigSchema = PageConfigSchema,
@@ -413,22 +410,17 @@ export class PagePrimitive<
   }> {
     return this.reactPageService.fetch(this.options.path || "", options);
   }
-
-  public match(url: string): boolean {
-    // TODO: Implement a way to match the URL against the pathname
-    return false;
-  }
-
-  public pathname(config: any) {
-    // TODO: Implement a way to generate the pathname based on the config
-    return this.options.path || "";
-  }
 }
 
 $page[KIND] = PagePrimitive;
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export type ErrorHandler = (
+  error: Error,
+  state: ReactRouterState,
+) => ReactNode | Redirection | undefined;
+
 export interface PageConfigSchema {
   query?: TSchema;
   params?: TSchema;

package/src/react/router/providers/ReactBrowserProvider.ts

@@ -12,14 +12,14 @@ import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { BrowserHeadProvider } from "alepha/react/head";
 import { LinkProvider } from "alepha/server/links";
-import type { RouterGoOptions } from "../services/ReactRouter.ts";
+import type { RouterPushOptions } from "../services/ReactRouter.ts";
 import { ReactBrowserRouterProvider } from "./ReactBrowserRouterProvider.ts";
 import type {
   PreviousLayerData,
   ReactRouterState,
 } from "./ReactPageProvider.ts";
 
-export type { RouterGoOptions } from "../services/ReactRouter.ts";
+export type { RouterPushOptions } from "../services/ReactRouter.ts";
 
 /**
  * React browser renderer configuration atom
@@ -158,7 +158,10 @@ export class ReactBrowserProvider {
     await this.render({ previous });
   }
 
-  public async go(url: string, options: RouterGoOptions = {}): Promise<void> {
+  public async push(
+    url: string,
+    options: RouterPushOptions = {},
+  ): Promise<void> {
     this.log.trace(`Going to ${url}`, {
       url,
       options,

package/src/react/router/providers/ReactPageProvider.ts

@@ -101,7 +101,7 @@ export class ReactPageProvider {
   ) {
     const page = this.page(name);
     if (!page) {
-      throw new Error(`Page ${name} not found`);
+      throw new AlephaError(`Page ${name} not found`);
     }
 
     let url = page.path ?? "";

package/src/react/router/providers/ReactPreloadProvider.spec.ts

@@ -0,0 +1,142 @@
+import { Alepha } from "alepha";
+import { HttpClient, ServerProvider } from "alepha/server";
+import { describe, it } from "vitest";
+import { ssrManifestAtom } from "../atoms/ssrManifestAtom.ts";
+import { $page } from "../index.ts";
+
+describe("ReactPreloadProvider", () => {
+  class App {
+    home = $page({
+      path: "/",
+      component: () => "Hello World",
+    });
+  }
+
+  it("should add Link header with entry assets to HTML responses", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create({
+      env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+    }).with(App);
+
+    // Set up mock SSR manifest with entry assets
+    alepha.store.set(ssrManifestAtom, {
+      client: {
+        "src/entry.tsx": {
+          file: "assets/entry.abc123.js",
+          isEntry: true,
+          css: ["assets/style.def456.css"],
+        },
+      },
+    });
+
+    await alepha.start();
+
+    const server = alepha.inject(ServerProvider);
+    const http = alepha.inject(HttpClient);
+
+    const response = await http.fetch(`${server.hostname}/`);
+
+    // Check that the Link header is present
+    const linkHeader = response.headers.get("link");
+    expect(linkHeader).toBeTruthy();
+    expect(linkHeader).toContain(
+      "</assets/style.def456.css>; rel=preload; as=style",
+    );
+    expect(linkHeader).toContain(
+      "</assets/entry.abc123.js>; rel=modulepreload",
+    );
+
+    await alepha.stop();
+  });
+
+  it("should not add Link header when no SSR manifest is available", async ({
+    expect,
+  }) => {
+    const alepha = Alepha.create({
+      env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+    }).with(App);
+
+    // No SSR manifest set
+
+    await alepha.start();
+
+    const server = alepha.inject(ServerProvider);
+    const http = alepha.inject(HttpClient);
+
+    const response = await http.fetch(`${server.hostname}/`);
+
+    // Link header should not be present (or empty)
+    const linkHeader = response.headers.get("link");
+    expect(linkHeader).toBeNull();
+
+    await alepha.stop();
+  });
+
+  it("should handle base path in manifest", async ({ expect }) => {
+    const alepha = Alepha.create({
+      env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+    }).with(App);
+
+    // Set up mock SSR manifest with base path
+    alepha.store.set(ssrManifestAtom, {
+      base: "/app",
+      client: {
+        "src/entry.tsx": {
+          file: "assets/entry.abc123.js",
+          isEntry: true,
+          css: ["assets/style.def456.css"],
+        },
+      },
+    });
+
+    await alepha.start();
+
+    const server = alepha.inject(ServerProvider);
+    const http = alepha.inject(HttpClient);
+
+    const response = await http.fetch(`${server.hostname}/`);
+
+    // Check that the Link header includes base path
+    const linkHeader = response.headers.get("link");
+    expect(linkHeader).toBeTruthy();
+    expect(linkHeader).toContain(
+      "</app/assets/style.def456.css>; rel=preload; as=style",
+    );
+    expect(linkHeader).toContain(
+      "</app/assets/entry.abc123.js>; rel=modulepreload",
+    );
+
+    await alepha.stop();
+  });
+
+  it("should handle entry with only JS (no CSS)", async ({ expect }) => {
+    const alepha = Alepha.create({
+      env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+    }).with(App);
+
+    // Set up mock SSR manifest with only JS entry
+    alepha.store.set(ssrManifestAtom, {
+      client: {
+        "src/entry.tsx": {
+          file: "assets/entry.abc123.js",
+          isEntry: true,
+        },
+      },
+    });
+
+    await alepha.start();
+
+    const server = alepha.inject(ServerProvider);
+    const http = alepha.inject(HttpClient);
+
+    const response = await http.fetch(`${server.hostname}/`);
+
+    // Check that the Link header contains only JS modulepreload
+    const linkHeader = response.headers.get("link");
+    expect(linkHeader).toBeTruthy();
+    expect(linkHeader).toBe("</assets/entry.abc123.js>; rel=modulepreload");
+
+    await alepha.stop();
+  });
+});

package/src/react/router/providers/ReactPreloadProvider.ts

@@ -0,0 +1,85 @@
+import { $hook, $inject, Alepha } from "alepha";
+import { SSRManifestProvider } from "./SSRManifestProvider.ts";
+
+/**
+ * Adds HTTP Link headers for preloading entry assets.
+ *
+ * Benefits:
+ * - Early Hints (103): Servers can send preload hints before the full response
+ * - CDN optimization: Many CDNs use Link headers to optimize asset delivery
+ * - Browser prefetching: Browsers can start fetching resources earlier
+ *
+ * The Link header is computed once at first request and cached for reuse.
+ */
+export class ReactPreloadProvider {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly ssrManifest = $inject(SSRManifestProvider);
+
+  /**
+   * Cached Link header value - computed once, reused for all requests.
+   */
+  protected cachedLinkHeader: string | null | undefined;
+
+  /**
+   * Build the Link header string from entry assets.
+   *
+   * Format: <url>; rel=preload; as=type, <url>; rel=modulepreload
+   *
+   * @returns Link header string or null if no assets
+   */
+  protected buildLinkHeader(): string | null {
+    const assets = this.ssrManifest.getEntryAssets();
+    if (!assets) return null;
+
+    const links: string[] = [];
+
+    // CSS - preload as style
+    for (const css of assets.css) {
+      links.push(`<${css}>; rel=preload; as=style`);
+    }
+
+    // JS - modulepreload for ES modules
+    if (assets.js) {
+      links.push(`<${assets.js}>; rel=modulepreload`);
+    }
+
+    return links.length > 0 ? links.join(", ") : null;
+  }
+
+  /**
+   * Get the cached Link header, computing it on first access.
+   */
+  protected getLinkHeader(): string | null {
+    if (this.cachedLinkHeader === undefined) {
+      this.cachedLinkHeader = this.buildLinkHeader();
+    }
+    return this.cachedLinkHeader;
+  }
+
+  /**
+   * Add Link header to HTML responses for asset preloading.
+   */
+  protected readonly onResponse = $hook({
+    on: "server:onResponse",
+    priority: "first",
+    handler: ({ response }) => {
+      // Only add to HTML responses (SSR pages)
+      const contentType = response.headers["content-type"];
+      if (!contentType || !contentType.includes("text/html")) {
+        return;
+      }
+
+      const linkHeader = this.getLinkHeader();
+      if (!linkHeader) {
+        return;
+      }
+
+      // Append to existing Link header if present
+      if (response.headers.link) {
+        response.headers.link = `${response.headers.link}, ${linkHeader}`;
+      } else {
+        response.headers.link = linkHeader;
+      }
+    },
+  });
+}