alepha 0.15.1 → 0.15.3

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;
+      }
+    },
+  });
+}

package/src/react/router/providers/ReactServerProvider.spec.tsx

@@ -0,0 +1,316 @@
+import { test } from "vitest";
+
+// Simple mock for testing template functionality without full Alepha setup
+class MockReactServerProvider {
+  protected readonly env = { REACT_ROOT_ID: "root" };
+  protected readonly ROOT_DIV_REGEX = new RegExp(
+    `<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
+    "is",
+  );
+  protected preprocessedTemplate: any = null;
+
+  public preprocessTemplate(template: string) {
+    // Find the body close tag for script injection
+    const bodyCloseMatch = template.match(/<\/body>/i);
+    const bodyCloseIndex = bodyCloseMatch?.index ?? template.length;
+
+    const beforeScript = template.substring(0, bodyCloseIndex);
+    const afterScript = template.substring(bodyCloseIndex);
+
+    // Check if there's an existing root div
+    const rootDivMatch = beforeScript.match(this.ROOT_DIV_REGEX);
+
+    if (rootDivMatch) {
+      // Split around the existing root div content
+      const beforeDiv = beforeScript.substring(0, rootDivMatch.index!);
+      const afterDivStart = rootDivMatch.index! + rootDivMatch[0].length;
+      const afterDiv = beforeScript.substring(afterDivStart);
+
+      const beforeApp = `${beforeDiv}<div${rootDivMatch[1]} id="${this.env.REACT_ROOT_ID}"${rootDivMatch[2]}>`;
+      const afterApp = `</div>${afterDiv}`;
+
+      return { beforeApp, afterApp, beforeScript: "", afterScript };
+    }
+
+    // No existing root div, find body tag to inject new div
+    const bodyMatch = beforeScript.match(/<body([^>]*)>/i);
+    if (bodyMatch) {
+      const beforeBody = beforeScript.substring(
+        0,
+        bodyMatch.index! + bodyMatch[0].length,
+      );
+      const afterBody = beforeScript.substring(
+        bodyMatch.index! + bodyMatch[0].length,
+      );
+
+      const beforeApp = `${beforeBody}<div id="${this.env.REACT_ROOT_ID}">`;
+      const afterApp = `</div>${afterBody}`;
+
+      return { beforeApp, afterApp, beforeScript: "", afterScript };
+    }
+
+    // Fallback: no body tag found, just wrap everything
+    return {
+      beforeApp: `<div id="${this.env.REACT_ROOT_ID}">`,
+      afterApp: `</div>`,
+      beforeScript,
+      afterScript,
+    };
+  }
+
+  public fillTemplate(response: { html: string }, app: string, script: string) {
+    if (!this.preprocessedTemplate) {
+      // Fallback to old logic if preprocessing failed
+      this.preprocessedTemplate = this.preprocessTemplate(response.html);
+    }
+
+    // Pure concatenation - no regex replacements needed
+    response.html =
+      this.preprocessedTemplate.beforeApp +
+      app +
+      this.preprocessedTemplate.afterApp +
+      script +
+      this.preprocessedTemplate.afterScript;
+  }
+}
+
+const setup = (env?: any) => {
+  const provider = new MockReactServerProvider();
+  if (env?.REACT_ROOT_ID) {
+    (provider as any).env.REACT_ROOT_ID = env.REACT_ROOT_ID;
+    (provider as any).ROOT_DIV_REGEX = new RegExp(
+      `<div([^>]*)\\s+id=["']${env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
+      "is",
+    );
+  }
+  return { provider };
+};
+
+test("ReactServerProvider - preprocessTemplate with existing root div", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root">existing content</div>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+`);
+  expect(preprocessed.beforeScript).toBe("");
+  expect(preprocessed.afterScript).toBe(`</body>
+</html>`);
+});
+
+test("ReactServerProvider - preprocessTemplate without root div", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <h1>Welcome</h1>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body><div id="root">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+  <h1>Welcome</h1>
+`);
+  expect(preprocessed.beforeScript).toBe("");
+  expect(preprocessed.afterScript).toBe(`</body>
+</html>`);
+});
+
+test("ReactServerProvider - preprocessTemplate with custom root ID", async ({
+  expect,
+}) => {
+  const { provider } = setup({ REACT_ROOT_ID: "app" });
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="app">existing content</div>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="app">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+`);
+});
+
+test("ReactServerProvider - preprocessTemplate with root div with attributes", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<body>
+  <div class="container" id="root" data-test="true">existing content</div>
+</body>
+</html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(
+    `<!DOCTYPE html>
+<html>
+<body>
+  <div class="container" id="root" data-test="true">`,
+  );
+  expect(preprocessed.afterApp).toBe(`</div>
+`);
+});
+
+test("ReactServerProvider - preprocessTemplate fallback (no body tag)", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<html><div>content</div></html>`;
+
+  const preprocessed = provider.preprocessTemplate(template);
+
+  expect(preprocessed.beforeApp).toBe(`<div id="root">`);
+  expect(preprocessed.afterApp).toBe(`</div>`);
+  expect(preprocessed.beforeScript).toBe(`<html><div>content</div></html>`);
+  expect(preprocessed.afterScript).toBe(``);
+});
+
+test("ReactServerProvider - fillTemplate concatenation", async ({ expect }) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root">existing</div>
+</body>
+</html>`;
+
+  // Preprocess the template
+  const preprocessed = provider.preprocessTemplate(template);
+  (provider as any).preprocessedTemplate = preprocessed;
+
+  const response = { html: "" };
+  const app = "<h1>Hello World</h1>";
+  const script = '<script>window.__ssr={"test":true}</script>';
+
+  provider.fillTemplate(response, app, script);
+
+  const expected = `<!DOCTYPE html>
+<html>
+<head><title>Test</title></head>
+<body>
+  <div id="root"><h1>Hello World</h1></div>
+<script>window.__ssr={"test":true}</script></body>
+</html>`;
+
+  expect(response.html).toBe(expected);
+});
+
+test("ReactServerProvider - fillTemplate without preprocessed template (fallback)", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<body>
+  <div id="root">existing</div>
+</body>
+</html>`;
+
+  const response = { html: template };
+  const app = "<h1>Hello World</h1>";
+  const script = '<script>window.__ssr={"test":true}</script>';
+
+  // Don't set preprocessedTemplate to test fallback
+  (provider as any).preprocessedTemplate = null;
+
+  provider.fillTemplate(response, app, script);
+
+  const expected = `<!DOCTYPE html>
+<html>
+<body>
+  <div id="root"><h1>Hello World</h1></div>
+<script>window.__ssr={"test":true}</script></body>
+</html>`;
+
+  expect(response.html).toBe(expected);
+});
+
+test("ReactServerProvider - fillTemplate performance comparison", async ({
+  expect,
+}) => {
+  const { provider } = setup();
+
+  const template = `<!DOCTYPE html>
+<html>
+<head><title>Performance Test</title></head>
+<body>
+  <div id="root">existing content</div>
+  <script>console.log('existing');</script>
+</body>
+</html>`;
+
+  const app = "<div><h1>Hello World</h1><p>This is a test</p></div>";
+  const script = '<script>window.__ssr={"data":"value","count":42}</script>';
+
+  // Test with preprocessing (should be faster)
+  const preprocessed = provider.preprocessTemplate(template);
+  (provider as any).preprocessedTemplate = preprocessed;
+
+  const response1 = { html: "" };
+  const start1 = performance.now();
+  provider.fillTemplate(response1, app, script);
+  const time1 = performance.now() - start1;
+
+  // Test fallback without preprocessing (should work but potentially slower)
+  (provider as any).preprocessedTemplate = null;
+  const response2 = { html: template };
+  const start2 = performance.now();
+  provider.fillTemplate(response2, app, script);
+  const time2 = performance.now() - start2;
+
+  // Both should produce the same result
+  expect(response1.html).toBe(response2.html);
+
+  // The result should contain the app content
+  expect(response1.html).toContain("<h1>Hello World</h1>");
+  expect(response1.html).toContain(
+    '<script>window.__ssr={"data":"value","count":42}</script>',
+  );
+});