react-bun-ssr 0.3.2 → 0.4.0

package/README.md

@@ -38,11 +38,6 @@ Prerequisites:
 - Bun `>= 1.3.10`
 - `rbssr` available on PATH in the workflow you use to start a new app
 
-Try in browser:
-
-- StackBlitz (primary): https://stackblitz.com/github/react-formation/react-bun-ssr/tree/main/examples/sandbox-starter
-- CodeSandbox (fallback): https://codesandbox.io/s/github/react-formation/react-bun-ssr/tree/main/examples/sandbox-starter
-
 Minimal setup:
 
 ```bash
@@ -119,6 +114,43 @@ Read more:
 - https://react-bun-ssr.dev/docs/routing/middleware
 - https://react-bun-ssr.dev/docs/data/loaders
 
+### Actions with React `useActionState`
+
+Page mutations use React 19 form actions (`useActionState`) with an explicit route stub:
+
+```tsx
+// app/routes/login.tsx
+import { useActionState } from "react";
+import { createRouteAction } from "react-bun-ssr/route";
+
+type LoginState = { error?: string };
+export const action = createRouteAction<LoginState>();
+
+export default function LoginPage() {
+  const [state, formAction, pending] = useActionState(action, {});
+  return (
+    <form action={formAction}>
+      {state.error ? <p>{state.error}</p> : null}
+      <button disabled={pending}>Sign in</button>
+    </form>
+  );
+}
+```
+
+```tsx
+// app/routes/login.server.tsx
+import { redirect } from "react-bun-ssr";
+import type { Action } from "react-bun-ssr/route";
+
+export const action: Action = async (ctx) => {
+  const email = String(ctx.formData?.get("email") ?? "").trim();
+  if (!email) return { error: "Email is required" };
+  return redirect("/dashboard");
+};
+```
+
+`createRouteAction` is the preferred pattern. `useRouteAction` remains available for backward compatibility.
+
 ### Rendering model
 
 SSR is the default model. HTML responses stream, deferred loader data is supported, and soft client transitions are handled through `Link` and `useRouter`. The docs site in this repository uses the same routing, rendering, markdown, and transition model that framework users get.

package/framework/cli/dev-runtime.ts

@@ -26,13 +26,20 @@ function isConfigFileName(fileName: string): boolean {
 }
 
 function isTopLevelAppRuntimeFile(relativePath: string): boolean {
-  return /^root\.(tsx|jsx|ts|js)$/.test(relativePath) || /^middleware\.(tsx|jsx|ts|js)$/.test(relativePath);
+  return /^root(?:\.server)?\.(tsx|jsx|ts|js)$/.test(relativePath)
+    || /^middleware(?:\.server)?\.(tsx|jsx|ts|js)$/.test(relativePath);
 }
 
 function isMarkdownRouteFile(relativePath: string): boolean {
   return /^routes\/.+\.md$/.test(relativePath);
 }
 
+function isServerOnlyRuntimeFile(relativePath: string): boolean {
+  return /^root\.server\.(tsx|jsx|ts|js)$/.test(relativePath)
+    || /^middleware\.server\.(tsx|jsx|ts|js)$/.test(relativePath)
+    || /^routes\/.+\.server\.(tsx|jsx|ts|js)$/.test(relativePath);
+}
+
 function isStructuralAppPath(relativePath: string): boolean {
   return relativePath === "routes"
     || relativePath.startsWith("routes/")
@@ -265,11 +272,21 @@ export async function runHotDevChild(options: {
       return;
     }
 
+    if (eventType === "rename" && isServerOnlyRuntimeFile(relativePath)) {
+      publishReload("server-runtime");
+      return;
+    }
+
     if (eventType === "rename" && isStructuralAppPath(relativePath)) {
       scheduleStructuralSync();
       return;
     }
 
+    if (eventType === "change" && isServerOnlyRuntimeFile(relativePath)) {
+      publishReload("server-runtime");
+      return;
+    }
+
     if (eventType !== "change" || !isMarkdownRouteFile(relativePath)) {
       return;
     }

package/framework/runtime/action-stub.ts

@@ -0,0 +1,26 @@
+export type RouteActionStateHandler<TState = unknown> = (
+  previousState: TState,
+  formData: FormData,
+) => Promise<TState>;
+
+const ROUTE_ACTION_STUB_MARKER = Symbol.for("react-bun-ssr.route-action-stub");
+
+export function markRouteActionStub<TState>(
+  handler: RouteActionStateHandler<TState>,
+): RouteActionStateHandler<TState> {
+  Object.defineProperty(handler, ROUTE_ACTION_STUB_MARKER, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return handler;
+}
+
+export function isRouteActionStub(value: unknown): value is RouteActionStateHandler<unknown> {
+  if (typeof value !== "function") {
+    return false;
+  }
+
+  return (value as unknown as Record<PropertyKey, unknown>)[ROUTE_ACTION_STUB_MARKER] === true;
+}

package/framework/runtime/client-runtime.tsx

@@ -374,7 +374,7 @@ function findPendingTransitionForEvent(event: NavigateEventLike): PendingNavigat
 }
 
 function reviveDeferredPayload(payload: RenderPayload): RenderPayload {
-  const sourceData = payload.data;
+  const sourceData = payload.loaderData;
   if (!sourceData || Array.isArray(sourceData) || typeof sourceData !== "object") {
     return payload;
   }
@@ -394,7 +394,7 @@ function reviveDeferredPayload(payload: RenderPayload): RenderPayload {
 
   return {
     ...payload,
-    data: revivedData,
+    loaderData: revivedData,
   };
 }
 
@@ -713,7 +713,7 @@ async function navigateToInternal(
           matchedModules,
           {
             routeId: matched.route.id,
-            data: null,
+            loaderData: null,
             params: matched.params,
             url: toUrl.toString(),
           },

package/framework/runtime/helpers.ts

@@ -1,5 +1,6 @@
-import type { FrameworkConfig, RedirectResult } from "./types";
+import type { FrameworkConfig, RedirectResult, RequestContext } from "./types";
 import { defer as deferValue } from "./deferred";
+import { routeError } from "./route-errors";
 
 export function json(data: unknown, init: ResponseInit = {}): Response {
   const headers = new Headers(init.headers);
@@ -30,6 +31,79 @@ export function defineConfig(config: FrameworkConfig): FrameworkConfig {
 
 export const defer = deferValue;
 
+function toNormalizedFallback(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "/";
+  }
+  if (trimmed.startsWith("/")) {
+    return trimmed.startsWith("//") ? "/" : trimmed;
+  }
+  if (trimmed.startsWith("?") || trimmed.startsWith("#")) {
+    return `/${trimmed}`;
+  }
+  if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(trimmed)) {
+    return "/";
+  }
+  return `/${trimmed.replace(/^\/+/, "")}`;
+}
+
+export function sanitizeRedirectTarget(value: string | null | undefined, fallback = "/"): string {
+  const normalizedFallback = toNormalizedFallback(fallback);
+  if (typeof value !== "string") {
+    return normalizedFallback;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return normalizedFallback;
+  }
+
+  if (trimmed.startsWith("//") || trimmed.startsWith("\\\\")) {
+    return normalizedFallback;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed, "http://rbssr.local");
+  } catch {
+    return normalizedFallback;
+  }
+
+  if (parsed.origin !== "http://rbssr.local") {
+    return normalizedFallback;
+  }
+
+  const normalizedTarget = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  if (!normalizedTarget.startsWith("/")) {
+    return normalizedFallback;
+  }
+
+  return normalizedTarget;
+}
+
+export function assertSameOriginAction(ctx: Pick<RequestContext, "request" | "url">): void {
+  if (ctx.request.method.toUpperCase() === "GET" || ctx.request.method.toUpperCase() === "HEAD") {
+    return;
+  }
+
+  const originHeader = ctx.request.headers.get("origin");
+  if (!originHeader) {
+    return;
+  }
+
+  let origin: URL;
+  try {
+    origin = new URL(originHeader);
+  } catch {
+    throw routeError(403, { message: "Invalid Origin header." });
+  }
+
+  if (origin.origin !== ctx.url.origin) {
+    throw routeError(403, { message: "Cross-origin form submissions are not allowed." });
+  }
+}
+
 export function isRedirectResult(value: unknown): value is RedirectResult {
   return Boolean(
     value &&

package/framework/runtime/index.ts

@@ -1,29 +1,59 @@
-export type {
-  Action,
-  ActionContext,
-  ActionResult,
-  ApiRouteModule,
-  BuildManifest,
-  BuildRouteAsset,
-  DeferredLoaderResult,
-  DeferredToken,
-  FrameworkConfig,
-  Loader,
-  LoaderContext,
-  LoaderResult,
-  Middleware,
-  Params,
-  RedirectResult,
-  ResponseHeaderRule,
-  RequestContext,
-  RouteCatchContext,
-  RouteErrorContext,
-  RouteErrorResponse,
-  RouteModule,
+import type {
+  Action as RuntimeAction,
+  ActionContext as RuntimeActionContext,
+  ActionResult as RuntimeActionResult,
+  ApiRouteModule as RuntimeApiRouteModule,
+  BuildManifest as RuntimeBuildManifest,
+  BuildRouteAsset as RuntimeBuildRouteAsset,
+  DeferredLoaderResult as RuntimeDeferredLoaderResult,
+  DeferredToken as RuntimeDeferredToken,
+  FrameworkConfig as RuntimeFrameworkConfig,
+  Loader as RuntimeLoader,
+  LoaderContext as RuntimeLoaderContext,
+  LoaderResult as RuntimeLoaderResult,
+  Middleware as RuntimeMiddleware,
+  Params as RuntimeParams,
+  RedirectResult as RuntimeRedirectResult,
+  RequestContext as RuntimeRequestContext,
+  ResponseContext as RuntimeResponseContext,
+  ResponseCookies as RuntimeResponseCookies,
+  ResponseCookieOptions as RuntimeResponseCookieOptions,
+  ResponseHeaderRule as RuntimeResponseHeaderRule,
+  RouteCatchContext as RuntimeRouteCatchContext,
+  RouteErrorContext as RuntimeRouteErrorContext,
+  RouteErrorResponse as RuntimeRouteErrorResponse,
+  RouteModule as RuntimeRouteModule,
 } from "./types";
 
+export interface AppRouteLocals extends Record<string, unknown> {}
+
+export type Action = RuntimeAction<AppRouteLocals>;
+export type ActionContext = RuntimeActionContext<AppRouteLocals>;
+export type ActionResult = RuntimeActionResult;
+export type ApiRouteModule = RuntimeApiRouteModule;
+export type BuildManifest = RuntimeBuildManifest;
+export type BuildRouteAsset = RuntimeBuildRouteAsset;
+export type DeferredLoaderResult = RuntimeDeferredLoaderResult;
+export type DeferredToken = RuntimeDeferredToken;
+export type FrameworkConfig = RuntimeFrameworkConfig;
+export type Loader = RuntimeLoader<AppRouteLocals>;
+export type LoaderContext = RuntimeLoaderContext<AppRouteLocals>;
+export type LoaderResult = RuntimeLoaderResult;
+export type Middleware = RuntimeMiddleware<AppRouteLocals>;
+export type Params = RuntimeParams;
+export type RedirectResult = RuntimeRedirectResult;
+export type RequestContext = RuntimeRequestContext<AppRouteLocals>;
+export type ResponseContext = RuntimeResponseContext;
+export type ResponseCookies = RuntimeResponseCookies;
+export type ResponseCookieOptions = RuntimeResponseCookieOptions;
+export type ResponseHeaderRule = RuntimeResponseHeaderRule;
+export type RouteCatchContext = RuntimeRouteCatchContext;
+export type RouteErrorContext = RuntimeRouteErrorContext;
+export type RouteErrorResponse = RuntimeRouteErrorResponse;
+export type RouteModule = RuntimeRouteModule;
+
 export { createServer, startHttpServer } from "./server";
-export { defer, json, redirect, defineConfig } from "./helpers";
+export { assertSameOriginAction, defer, defineConfig, json, redirect, sanitizeRedirectTarget } from "./helpers";
 export { isRouteErrorResponse, notFound, routeError } from "./route-errors";
 export { Link, type LinkProps } from "./link";
 export { useRouter, type Router, type RouterNavigateInfo, type RouterNavigateListener, type RouterNavigateOptions } from "./router";

package/framework/runtime/module-loader.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { isRouteActionStub } from './action-stub';
 import { ensureDir, existsPath } from './io';
 import type {
   ApiRouteModule,
@@ -30,8 +31,19 @@ export interface RouteModuleLoadOptions {
   serverBytecode?: boolean;
   devSourceImports?: boolean;
   nodeEnv?: "development" | "production";
+  companionFilePath?: string | null;
 }
 
+const ROUTE_SERVER_EXPORT_KEYS = new Set([
+  "loader",
+  "action",
+  "middleware",
+  "head",
+  "meta",
+  "onError",
+  "onCatch",
+]);
+
 export function createServerModuleCacheKey(options: {
   absoluteFilePath: string;
   cacheBustKey?: string;
@@ -88,6 +100,46 @@ function normalizeLoadOptions(
   return options ?? {};
 }
 
+export function toServerCompanionPath(filePath: string): string {
+  const extension = path.extname(filePath);
+  if (!extension) {
+    return `${filePath}.server`;
+  }
+  return `${filePath.slice(0, -extension.length)}.server${extension}`;
+}
+
+async function resolveServerCompanionFilePath(
+  filePath: string,
+  options: RouteModuleLoadOptions,
+): Promise<string | null> {
+  if (options.companionFilePath === null) {
+    return null;
+  }
+
+  if (typeof options.companionFilePath === "string") {
+    return options.companionFilePath;
+  }
+
+  const companionFilePath = toServerCompanionPath(filePath);
+  if (await existsPath(companionFilePath)) {
+    return companionFilePath;
+  }
+  return null;
+}
+
+async function loadRawModuleRecord(
+  filePath: string,
+  options: RouteModuleLoadOptions,
+): Promise<Record<string, unknown>> {
+  const modulePath = options.devSourceImports
+    ? path.resolve(filePath)
+    : await buildServerModule(filePath, options);
+  return unwrapModuleNamespace(await importModule<Record<string, unknown>>(
+    modulePath,
+    options.cacheBustKey,
+  ));
+}
+
 function toRouteModule(filePath: string, moduleValue: unknown): RouteModule {
   const rawValue = moduleValue as Record<string, unknown>;
   const value = unwrapModuleNamespace(rawValue) as Partial<RouteModule>;
@@ -108,14 +160,103 @@ function toRouteModule(filePath: string, moduleValue: unknown): RouteModule {
   } as RouteModule;
 }
 
+function toRouteServerCompanionExports(
+  filePath: string,
+  companionFilePath: string,
+  moduleValue: Record<string, unknown>,
+): Partial<RouteModule> {
+  const exportKeys = Object.keys(moduleValue).filter(key => key !== "__esModule");
+
+  if (exportKeys.includes("default")) {
+    throw new Error(
+      `Route companion module ${companionFilePath} cannot export default. ` +
+        `Move UI exports back to ${filePath}.`,
+    );
+  }
+
+  const unsupportedExports = exportKeys.filter(key => !ROUTE_SERVER_EXPORT_KEYS.has(key));
+  if (unsupportedExports.length > 0) {
+    throw new Error(
+      `Route companion module ${companionFilePath} has unsupported exports: ${unsupportedExports.join(", ")}. ` +
+        `Allowed exports: ${[...ROUTE_SERVER_EXPORT_KEYS].join(", ")}.`,
+    );
+  }
+
+  const companionExports: Partial<RouteModule> = {};
+  for (const key of exportKeys) {
+    (companionExports as Record<string, unknown>)[key] = moduleValue[key];
+  }
+  return companionExports;
+}
+
+function mergeRouteModuleWithCompanion(options: {
+  filePath: string;
+  companionFilePath: string;
+  routeModule: RouteModule;
+  companionExports: Partial<RouteModule>;
+}): RouteModule {
+  for (const key of ROUTE_SERVER_EXPORT_KEYS) {
+    if (options.companionExports[key as keyof RouteModule] === undefined) {
+      continue;
+    }
+
+    if (
+      key === "action"
+      && isRouteActionStub(options.routeModule.action)
+    ) {
+      continue;
+    }
+
+    if (options.routeModule[key as keyof RouteModule] !== undefined) {
+      throw new Error(
+        `Duplicate server export "${key}" found in both ${options.filePath} and ${options.companionFilePath}. ` +
+          `Keep "${key}" in only one file.`,
+      );
+    }
+  }
+
+  return {
+    ...options.routeModule,
+    ...options.companionExports,
+  };
+}
+
+function stripRouteActionStub(routeModule: RouteModule): RouteModule {
+  if (!isRouteActionStub(routeModule.action)) {
+    return routeModule;
+  }
+
+  const { action: _stubAction, ...rest } = routeModule;
+  return rest as RouteModule;
+}
+
 function unwrapModuleNamespace(moduleValue: Record<string, unknown>): Record<string, unknown> {
   if (
-    moduleValue
-    && typeof moduleValue.default === "object"
-    && moduleValue.default !== null
-    && "default" in (moduleValue.default as Record<string, unknown>)
+    !moduleValue
+    || typeof moduleValue.default !== "object"
+    || moduleValue.default === null
+  ) {
+    return moduleValue;
+  }
+
+  const defaultNamespace = moduleValue.default as Record<string, unknown>;
+
+  if ("default" in defaultNamespace) {
+    return defaultNamespace;
+  }
+
+  const namedExportKeys = Object.keys(moduleValue).filter(key => {
+    return key !== "default" && key !== "__esModule";
+  });
+
+  if (
+    namedExportKeys.length > 0
+    && namedExportKeys.every(key => {
+      return Object.prototype.hasOwnProperty.call(defaultNamespace, key)
+        && defaultNamespace[key] === moduleValue[key];
+    })
   ) {
-    return moduleValue.default as Record<string, unknown>;
+    return defaultNamespace;
   }
 
   return moduleValue;
@@ -243,20 +384,29 @@ export async function loadRouteModule(
   options: RouteModuleLoadOptions = {},
 ): Promise<RouteModule> {
   const normalizedOptions = normalizeLoadOptions(options);
-  const modulePath = normalizedOptions.devSourceImports
-    ? path.resolve(filePath)
-    : await buildServerModule(filePath, normalizedOptions);
-  const moduleValue = await importModule<unknown>(
-    modulePath,
-    normalizedOptions.cacheBustKey,
-  );
-  return toRouteModule(filePath, moduleValue);
+  const baseModuleValue = await loadRawModuleRecord(filePath, normalizedOptions);
+  const routeModule = toRouteModule(filePath, baseModuleValue);
+  const companionFilePath = await resolveServerCompanionFilePath(filePath, normalizedOptions);
+  if (!companionFilePath) {
+    return stripRouteActionStub(routeModule);
+  }
+
+  const companionModuleValue = await loadRawModuleRecord(companionFilePath, normalizedOptions);
+  const companionExports = toRouteServerCompanionExports(filePath, companionFilePath, companionModuleValue);
+  const mergedRouteModule = mergeRouteModuleWithCompanion({
+    filePath,
+    companionFilePath,
+    routeModule,
+    companionExports,
+  });
+  return stripRouteActionStub(mergedRouteModule);
 }
 
 export async function loadRouteModules(options: {
   rootFilePath: string;
   layoutFiles: string[];
   routeFilePath: string;
+  routeServerFilePath?: string;
   cacheBustKey?: string;
   serverBytecode?: boolean;
   devSourceImports?: boolean;
@@ -273,7 +423,10 @@ export async function loadRouteModules(options: {
         loadRouteModule(layoutFilePath, moduleOptions),
       ),
     ),
-    loadRouteModule(options.routeFilePath, moduleOptions),
+    loadRouteModule(options.routeFilePath, {
+      ...moduleOptions,
+      companionFilePath: options.routeServerFilePath,
+    }),
   ]);
 
   return {
@@ -301,22 +454,42 @@ function normalizeMiddlewareExport(value: unknown): Middleware[] {
   return [];
 }
 
+async function resolveGlobalMiddlewarePath(middlewareFilePath: string): Promise<string | null> {
+  const basePath = path.resolve(middlewareFilePath);
+  const serverPath = toServerCompanionPath(basePath);
+  const [baseExists, serverExists] = await Promise.all([
+    existsPath(basePath),
+    existsPath(serverPath),
+  ]);
+
+  if (baseExists && serverExists) {
+    throw new Error(
+      `Global middleware file collision: both ${basePath} and ${serverPath} exist. ` +
+        "Use only one of these files.",
+    );
+  }
+
+  if (serverExists) {
+    return serverPath;
+  }
+  if (baseExists) {
+    return basePath;
+  }
+
+  return null;
+}
+
 export async function loadGlobalMiddleware(
   middlewareFilePath: string,
   options: string | RouteModuleLoadOptions = {},
 ): Promise<Middleware[]> {
-  if (!(await existsPath(middlewareFilePath))) {
+  const resolvedMiddlewarePath = await resolveGlobalMiddlewarePath(middlewareFilePath);
+  if (!resolvedMiddlewarePath) {
     return [];
   }
 
   const normalizedOptions = normalizeLoadOptions(options);
-  const modulePath = normalizedOptions.devSourceImports
-    ? path.resolve(middlewareFilePath)
-    : await buildServerModule(middlewareFilePath, normalizedOptions);
-  const raw = unwrapModuleNamespace(await importModule<Record<string, unknown>>(
-    modulePath,
-    normalizedOptions.cacheBustKey,
-  ));
+  const raw = await loadRawModuleRecord(resolvedMiddlewarePath, normalizedOptions);
 
   return [
     ...normalizeMiddlewareExport(raw.default),
@@ -331,13 +504,7 @@ export async function loadNestedMiddleware(
   const normalizedOptions = normalizeLoadOptions(options);
   const rawModules = await Promise.all(
     middlewareFilePaths.map(async (middlewareFilePath) => {
-      const modulePath = normalizedOptions.devSourceImports
-        ? path.resolve(middlewareFilePath)
-        : await buildServerModule(middlewareFilePath, normalizedOptions);
-      return unwrapModuleNamespace(await importModule<Record<string, unknown>>(
-        modulePath,
-        normalizedOptions.cacheBustKey,
-      ));
+      return loadRawModuleRecord(middlewareFilePath, normalizedOptions);
     }),
   );
 
@@ -358,10 +525,5 @@ export async function loadApiRouteModule(
   options: string | RouteModuleLoadOptions = {},
 ): Promise<ApiRouteModule> {
   const normalizedOptions = normalizeLoadOptions(options);
-  const modulePath = normalizedOptions.devSourceImports
-    ? path.resolve(filePath)
-    : await buildServerModule(filePath, normalizedOptions);
-  return unwrapModuleNamespace(
-    await importModule<Record<string, unknown>>(modulePath, normalizedOptions.cacheBustKey),
-  ) as ApiRouteModule;
+  return await loadRawModuleRecord(filePath, normalizedOptions) as ApiRouteModule;
 }

package/framework/runtime/render.tsx

@@ -155,7 +155,7 @@ function moduleHeadToElements(moduleValue: RouteModule, payload: RenderPayload,
   const tags: ReactNode[] = [];
 
   const context = {
-    data: payload.data,
+    data: payload.loaderData,
     params: payload.params,
     url: new URL(payload.url),
     error: payload.error,