@alepha/react 0.11.5 → 0.11.7

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@alepha/react",
 	"description": "Build server-side rendered (SSR) or single-page React applications.",
-	"version": "0.11.5",
+	"version": "0.11.7",
 	"type": "module",
 	"engines": {
 		"node": ">=22.0.0"
@@ -17,25 +17,25 @@
 		"src"
 	],
 	"dependencies": {
-		"@alepha/core": "0.11.5",
-		"@alepha/datetime": "0.11.5",
-		"@alepha/logger": "0.11.5",
-		"@alepha/router": "0.11.5",
-		"@alepha/server": "0.11.5",
-		"@alepha/server-cache": "0.11.5",
-		"@alepha/server-links": "0.11.5",
-		"@alepha/server-static": "0.11.5"
+		"@alepha/core": "0.11.7",
+		"@alepha/datetime": "0.11.7",
+		"@alepha/logger": "0.11.7",
+		"@alepha/router": "0.11.7",
+		"@alepha/server": "0.11.7",
+		"@alepha/server-cache": "0.11.7",
+		"@alepha/server-links": "0.11.7",
+		"@alepha/server-static": "0.11.7"
 	},
 	"devDependencies": {
-		"@alepha/testing": "0.11.5",
-		"@biomejs/biome": "^2.3.3",
-		"@types/react": "^19.2.2",
-		"@types/react-dom": "^19.2.2",
+		"@alepha/testing": "0.11.7",
+		"@biomejs/biome": "^2.3.5",
+		"@types/react": "^19.2.4",
+		"@types/react-dom": "^19.2.3",
 		"react": "^19.2.0",
 		"react-dom": "^19.2.0",
-		"tsdown": "^0.16.0",
+		"tsdown": "^0.16.4",
 		"typescript": "^5.9.3",
-		"vitest": "^4.0.6"
+		"vitest": "^4.0.8"
 	},
 	"peerDependencies": {
 		"react": "*",

package/src/hooks/useAction.ts

@@ -297,7 +297,7 @@ export function useAction<Args extends any[], Result = void>(
     if (options.runOnInit) {
       handler(...([] as any));
     }
-  }, []);
+  }, deps);
 
   // Run action periodically if runEvery is specified
   useEffect(() => {

package/src/hooks/useRouterState.ts

@@ -3,7 +3,7 @@ import type { ReactRouterState } from "../providers/ReactPageProvider.ts";
 import { useStore } from "./useStore.ts";
 
 export const useRouterState = (): ReactRouterState => {
-  const [state] = useStore("react.router.state");
+  const [state] = useStore("alepha.react.router.state");
   if (!state) {
     throw new AlephaError("Missing react router state");
   }

package/src/hooks/useStore.ts

@@ -1,29 +1,37 @@
-import type { State } from "@alepha/core";
+import type { State, Static, TAtomObject } from "@alepha/core";
+import { Atom } from "@alepha/core";
 import { useEffect, useMemo, useState } from "react";
 import { useAlepha } from "./useAlepha.ts";
 
 /**
  * Hook to access and mutate the Alepha state.
  */
-export const useStore = <Key extends keyof State>(
-  key: Key,
+function useStore<T extends TAtomObject>(
+  target: Atom<T>,
+  defaultValue?: Static<T>,
+): UseStoreReturn<Static<T>>;
+function useStore<Key extends keyof State>(
+  target: Key,
   defaultValue?: State[Key],
-): [State[Key], (value: State[Key]) => void] => {
+): UseStoreReturn<State[Key]>;
+function useStore(target: any, defaultValue?: any): any {
   const alepha = useAlepha();
 
   useMemo(() => {
-    if (defaultValue != null && alepha.state.get(key) == null) {
-      alepha.state.set(key, defaultValue);
+    if (defaultValue != null && alepha.state.get(target) == null) {
+      alepha.state.set(target, defaultValue);
     }
   }, [defaultValue]);
 
-  const [state, setState] = useState(alepha.state.get(key));
+  const [state, setState] = useState(alepha.state.get(target));
 
   useEffect(() => {
     if (!alepha.isBrowser()) {
       return;
     }
 
+    const key = target instanceof Atom ? target.key : target;
+
     return alepha.events.on("state:mutate", (ev) => {
       if (ev.key === key) {
         setState(ev.value);
@@ -33,8 +41,12 @@ export const useStore = <Key extends keyof State>(
 
   return [
     state,
-    (value: State[Key]) => {
-      alepha.state.set(key, value);
+    (value: any) => {
+      alepha.state.set(target, value);
     },
   ] as const;
-};
+}
+
+export type UseStoreReturn<T> = [T, (value: T) => void];
+
+export { useStore };

package/src/index.ts

@@ -26,7 +26,7 @@ export * from "./providers/ReactServerProvider.ts";
 
 declare module "@alepha/core" {
   interface State {
-    "react.router.state"?: ReactRouterState;
+    "alepha.react.router.state"?: ReactRouterState;
   }
 
   interface Hooks {

package/src/providers/ReactBrowserProvider.ts

@@ -1,7 +1,9 @@
 import {
+  $atom,
   $env,
   $hook,
   $inject,
+  $use,
   Alepha,
   type State,
   type Static,
@@ -17,6 +19,8 @@ import type {
   TransitionOptions,
 } from "./ReactPageProvider.ts";
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 const envSchema = t.object({
   REACT_ROOT_ID: t.text({ default: "root" }),
 });
@@ -25,10 +29,31 @@ declare module "@alepha/core" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
 
-export interface ReactBrowserRendererOptions {
-  scrollRestoration?: "top" | "manual";
+/**
+ * React browser renderer configuration atom
+ */
+export const reactBrowserOptions = $atom({
+  name: "alepha.react.browser.options",
+  schema: t.object({
+    scrollRestoration: t.enum(["top", "manual"]),
+  }),
+  default: {
+    scrollRestoration: "top" as const,
+  },
+});
+
+export type ReactBrowserRendererOptions = Static<
+  typeof reactBrowserOptions.schema
+>;
+
+declare module "@alepha/core" {
+  interface State {
+    [reactBrowserOptions.key]: ReactBrowserRendererOptions;
+  }
 }
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 export class ReactBrowserProvider {
   protected readonly env = $env(envSchema);
   protected readonly log = $logger();
@@ -37,9 +62,7 @@ export class ReactBrowserProvider {
   protected readonly router = $inject(ReactBrowserRouterProvider);
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
 
-  public options: ReactBrowserRendererOptions = {
-    scrollRestoration: "top",
-  };
+  protected readonly options = $use(reactBrowserOptions);
 
   protected getRootElement() {
     const root = this.document.getElementById(this.env.REACT_ROOT_ID);
@@ -61,7 +84,7 @@ export class ReactBrowserProvider {
   };
 
   public get state(): ReactRouterState {
-    return this.alepha.state.get("react.router.state")!;
+    return this.alepha.state.get("alepha.react.router.state")!;
   }
 
   /**

package/src/providers/ReactBrowserRouterProvider.ts

@@ -63,7 +63,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
       type: "transition",
     });
     await this.alepha.events.emit("react:transition:begin", {
-      previous: this.alepha.state.get("react.router.state")!,
+      previous: this.alepha.state.get("alepha.react.router.state")!,
       state,
     });
 
@@ -135,7 +135,7 @@ export class ReactBrowserRouterProvider extends RouterProvider<BrowserRoute> {
       }
     }
 
-    this.alepha.state.set("react.router.state", state);
+    this.alepha.state.set("alepha.react.router.state", state);
 
     await this.alepha.events.emit("react:action:end", {
       type: "transition",

package/src/providers/ReactServerProvider.ts

@@ -1,12 +1,13 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import {
+  $atom,
   $env,
   $hook,
   $inject,
+  $use,
   Alepha,
   AlephaError,
-  type Configurable,
   type Static,
   t,
 } from "@alepha/core";
@@ -18,10 +19,7 @@ import {
   ServerTimingProvider,
 } from "@alepha/server";
 import { ServerLinksProvider } from "@alepha/server-links";
-import {
-  type ServeDescriptorOptions,
-  ServerStaticProvider,
-} from "@alepha/server-static";
+import { ServerStaticProvider } from "@alepha/server-static";
 import { renderToString } from "react-dom/server";
 import {
   $page,
@@ -36,9 +34,9 @@ import {
   type ReactRouterState,
 } from "./ReactPageProvider.ts";
 
+// ---------------------------------------------------------------------------------------------------------------------
+
 const envSchema = t.object({
-  REACT_SERVER_DIST: t.text({ default: "public" }),
-  REACT_SERVER_PREFIX: t.text({ default: "" }),
   REACT_SSR_ENABLED: t.optional(t.boolean()),
   REACT_ROOT_ID: t.text({ default: "root" }), // TODO: move to ReactPageProvider.options?
   REACT_SERVER_TEMPLATE: t.optional(
@@ -51,19 +49,46 @@ const envSchema = t.object({
 declare module "@alepha/core" {
   interface Env extends Partial<Static<typeof envSchema>> {}
   interface State {
-    "react.server.ssr"?: boolean;
+    "alepha.react.server.ssr"?: boolean;
   }
 }
 
-export interface ReactServerProviderOptions {
-  /**
-   * Override default options for the static file server.
-   * > Static file server is only created in non-serverless production mode.
-   */
-  static?: Partial<Omit<ServeDescriptorOptions, "root">>;
+/**
+ * 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/core" {
+  interface State {
+    [reactServerOptions.key]: ReactServerProviderOptions;
+  }
 }
 
-export class ReactServerProvider implements Configurable {
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class ReactServerProvider {
   protected readonly log = $logger();
   protected readonly alepha = $inject(Alepha);
   protected readonly env = $env(envSchema);
@@ -79,7 +104,7 @@ export class ReactServerProvider implements Configurable {
   );
   protected preprocessedTemplate: PreprocessedTemplate | null = null;
 
-  public options: ReactServerProviderOptions = {};
+  protected readonly options = $use(reactServerOptions);
 
   /**
    * Configure the React server provider.
@@ -92,7 +117,7 @@ export class ReactServerProvider implements Configurable {
       const ssrEnabled =
         pages.length > 0 && this.env.REACT_SSR_ENABLED !== false;
 
-      this.alepha.state.set("react.server.ssr", ssrEnabled);
+      this.alepha.state.set("alepha.react.server.ssr", ssrEnabled);
 
       // development mode
       if (this.alepha.isViteDev()) {
@@ -180,8 +205,8 @@ export class ReactServerProvider implements Configurable {
    */
   protected getPublicDirectory(): string {
     const maybe = [
-      join(process.cwd(), `dist/${this.env.REACT_SERVER_DIST}`),
-      join(process.cwd(), this.env.REACT_SERVER_DIST),
+      join(process.cwd(), `dist/${this.options.publicDir}`),
+      join(process.cwd(), this.options.publicDir),
     ];
 
     for (const it of maybe) {
@@ -199,12 +224,11 @@ export class ReactServerProvider implements Configurable {
   protected async configureStaticServer(root: string) {
     await this.serverStaticProvider.createStaticServer({
       root,
-      path: this.env.REACT_SERVER_PREFIX,
       cacheControl: {
         maxAge: 3600,
         immutable: true,
       },
-      ...this.options.static,
+      ...this.options.staticServer,
     });
   }
 
@@ -217,7 +241,7 @@ export class ReactServerProvider implements Configurable {
       return;
     }
 
-    this.log.info("SSR (vite) OK");
+    this.log.info("SSR (dev) OK");
 
     const url = `http://${process.env.SERVER_HOST}:${process.env.SERVER_PORT}`;
 
@@ -265,7 +289,7 @@ export class ReactServerProvider implements Configurable {
     }
 
     if (!options.html) {
-      this.alepha.state.set("react.router.state", state);
+      this.alepha.state.set("alepha.react.router.state", state);
 
       return {
         state,
@@ -317,7 +341,7 @@ export class ReactServerProvider implements Configurable {
 
       if (this.alepha.has(ServerLinksProvider)) {
         this.alepha.state.set(
-          "api",
+          "alepha.server.request.apiLinks",
           await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
             user: (serverRequest as any).user, // TODO: fix type
             authorization: serverRequest.headers.authorization,
@@ -407,7 +431,7 @@ export class ReactServerProvider implements Configurable {
     const element = this.pageApi.root(state);
 
     // attach react router state to the http request context
-    this.alepha.state.set("react.router.state", state);
+    this.alepha.state.set("alepha.react.router.state", state);
 
     this.serverTimingProvider.beginTiming("renderToString");
     let app = "";
@@ -440,7 +464,7 @@ export class ReactServerProvider implements Configurable {
       const hydrationData: ReactHydrationState = {
         ...store,
         // map react.router.state to the hydration state
-        "react.router.state": undefined,
+        "alepha.react.router.state": undefined,
         layers: state.layers.map((it) => ({
           ...it,
           error: it.error

package/src/services/ReactRouter.ts

@@ -15,7 +15,7 @@ export class ReactRouter<T extends object> {
   protected readonly pageApi = $inject(ReactPageProvider);
 
   public get state(): ReactRouterState {
-    return this.alepha.state.get("react.router.state")!;
+    return this.alepha.state.get("alepha.react.router.state")!;
   }
 
   public get pages() {