@alepha/react 0.14.2 → 0.14.4

package/src/router/providers/ReactServerProvider.ts

@@ -1,85 +1,56 @@
-import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { $atom, $env, $hook, $inject, $use, Alepha, AlephaError, type Static, t, } from "alepha";
+import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { type ServerHandler, ServerRouterProvider, ServerTimingProvider, } from "alepha/server";
 import { ServerLinksProvider } from "alepha/server/links";
 import { ServerStaticProvider } from "alepha/server/static";
-import { renderToString } from "react-dom/server";
+import { renderToReadableStream } from "react-dom/server";
+import { ServerHeadProvider } from "@alepha/react/head";
 import { Redirection } from "../errors/Redirection.ts";
 import { $page, type PagePrimitiveRenderOptions, type PagePrimitiveRenderResult, } from "../primitives/$page.ts";
-import type { ReactHydrationState } from "./ReactBrowserProvider.ts";
 import { type PageRoute, ReactPageProvider, type ReactRouterState, } from "./ReactPageProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-const envSchema = t.object({
-  REACT_SSR_ENABLED: t.optional(t.boolean()),
-  REACT_ROOT_ID: t.text({ default: "root" }), // TODO: move to ReactPageProvider.options?
-});
-
-declare module "alepha" {
-  interface Env extends Partial<Static<typeof envSchema>> {}
-  interface State {
-    "alepha.react.server.ssr"?: boolean;
-    "alepha.react.server.template"?: string;
-  }
-}
-
-/**
- * React server provider configuration atom
- */
-export const reactServerOptions = $atom({
-  name: "alepha.react.server.options",
-  schema: t.object({
-    publicDir: t.string(),
-    staticServer: t.object({
-      disabled: t.boolean(),
-      path: t.string({
-        description: "URL path where static files will be served.",
-      }),
-    }),
-  }),
-  default: {
-    publicDir: "public",
-    staticServer: {
-      disabled: false,
-      path: "/",
-    },
-  },
-});
-
-export type ReactServerProviderOptions = Static<
-  typeof reactServerOptions.schema
->;
-
-declare module "alepha" {
-  interface State {
-    [reactServerOptions.key]: ReactServerProviderOptions;
-  }
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
+import { ReactServerTemplateProvider } from "./ReactServerTemplateProvider.ts";
+import { SSRManifestProvider } from "./SSRManifestProvider.ts";
 
 /**
  * React server provider responsible for SSR and static file serving.
  *
- * Use `react-dom/server` under the hood.
+ * Coordinates between:
+ * - ReactPageProvider: Page routing and layer resolution
+ * - ReactServerTemplateProvider: HTML template parsing and streaming
+ * - ServerHeadProvider: Head content management
+ * - SSRManifestProvider: Module preload link collection
+ *
+ * Uses `react-dom/server` under the hood.
  */
 export class ReactServerProvider {
+  /**
+   * SSR response headers - pre-allocated to avoid object creation per request.
+   */
+  protected readonly SSR_HEADERS = {
+    "content-type": "text/html",
+    "cache-control": "no-store, no-cache, must-revalidate, proxy-revalidate",
+    pragma: "no-cache",
+    expires: "0",
+  } as const;
+
+  protected readonly fs = $inject(FileSystemProvider);
   protected readonly log = $logger();
   protected readonly alepha = $inject(Alepha);
   protected readonly env = $env(envSchema);
   protected readonly pageApi = $inject(ReactPageProvider);
+  protected readonly templateProvider = $inject(ReactServerTemplateProvider);
+  protected readonly serverHeadProvider = $inject(ServerHeadProvider);
   protected readonly serverStaticProvider = $inject(ServerStaticProvider);
   protected readonly serverRouterProvider = $inject(ServerRouterProvider);
   protected readonly serverTimingProvider = $inject(ServerTimingProvider);
+  protected readonly ssrManifestProvider = $inject(SSRManifestProvider);
 
-  public readonly ROOT_DIV_REGEX = new RegExp(
-    `<div([^>]*)\\s+id=["']${this.env.REACT_ROOT_ID}["']([^>]*)>(.*?)<\\/div>`,
-    "is",
-  );
-  protected preprocessedTemplate: PreprocessedTemplate | null = null;
+  /**
+   * Cached check for ServerLinksProvider - avoids has() lookup per request.
+   */
+  protected hasServerLinksProvider = false;
 
   protected readonly options = $use(reactServerOptions);
 
@@ -96,6 +67,10 @@ export class ReactServerProvider {
 
       this.alepha.store.set("alepha.react.server.ssr", ssrEnabled);
 
+      if (ssrEnabled) {
+        this.log.info("SSR streaming enabled");
+      }
+
       // development mode
       if (this.alepha.isViteDev()) {
         await this.configureVite(ssrEnabled);
@@ -107,7 +82,7 @@ export class ReactServerProvider {
 
       // non-serverless mode only -> serve static files
       if (!this.alepha.isServerless()) {
-        root = this.getPublicDirectory();
+        root = await this.getPublicDirectory();
         if (!root) {
           this.log.warn(
             "Missing static files, static file server will be disabled",
@@ -146,27 +121,39 @@ export class ReactServerProvider {
     },
   });
 
+  /**
+   * Get the current HTML template.
+   */
   public get template() {
     return (
       this.alepha.store.get("alepha.react.server.template") ??
-      "<!DOCTYPE html><html lang='en'><head></head><body></body></html>"
+      "<!DOCTYPE html><html lang='en'><head></head><body><div id='root'></div></body></html>"
     );
   }
 
+  /**
+   * Register all pages as server routes.
+   */
   protected async registerPages(templateLoader: TemplateLoader) {
-    // Preprocess template once
+    // Parse template once at startup
     const template = await templateLoader();
     if (template) {
-      this.preprocessedTemplate = this.preprocessTemplate(template);
+      this.templateProvider.parseTemplate(template);
     }
 
+    // Set up early head content (entry assets preloads)
+    this.setupEarlyHeadContent();
+
+    // Cache ServerLinksProvider check at startup
+    this.hasServerLinksProvider = this.alepha.has(ServerLinksProvider);
+
     for (const page of this.pageApi.getPages()) {
       if (page.component || page.lazy) {
         this.log.debug(`+ ${page.match} -> ${page.name}`);
 
         this.serverRouterProvider.createRoute({
           ...page,
-          schema: undefined, // schema is handled by the page primitive provider for now (shared by browser and server)
+          schema: undefined, // schema is handled by the page primitive provider
           method: "GET",
           path: page.match,
           handler: this.createHandler(page, templateLoader),
@@ -175,17 +162,63 @@ export class ReactServerProvider {
     }
   }
 
+  /**
+   * Set up early head content with entry assets.
+   *
+   * This content is sent immediately when streaming starts, before page loaders run,
+   * allowing the browser to start downloading entry.js and CSS files early.
+   *
+   * Uses <script type="module"> instead of <link rel="modulepreload"> for JS
+   * because the script needs to execute anyway - this way the browser starts
+   * downloading, parsing, AND will execute as soon as ready.
+   *
+   * Also strips these assets from the original template head to avoid duplicates.
+   */
+  protected setupEarlyHeadContent(): void {
+    const assets = this.ssrManifestProvider.getEntryAssets();
+    if (!assets) {
+      return;
+    }
+
+    const parts: string[] = [];
+
+    // Add CSS stylesheets (critical for rendering)
+    for (const css of assets.css) {
+      parts.push(`<link rel="stylesheet" href="${css}" crossorigin="">`);
+    }
+
+    // Add entry JS as script module (not just modulepreload)
+    // This starts download, parse, AND execution immediately
+    if (assets.js) {
+      parts.push(
+        `<script type="module" crossorigin="" src="${assets.js}"></script>`,
+      );
+    }
+
+    if (parts.length > 0) {
+      // Pass assets so they get stripped from original head content
+      this.templateProvider.setEarlyHeadContent(
+        parts.join("\n") + "\n",
+        assets,
+      );
+      this.log.debug("Early head content set", {
+        css: assets.css.length,
+        js: assets.js ? 1 : 0,
+      });
+    }
+  }
+
   /**
    * Get the public directory path where static files are located.
    */
-  protected getPublicDirectory(): string {
+  protected async getPublicDirectory(): Promise<string> {
     const maybe = [
       join(process.cwd(), `dist/${this.options.publicDir}`),
       join(process.cwd(), this.options.publicDir),
     ];
 
     for (const it of maybe) {
-      if (existsSync(it)) {
+      if (await this.fs.exists(it)) {
         return it;
       }
     }
@@ -208,7 +241,7 @@ export class ReactServerProvider {
   }
 
   /**
-   * Configure Vite for SSR.
+   * Configure Vite for SSR in development mode.
    */
   protected async configureVite(ssrEnabled: boolean) {
     if (!ssrEnabled) {
@@ -216,9 +249,9 @@ export class ReactServerProvider {
       return;
     }
 
-    this.log.info("SSR (dev) OK");
+    const url = `http://localhost:${this.alepha.env.SERVER_PORT ?? "5173"}`;
 
-    const url = `http://${process.env.SERVER_HOST}:${process.env.SERVER_PORT}`;
+    this.log.info("SSR (dev) OK", { url });
 
     await this.registerPages(() =>
       fetch(`${url}/index.html`)
@@ -228,95 +261,41 @@ export class ReactServerProvider {
   }
 
   /**
-   * For testing purposes, creates a render function that can be used.
+   * Create the request handler for a page route.
    */
-  public async render(
-    name: string,
-    options: PagePrimitiveRenderOptions = {},
-  ): Promise<PagePrimitiveRenderResult> {
-    const page = this.pageApi.page(name);
-    const url = new URL(this.pageApi.url(name, options));
-    const entry: Partial<ReactRouterState> = {
-      url,
-      params: options.params ?? {},
-      query: options.query ?? {},
-      onError: () => null,
-      layers: [],
-      meta: {},
-    };
-    const state = entry as ReactRouterState;
-
-    this.log.trace("Rendering", {
-      url,
-    });
-
-    await this.alepha.events.emit("react:server:render:begin", {
-      state,
-    });
-
-    const { redirect } = await this.pageApi.createLayers(
-      page,
-      state as ReactRouterState,
-    );
-
-    if (redirect) {
-      return { state, html: "", redirect };
-    }
-
-    if (!options.html) {
-      this.alepha.store.set("alepha.react.router.state", state);
-
-      return {
-        state,
-        html: renderToString(this.pageApi.root(state)),
-      };
-    }
-
-    const template = this.template ?? "";
-    const html = this.renderToHtml(template, state, options.hydration);
-
-    if (html instanceof Redirection) {
-      return { state, html: "", redirect };
-    }
-
-    const result = {
-      state,
-      html,
-    };
-
-    await this.alepha.events.emit("react:server:render:end", result);
-
-    return result;
-  }
-
   protected createHandler(
     route: PageRoute,
     templateLoader: TemplateLoader,
   ): ServerHandler {
     return async (serverRequest) => {
       const { url, reply, query, params } = serverRequest;
-      const template = await templateLoader();
-      if (!template) {
-        throw new AlephaError("Missing template for SSR rendering");
+
+      // Ensure template is parsed (handles dev mode where template may change)
+      if (!this.templateProvider.isReady()) {
+        const template = await templateLoader();
+        if (!template) {
+          throw new AlephaError("Missing template for SSR rendering");
+        }
+        this.templateProvider.parseTemplate(template);
+        this.setupEarlyHeadContent();
       }
 
-      this.log.trace("Rendering page", {
-        name: route.name,
-      });
+      this.log.trace("Rendering page", { name: route.name });
 
-      const entry: Partial<ReactRouterState> = {
+      // Initialize router state
+      const state: ReactRouterState = {
         url,
         params,
         query,
+        name: route.name,
         onError: () => null,
         layers: [],
+        meta: {},
+        head: {},
       };
 
-      const state = entry as ReactRouterState;
-
-      state.name = route.name;
-
-      if (this.alepha.has(ServerLinksProvider)) {
+      // Set up API links if available
+      if (this.hasServerLinksProvider) {
         this.alepha.store.set(
           "alepha.server.request.apiLinks",
           await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
@@ -326,13 +305,13 @@ export class ReactServerProvider {
         );
       }
 
-      let target: PageRoute | undefined = route; // TODO: move to PagePrimitiveProvider
+      // Check access permissions
+      let target: PageRoute | undefined = route;
       while (target) {
         if (route.can && !route.can()) {
           this.log.warn(
             `Access to page '${route.name}' is forbidden by can() check`,
-          )
-          // if the page is not accessible, return 403
+          );
           reply.status = 403;
           reply.headers["content-type"] = "text/plain";
           return "Forbidden";
@@ -340,220 +319,257 @@ export class ReactServerProvider {
         target = target.parent;
       }
 
-      // TODO: SSR strategies
-      // - only when googlebot
-      // - only child pages
-      // if (page.client) {
-      // 	// if the page is a client-only page, return 404
-      // 	reply.status = 200;
-      // 	reply.headers["content-type"] = "text/html";
-      // 	reply.body = template;
-      // 	return;
-      // }
-
       await this.alepha.events.emit("react:server:render:begin", {
         request: serverRequest,
         state,
       });
 
-      this.serverTimingProvider.beginTiming("createLayers");
-
-      const { redirect } = await this.pageApi.createLayers(route, state);
-
-      this.serverTimingProvider.endTiming("createLayers");
-
-      if (redirect) {
-        this.log.debug("Resolver resulted in redirection", {
-          redirect,
-        });
-        return reply.redirect(redirect);
-      }
+      // Apply SSR headers early
+      Object.assign(reply.headers, this.SSR_HEADERS);
 
-      reply.headers["content-type"] = "text/html";
-
-      // by default, disable caching for SSR responses
-      // some plugins may override this
-      reply.headers["cache-control"] =
-        "no-store, no-cache, must-revalidate, proxy-revalidate";
-      reply.headers.pragma = "no-cache";
-      reply.headers.expires = "0";
-
-      const html = this.renderToHtml(template, state);
-      if (html instanceof Redirection) {
-        reply.redirect(
-          typeof html.redirect === "string"
-            ? html.redirect
-            : this.pageApi.href(html.redirect),
-        );
-        this.log.debug("Rendering resulted in redirection", {
-          redirect: html.redirect,
-        });
-        return;
-      }
+      // Resolve global head for early streaming (htmlAttributes only)
+      const globalHead = this.serverHeadProvider.resolveGlobalHead();
 
-      this.log.trace("Page rendered to HTML successfully");
+      // Create optimized HTML stream with early head
+      const htmlStream = this.templateProvider.createEarlyHtmlStream(
+        globalHead,
+        async () => {
+          // === ASYNC WORK (runs while early head is being sent) ===
+          const result = await this.renderPage(route, state);
 
-      const event = {
-        request: serverRequest,
-        state,
-        html,
-      };
+          if (result.redirect) {
+            // Note: redirect happens after early head is sent, handled by stream
+            reply.redirect(result.redirect);
+            return null;
+          }
 
-      await this.alepha.events.emit("react:server:render:end", event);
+          return { state, reactStream: result.reactStream! };
+        },
+        {
+          hydration: true,
+          onError: (error) => {
+            if (error instanceof Redirection) {
+              this.log.debug("Streaming resulted in redirection", {
+                redirect: error.redirect,
+              });
+              // Can't do redirect after streaming started - already handled above
+            } else {
+              this.log.error("HTML stream error", error);
+            }
+          },
+        },
+      );
 
+      this.log.trace("Page streaming started (early head optimization)");
       route.onServerResponse?.(serverRequest);
-
-      this.log.trace("Page rendered", {
-        name: route.name,
-      });
-
-      return event.html;
+      reply.body = htmlStream;
     };
   }
 
-  public renderToHtml(
-    template: string,
+  // ---------------------------------------------------------------------------
+  // Core rendering logic - shared between SSR handler and static prerendering
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Core page rendering logic shared between SSR handler and static prerendering.
+   *
+   * Handles:
+   * - Layer resolution (loaders)
+   * - Redirect detection
+   * - Head content filling
+   * - Preload link collection
+   * - React stream rendering
+   *
+   * @param route - The page route to render
+   * @param state - The router state
+   * @returns Render result with redirect or React stream
+   */
+  protected async renderPage(
+    route: PageRoute,
     state: ReactRouterState,
-    hydration = true,
-  ): string | Redirection {
-    const element = this.pageApi.root(state);
+  ): Promise<{ redirect?: string; reactStream?: ReadableStream<Uint8Array> }> {
+    // Resolve page layers (loaders)
+    this.serverTimingProvider.beginTiming("createLayers");
+    const { redirect } = await this.pageApi.createLayers(route, state);
+    this.serverTimingProvider.endTiming("createLayers");
 
-    // attach react router state to the http request context
-    this.alepha.store.set("alepha.react.router.state", state);
+    if (redirect) {
+      this.log.debug("Resolver resulted in redirection", { redirect });
+      return { redirect };
+    }
 
-    this.serverTimingProvider.beginTiming("renderToString");
-    let app = "";
-    try {
-      app = renderToString(element);
-    } catch (error) {
-      this.log.error(
-        "renderToString has failed, fallback to error handler",
-        error,
-      );
-      const element = state.onError(error as Error, state);
-      if (element instanceof Redirection) {
-        // if the error is a redirection, return the redirection URL
-        return element;
-      }
+    // Fill head from route config
+    this.serverHeadProvider.fillHead(state);
 
-      app = renderToString(element);
-      this.log.debug("Error handled successfully with fallback");
+    // Collect and inject modulepreload links for page-specific chunks
+    const preloadLinks = this.ssrManifestProvider.collectPreloadLinks(route);
+    if (preloadLinks.length > 0) {
+      state.head ??= {};
+      state.head.link = [...(state.head.link ?? []), ...preloadLinks];
     }
-    this.serverTimingProvider.endTiming("renderToString");
 
-    const response = {
-      html: template,
-    };
+    // Render React to stream
+    this.serverTimingProvider.beginTiming("renderToStream");
 
-    if (hydration) {
-      const { request, context, ...store } =
-        this.alepha.context.als?.getStore() ?? {}; /// TODO: als must be protected, find a way to iterate on alepha.state
-
-      const hydrationData: ReactHydrationState = {
-        ...store,
-        // map react.router.state to the hydration state
-        "alepha.react.router.state": undefined,
-        layers: state.layers.map((it) => ({
-          ...it,
-          error: it.error
-            ? {
-                ...it.error,
-                name: it.error.name,
-                message: it.error.message,
-                stack: !this.alepha.isProduction() ? it.error.stack : undefined,
-              }
-            : undefined,
-          index: undefined,
-          path: undefined,
-          element: undefined,
-          route: undefined,
-        })),
-      };
+    const element = this.pageApi.root(state);
+    this.alepha.store.set("alepha.react.router.state", state);
 
-      // create hydration data
-      const script = `<script>window.__ssr=${JSON.stringify(hydrationData)}</script>`;
+    const reactStream = await renderToReadableStream(element, {
+      onError: (error: unknown) => {
+        if (error instanceof Redirection) {
+          this.log.warn("Redirect during streaming ignored", {
+            redirect: error.redirect,
+          });
+        } else {
+          this.log.error("Streaming render error", error);
+        }
+      },
+    });
 
-      // inject app into template
-      this.fillTemplate(response, app, script);
-    }
+    this.serverTimingProvider.endTiming("renderToStream");
 
-    return response.html;
+    return { reactStream };
   }
 
-  protected preprocessTemplate(template: string): PreprocessedTemplate {
-    // 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);
+  // ---------------------------------------------------------------------------
+  // Testing utilities - kept for backwards compatibility with tests
+  // ---------------------------------------------------------------------------
 
-    // Check if there's an existing root div
-    const rootDivMatch = beforeScript.match(this.ROOT_DIV_REGEX);
+  /**
+   * For testing purposes, renders a page to HTML string.
+   * Uses the same streaming code path as production, then collects to string.
+   *
+   * @param name - Page name to render
+   * @param options - Render options (params, query, html, hydration)
+   */
+  public async render(
+    name: string,
+    options: PagePrimitiveRenderOptions = {},
+  ): Promise<PagePrimitiveRenderResult> {
+    const page = this.pageApi.page(name);
+    const url = new URL(this.pageApi.url(name, options));
+    const state: ReactRouterState = {
+      url,
+      params: options.params ?? {},
+      query: options.query ?? {},
+      onError: () => null,
+      layers: [],
+      meta: {},
+      head: {},
+    };
 
-    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);
+    this.log.trace("Rendering", { url });
 
-      const beforeApp = `${beforeDiv}<div${rootDivMatch[1]} id="${this.env.REACT_ROOT_ID}"${rootDivMatch[2]}>`;
-      const afterApp = `</div>${afterDiv}`;
+    await this.alepha.events.emit("react:server:render:begin", { state });
 
-      return { beforeApp, afterApp, beforeScript: "", afterScript };
+    // Ensure template is parsed with early head content (entry.js, CSS)
+    if (!this.templateProvider.isReady()) {
+      this.templateProvider.parseTemplate(this.template);
+      this.setupEarlyHeadContent();
     }
 
-    // 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,
-      );
+    // Use shared rendering logic
+    const result = await this.renderPage(page, state);
 
-      const beforeApp = `${beforeBody}<div id="${this.env.REACT_ROOT_ID}">`;
-      const afterApp = `</div>${afterBody}`;
+    if (result.redirect) {
+      return { state, html: "", redirect: result.redirect };
+    }
+
+    const reactStream = result.reactStream!;
 
-      return { beforeApp, afterApp, beforeScript: "", afterScript };
+    // If full HTML page not requested, collect just the React content
+    if (!options.html) {
+      const html = await this.streamToString(reactStream);
+      return { state, html };
     }
 
-    // Fallback: no body tag found, just wrap everything
-    return {
-      beforeApp: `<div id="${this.env.REACT_ROOT_ID}">`,
-      afterApp: `</div>`,
-      beforeScript,
-      afterScript,
-    };
+    // Create full HTML stream and collect to string
+    const htmlStream = this.templateProvider.createHtmlStream(
+      reactStream,
+      state,
+      { hydration: options.hydration ?? true },
+    );
+
+    const html = await this.streamToString(htmlStream);
+
+    await this.alepha.events.emit("react:server:render:end", { state, html });
+
+    return { state, html };
   }
 
-  protected fillTemplate(
-    response: { html: string },
-    app: string,
-    script: string,
-  ) {
-    if (!this.preprocessedTemplate) {
-      // Fallback to old logic if preprocessing failed
-      this.preprocessedTemplate = this.preprocessTemplate(response.html);
+  /**
+   * Collect a ReadableStream into a string.
+   */
+  protected async streamToString(
+    stream: ReadableStream<Uint8Array>,
+  ): Promise<string> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    const chunks: string[] = [];
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(decoder.decode(value, { stream: true }));
+      }
+      chunks.push(decoder.decode()); // Flush remaining
+    } finally {
+      reader.releaseLock();
     }
 
-    // Pure concatenation - no regex replacements needed
-    response.html =
-      this.preprocessedTemplate.beforeApp +
-      app +
-      this.preprocessedTemplate.afterApp +
-      script +
-      this.preprocessedTemplate.afterScript;
+    return chunks.join("");
   }
 }
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 type TemplateLoader = () => Promise<string | undefined>;
 
-interface PreprocessedTemplate {
-  beforeApp: string;
-  afterApp: string;
-  beforeScript: string;
-  afterScript: string;
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const envSchema = t.object({
+  REACT_SSR_ENABLED: t.optional(t.boolean()),
+});
+
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+  interface State {
+    "alepha.react.server.ssr"?: boolean;
+    "alepha.react.server.template"?: string;
+  }
+}
+
+/**
+ * React server provider configuration atom
+ */
+export const reactServerOptions = $atom({
+  name: "alepha.react.server.options",
+  schema: t.object({
+    publicDir: t.string(),
+    staticServer: t.object({
+      disabled: t.boolean(),
+      path: t.string({
+        description: "URL path where static files will be served.",
+      }),
+    }),
+  }),
+  default: {
+    publicDir: "public",
+    staticServer: {
+      disabled: false,
+      path: "/",
+    },
+  },
+});
+
+export type ReactServerProviderOptions = Static<
+  typeof reactServerOptions.schema
+>;
+
+declare module "alepha" {
+  interface State {
+    [reactServerOptions.key]: ReactServerProviderOptions;
+  }
 }