react-bun-ssr 0.3.1 → 0.4.0

package/README.md

@@ -1,10 +1,17 @@
 # react-bun-ssr
 
+[![npm version](https://img.shields.io/npm/v/react-bun-ssr)](https://www.npmjs.com/package/react-bun-ssr)
+[![CI](https://github.com/react-formation/react-bun-ssr/actions/workflows/ci.yml/badge.svg)](https://github.com/react-formation/react-bun-ssr/actions/workflows/ci.yml)
+
 `react-bun-ssr` is a Bun-native SSR React framework with file-based routing, loaders, actions, middleware, streaming, soft navigation, and first-class markdown routes.
 
+> **Stability: Experimental (early alpha).**
+> Expect breaking changes across minor releases while core APIs and ergonomics are still being shaped.
+
 - Documentation: https://react-bun-ssr.dev/docs
 - API reference: https://react-bun-ssr.dev/docs/api/overview
 - Blog: https://react-bun-ssr.dev/blog
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
 - Repository: https://github.com/react-formation/react-bun-ssr
 
 ## Why react-bun-ssr?
@@ -107,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.
@@ -152,6 +196,7 @@ This repository contains both the framework and the official docs site built wit
 ```bash
 git clone git@github.com:react-formation/react-bun-ssr.git
 cd react-bun-ssr
+bun link
 bun install
 bun run docs:dev
 ```
@@ -189,20 +234,3 @@ Contributions should keep framework behavior, docs, tests, and generated artifac
 - The release workflow derives the published package version from the Git tag and rewrites `package.json` in the release job before publishing.
 - npm publishing uses trusted publishing with GitHub OIDC instead of an `NPM_TOKEN`.
 - npm package settings must have a trusted publisher configured for `react-formation / react-bun-ssr / release.yml`.
-
-## Deploying
-
-Fly.io deployment support is already documented and used by this project.
-
-Happy path:
-
-```bash
-fly auth login
-fly deploy
-```
-
-Full deployment docs:
-
-- https://react-bun-ssr.dev/docs/deployment/bun-deployment
-- https://react-bun-ssr.dev/docs/deployment/configuration
-- https://react-bun-ssr.dev/docs/deployment/troubleshooting

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/")
@@ -43,6 +50,10 @@ function toAbsoluteAppPath(appDir: string, relativePath: string): string {
   return path.join(appDir, relativePath);
 }
 
+function toNormalizedWatchPath(fileName?: string | Buffer | null): string {
+  return typeof fileName === "string" ? normalizeSlashes(fileName) : "";
+}
+
 interface DevHotData {
   bunServer?: Bun.Server<undefined>;
   reloadToken?: number;
@@ -88,9 +99,11 @@ export async function runHotDevChild(options: {
   let nextClientBuildReason: DevReloadReason | null = null;
   let stopping = false;
 
-  const watchers: FSWatcher[] = [];
   let structuralSyncTimer: ReturnType<typeof setTimeout> | undefined;
   let structuralSyncQueue: Promise<void> = Promise.resolve();
+  let routesWatcher: FSWatcher | null = null;
+  let appWatcher: FSWatcher | null = null;
+  let configWatcher: FSWatcher | null = null;
 
   const publishReload = (reason: DevReloadReason): void => {
     reloadToken += 1;
@@ -253,21 +266,27 @@ export async function runHotDevChild(options: {
     process.exit(RBSSR_DEV_RESTART_EXIT_CODE);
   };
 
-  const handleAppEvent = (eventType: string, fileName?: string | Buffer | null): void => {
-    const relativePath = typeof fileName === "string"
-      ? normalizeSlashes(fileName)
-      : "";
-
+  const handleAppEvent = (eventType: string, relativePath: string): void => {
     if (!relativePath) {
       scheduleStructuralSync();
       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;
     }
@@ -289,10 +308,29 @@ export async function runHotDevChild(options: {
     });
   };
 
-  const addWatcher = (watcher: FSWatcher | null): void => {
-    if (watcher) {
-      watchers.push(watcher);
+  const ensureRoutesWatcher = async (): Promise<void> => {
+    if (routesWatcher || !(await existsPath(resolved.routesDir))) {
+      return;
+    }
+
+    try {
+      routesWatcher = watch(resolved.routesDir, { recursive: true }, (eventType, fileName) => {
+        const nestedPath = toNormalizedWatchPath(fileName);
+        const relativePath = nestedPath ? `routes/${nestedPath}` : "routes";
+        handleAppEvent(eventType, relativePath);
+      });
+    } catch {
+      log(`recursive route watching unavailable for ${resolved.routesDir}; route topology updates may require a restart`);
+    }
+  };
+
+  const refreshRoutesWatcher = async (): Promise<void> => {
+    if (routesWatcher) {
+      routesWatcher.close();
+      routesWatcher = null;
     }
+
+    await ensureRoutesWatcher();
   };
 
   const cleanup = async (options: {
@@ -303,9 +341,12 @@ export async function runHotDevChild(options: {
       structuralSyncTimer = undefined;
     }
 
-    for (const watcher of watchers.splice(0, watchers.length)) {
-      watcher.close();
-    }
+    routesWatcher?.close();
+    routesWatcher = null;
+    appWatcher?.close();
+    appWatcher = null;
+    configWatcher?.close();
+    configWatcher = null;
 
     if (clientWatch) {
       await clientWatch.stop();
@@ -318,31 +359,38 @@ export async function runHotDevChild(options: {
     }
   };
 
+  await refreshRoutesWatcher();
+
   try {
-    addWatcher(
-      watch(resolved.appDir, { recursive: true }, (eventType, fileName) => {
-        handleAppEvent(eventType, fileName);
-      }),
-    );
+    appWatcher = watch(resolved.appDir, (eventType, fileName) => {
+      const relativePath = toNormalizedWatchPath(fileName);
+      if (relativePath === "routes" && eventType === "rename") {
+        void refreshRoutesWatcher();
+      }
+
+      handleAppEvent(eventType, relativePath);
+    });
   } catch {
-    log(`recursive file watching unavailable for ${resolved.appDir}; dev route topology updates may require a restart`);
+    log(`top-level app watching unavailable for ${resolved.appDir}; route topology updates may require a restart`);
   }
 
   try {
-    addWatcher(
-      watch(options.cwd, (eventType, fileName) => {
-        if (typeof fileName !== "string" || !isConfigFileName(fileName)) {
-          return;
-        }
-        if (eventType === "rename" || eventType === "change") {
-          void restartForConfigChange();
-        }
-      }),
-    );
+    configWatcher = watch(options.cwd, (eventType, fileName) => {
+      const configFileName = toNormalizedWatchPath(fileName);
+      if (!configFileName || !isConfigFileName(configFileName)) {
+        return;
+      }
+      if (eventType === "rename" || eventType === "change") {
+        void restartForConfigChange();
+      }
+    });
   } catch {
     log(`config file watching unavailable for ${options.cwd}; config changes may require a manual restart`);
   }
 
+  await enqueueStructuralSync("bootstrap");
+  await refreshRoutesWatcher();
+
   if (import.meta.hot) {
     import.meta.hot.dispose(async (data: DevHotData) => {
       data.bunServer = bunServer;
@@ -352,8 +400,6 @@ export async function runHotDevChild(options: {
     });
   }
 
-  await enqueueStructuralSync("bootstrap");
-
   if (hotData.bunServer && bunServer) {
     publishReload("server-runtime");
   }

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

@@ -17,11 +17,10 @@ import {
   type NavigationHistoryMode,
 } from "./navigation-api";
 import {
-  RBSSR_HEAD_MARKER_END_ATTR,
-  RBSSR_HEAD_MARKER_START_ATTR,
   RBSSR_PAYLOAD_SCRIPT_ID,
   RBSSR_ROUTER_SCRIPT_ID,
 } from "./runtime-constants";
+import { replaceManagedHead } from "./head-reconcile";
 import {
   createCatchAppTree,
   createErrorAppTree,
@@ -375,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;
   }
@@ -395,7 +394,7 @@ function reviveDeferredPayload(payload: RenderPayload): RenderPayload {
 
   return {
     ...payload,
-    data: revivedData,
+    loaderData: revivedData,
   };
 }
 
@@ -569,220 +568,6 @@ function createFallbackNotFoundRoute(rootModule: RouteModule): RouteModule {
   };
 }
 
-function nodeSignature(node: Node): string {
-  if (node.nodeType === Node.TEXT_NODE) {
-    return `text:${node.textContent ?? ""}`;
-  }
-
-  if (node.nodeType === Node.COMMENT_NODE) {
-    return `comment:${node.textContent ?? ""}`;
-  }
-
-  if (node.nodeType !== Node.ELEMENT_NODE) {
-    return `node:${node.nodeType}`;
-  }
-
-  const element = node as Element;
-  const attrs = Array.from(element.attributes)
-    .map(attribute => `${attribute.name}=${attribute.value}`)
-    .sort((a, b) => a.localeCompare(b))
-    .join("|");
-
-  return `element:${element.tagName.toLowerCase()}:${attrs}:${element.innerHTML}`;
-}
-
-function isIgnorableTextNode(node: Node): boolean {
-  return node.nodeType === Node.TEXT_NODE && (node.textContent ?? "").trim().length === 0;
-}
-
-function getManagedHeadNodes(startMarker: Element, endMarker: Element): Node[] {
-  const nodes: Node[] = [];
-  let cursor = startMarker.nextSibling;
-  while (cursor && cursor !== endMarker) {
-    nodes.push(cursor);
-    cursor = cursor.nextSibling;
-  }
-  return nodes;
-}
-
-function removeNode(node: Node): void {
-  if (node.parentNode) {
-    node.parentNode.removeChild(node);
-  }
-}
-
-function isStylesheetLinkNode(node: Node): node is HTMLLinkElement {
-  if (node.nodeType !== Node.ELEMENT_NODE) {
-    return false;
-  }
-
-  const element = node as Element;
-  return (
-    element.tagName.toLowerCase() === "link"
-    && (element.getAttribute("rel")?.toLowerCase() ?? "") === "stylesheet"
-    && Boolean(element.getAttribute("href"))
-  );
-}
-
-function toAbsoluteHref(href: string): string {
-  return new URL(href, document.baseURI).toString();
-}
-
-function waitForStylesheetLoad(link: HTMLLinkElement): Promise<void> {
-  const sheet = link.sheet;
-  if (sheet) {
-    return Promise.resolve();
-  }
-
-  return new Promise(resolve => {
-    const finish = () => {
-      link.removeEventListener("load", finish);
-      link.removeEventListener("error", finish);
-      resolve();
-    };
-
-    link.addEventListener("load", finish, { once: true });
-    link.addEventListener("error", finish, { once: true });
-  });
-}
-
-async function reconcileStylesheetLinks(options: {
-  head: HTMLHeadElement;
-  desiredStylesheetHrefs: string[];
-}): Promise<void> {
-  const desiredAbsoluteHrefs = options.desiredStylesheetHrefs.map(toAbsoluteHref);
-  const existingLinks = Array.from(
-    options.head.querySelectorAll('link[rel="stylesheet"][href]'),
-  ) as HTMLLinkElement[];
-
-  const existingByAbsoluteHref = new Map<string, HTMLLinkElement[]>();
-  for (const link of existingLinks) {
-    const href = link.getAttribute("href");
-    if (!href) {
-      continue;
-    }
-    const absoluteHref = toAbsoluteHref(href);
-    const list = existingByAbsoluteHref.get(absoluteHref) ?? [];
-    list.push(link);
-    existingByAbsoluteHref.set(absoluteHref, list);
-  }
-
-  const waitForLoads: Promise<void>[] = [];
-  for (let index = 0; index < options.desiredStylesheetHrefs.length; index += 1) {
-    const href = options.desiredStylesheetHrefs[index]!;
-    const absoluteHref = desiredAbsoluteHrefs[index]!;
-    const existing = existingByAbsoluteHref.get(absoluteHref)?.[0];
-    if (existing) {
-      waitForLoads.push(waitForStylesheetLoad(existing));
-      continue;
-    }
-
-    const link = document.createElement("link");
-    link.setAttribute("rel", "stylesheet");
-    link.setAttribute("href", href);
-    options.head.appendChild(link);
-    waitForLoads.push(waitForStylesheetLoad(link));
-  }
-
-  const seen = new Set<string>();
-  for (const link of Array.from(options.head.querySelectorAll('link[rel="stylesheet"][href]'))) {
-    const href = link.getAttribute("href");
-    if (!href) {
-      continue;
-    }
-
-    const absoluteHref = toAbsoluteHref(href);
-    if (seen.has(absoluteHref)) {
-      removeNode(link);
-      continue;
-    }
-
-    seen.add(absoluteHref);
-  }
-
-  await Promise.all(waitForLoads);
-}
-
-async function replaceManagedHead(headHtml: string): Promise<void> {
-  const head = document.head;
-  const startMarker = head.querySelector(`meta[${RBSSR_HEAD_MARKER_START_ATTR}]`);
-  const endMarker = head.querySelector(`meta[${RBSSR_HEAD_MARKER_END_ATTR}]`);
-
-  if (!startMarker || !endMarker || startMarker === endMarker) {
-    return;
-  }
-
-  const template = document.createElement("template");
-  template.innerHTML = headHtml;
-
-  const desiredStylesheetHrefs = Array.from(template.content.querySelectorAll('link[rel="stylesheet"][href]'))
-    .map(link => link.getAttribute("href"))
-    .filter((value): value is string => Boolean(value));
-  for (const styleNode of Array.from(template.content.querySelectorAll('link[rel="stylesheet"][href]'))) {
-    removeNode(styleNode);
-  }
-
-  const desiredNodes = Array.from(template.content.childNodes).filter(node => !isIgnorableTextNode(node));
-  const currentNodes = getManagedHeadNodes(startMarker, endMarker).filter(node => {
-    if (isIgnorableTextNode(node)) {
-      return false;
-    }
-
-    if (isStylesheetLinkNode(node)) {
-      return false;
-    }
-
-    return true;
-  });
-  const unusedCurrentNodes = new Set(currentNodes);
-
-  let cursor = startMarker.nextSibling;
-
-  for (const desiredNode of desiredNodes) {
-    while (cursor && cursor !== endMarker && isIgnorableTextNode(cursor)) {
-      const next = cursor.nextSibling;
-      removeNode(cursor);
-      cursor = next;
-    }
-
-    const desiredSignature = nodeSignature(desiredNode);
-
-    if (cursor && cursor !== endMarker && nodeSignature(cursor) === desiredSignature) {
-      unusedCurrentNodes.delete(cursor);
-      cursor = cursor.nextSibling;
-      continue;
-    }
-
-    let matchedNode: Node | null = null;
-    for (const currentNode of currentNodes) {
-      if (!unusedCurrentNodes.has(currentNode)) {
-        continue;
-      }
-      if (nodeSignature(currentNode) === desiredSignature) {
-        matchedNode = currentNode;
-        break;
-      }
-    }
-
-    if (matchedNode) {
-      unusedCurrentNodes.delete(matchedNode);
-      head.insertBefore(matchedNode, cursor ?? endMarker);
-      continue;
-    }
-
-    head.insertBefore(desiredNode.cloneNode(true), cursor ?? endMarker);
-  }
-
-  for (const leftover of unusedCurrentNodes) {
-    removeNode(leftover);
-  }
-
-  await reconcileStylesheetLinks({
-    head,
-    desiredStylesheetHrefs,
-  });
-}
-
 async function renderTransitionInitial(
   chunk: TransitionInitialChunk,
   toUrl: URL,
@@ -928,7 +713,7 @@ async function navigateToInternal(
           matchedModules,
           {
             routeId: matched.route.id,
-            data: null,
+            loaderData: null,
             params: matched.params,
             url: toUrl.toString(),
           },

package/framework/runtime/doctype-stream.ts

@@ -0,0 +1,38 @@
+const DOCTYPE = new TextEncoder().encode("<!doctype html>");
+
+export function prependDoctypeStream(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      controller.enqueue(DOCTYPE);
+      reader = stream.getReader();
+
+      try {
+        while (true) {
+          const result = await reader.read();
+          if (result.done) {
+            break;
+          }
+          controller.enqueue(result.value);
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      } finally {
+        const activeReader = reader;
+        reader = null;
+        activeReader?.releaseLock();
+      }
+    },
+    async cancel(reason) {
+      const activeReader = reader;
+      if (activeReader) {
+        await activeReader.cancel(reason);
+        return;
+      }
+
+      await stream.cancel(reason);
+    },
+  });
+}