react-bun-ssr 0.1.0

package/framework/runtime/tree.tsx

@@ -0,0 +1,77 @@
+import { createContext, useContext, type ReactElement, type ReactNode } from "react";
+import type { Params, RenderPayload, RouteModuleBundle } from "./types";
+
+interface RuntimeState {
+  data: unknown;
+  params: Params;
+  url: URL;
+  error?: unknown;
+}
+
+const RuntimeContext = createContext<RuntimeState | null>(null);
+const OutletContext = createContext<ReactNode>(null);
+
+function useRuntimeState(): RuntimeState {
+  const state = useContext(RuntimeContext);
+  if (!state) {
+    throw new Error("react-bun-ssr hooks must be used inside a framework route tree");
+  }
+  return state;
+}
+
+export function useLoaderData<T = unknown>(): T {
+  return useRuntimeState().data as T;
+}
+
+export function useParams<T extends Params = Params>(): T {
+  return useRuntimeState().params as T;
+}
+
+export function useRequestUrl(): URL {
+  return useRuntimeState().url;
+}
+
+export function useRouteError(): unknown {
+  return useRuntimeState().error;
+}
+
+export function Outlet(): ReactElement | null {
+  const outlet = useContext(OutletContext);
+  if (outlet === undefined || outlet === null) {
+    return null;
+  }
+  return <>{outlet}</>;
+}
+
+export function createRouteTree(
+  modules: RouteModuleBundle,
+  leafElement: ReactElement,
+  payload: RenderPayload,
+): ReactElement {
+  const runtimeState: RuntimeState = {
+    data: payload.data,
+    params: payload.params,
+    url: new URL(payload.url),
+    error: payload.error,
+  };
+
+  let current: ReactNode = leafElement;
+
+  for (let index = modules.layouts.length - 1; index >= 0; index -= 1) {
+    const Layout = modules.layouts[index]!.default;
+    current = (
+      <OutletContext.Provider value={current}>
+        <Layout />
+      </OutletContext.Provider>
+    );
+  }
+
+  const Root = modules.root.default;
+  const tree = (
+    <OutletContext.Provider value={current}>
+      <Root />
+    </OutletContext.Provider>
+  );
+
+  return <RuntimeContext.Provider value={runtimeState}>{tree}</RuntimeContext.Provider>;
+}

package/framework/runtime/types.ts

@@ -0,0 +1,213 @@
+import type { ComponentType, ReactNode } from "react";
+
+export type Params = Record<string, string>;
+
+export interface RequestContext {
+  request: Request;
+  url: URL;
+  params: Params;
+  cookies: Map<string, string>;
+  locals: Record<string, unknown>;
+}
+
+export interface LoaderContext extends RequestContext {}
+
+export interface ActionContext extends RequestContext {
+  formData?: FormData;
+  json?: unknown;
+}
+
+export interface DeferredToken {
+  __rbssrDeferred: string;
+}
+
+export interface DeferredLoaderResult<T extends Record<string, unknown> = Record<string, unknown>> {
+  __rbssrType: "defer";
+  data: T;
+}
+
+export type LoaderResult =
+  | Response
+  | RedirectResult
+  | DeferredLoaderResult<Record<string, unknown>>
+  | Record<string, unknown>
+  | string
+  | number
+  | boolean
+  | null;
+export type ActionResult = LoaderResult | RedirectResult;
+
+export type Loader = (ctx: LoaderContext) => Promise<LoaderResult> | LoaderResult;
+export type Action = (ctx: ActionContext) => Promise<ActionResult> | ActionResult;
+
+export interface RedirectResult {
+  type: "redirect";
+  location: string;
+  status?: 301 | 302 | 303 | 307 | 308;
+}
+
+export type Middleware = (
+  ctx: RequestContext,
+  next: () => Promise<Response>,
+) => Promise<Response> | Response;
+
+export type HeadFn = (ctx: {
+  data: unknown;
+  params: Params;
+  url: URL;
+  error?: unknown;
+}) => ReactNode;
+
+export type MetaFn = (ctx: {
+  data: unknown;
+  params: Params;
+  url: URL;
+  error?: unknown;
+}) => Record<string, string>;
+
+export type MetaValue = Record<string, string> | MetaFn;
+
+export interface RouteModule {
+  default: ComponentType;
+  loader?: Loader;
+  action?: Action;
+  middleware?: Middleware | Middleware[];
+  head?: HeadFn;
+  meta?: MetaValue;
+  ErrorBoundary?: ComponentType<{ error: unknown }>;
+  NotFound?: ComponentType;
+}
+
+export type LayoutModule = RouteModule;
+
+export type ApiHandler = (ctx: RequestContext) => Promise<Response | unknown> | Response | unknown;
+
+export interface ApiRouteModule {
+  GET?: ApiHandler;
+  POST?: ApiHandler;
+  PUT?: ApiHandler;
+  PATCH?: ApiHandler;
+  DELETE?: ApiHandler;
+  HEAD?: ApiHandler;
+  OPTIONS?: ApiHandler;
+}
+
+export interface ResponseHeaderRule {
+  source: string;
+  headers: Record<string, string>;
+}
+
+export interface ResolvedResponseHeaderRule extends ResponseHeaderRule {
+  matcher: RegExp;
+}
+
+export interface FrameworkConfig {
+  appDir?: string;
+  routesDir?: string;
+  publicDir?: string;
+  rootModule?: string;
+  middlewareFile?: string;
+  distDir?: string;
+  host?: string;
+  port?: number;
+  mode?: "development" | "production";
+  headers?: ResponseHeaderRule[];
+}
+
+export interface ResolvedConfig {
+  cwd: string;
+  appDir: string;
+  routesDir: string;
+  publicDir: string;
+  rootModule: string;
+  middlewareFile: string;
+  distDir: string;
+  host: string;
+  port: number;
+  mode: "development" | "production";
+  headerRules: ResolvedResponseHeaderRule[];
+}
+
+export type SegmentKind = "static" | "dynamic" | "catchall";
+
+export interface RouteSegment {
+  kind: SegmentKind;
+  value: string;
+}
+
+export interface PageRouteDefinition {
+  type: "page";
+  id: string;
+  filePath: string;
+  routePath: string;
+  segments: RouteSegment[];
+  score: number;
+  layoutFiles: string[];
+  middlewareFiles: string[];
+  directory: string;
+}
+
+export interface ApiRouteDefinition {
+  type: "api";
+  id: string;
+  filePath: string;
+  routePath: string;
+  segments: RouteSegment[];
+  score: number;
+  middlewareFiles: string[];
+  directory: string;
+}
+
+export interface RouteManifest {
+  pages: PageRouteDefinition[];
+  api: ApiRouteDefinition[];
+}
+
+export interface RouteMatch<T extends PageRouteDefinition | ApiRouteDefinition> {
+  route: T;
+  params: Params;
+}
+
+export interface BuildRouteAsset {
+  script: string;
+  css: string[];
+}
+
+export interface BuildManifest {
+  version: string;
+  generatedAt: string;
+  routes: Record<string, BuildRouteAsset>;
+}
+
+export interface RenderPayload {
+  routeId: string;
+  data: unknown;
+  params: Params;
+  url: string;
+  error?: {
+    message: string;
+  };
+}
+
+export interface RouteModuleBundle {
+  root: RouteModule;
+  layouts: LayoutModule[];
+  route: RouteModule;
+}
+
+export interface HydrationDocumentAssets {
+  script?: string;
+  css: string[];
+  devVersion?: number;
+}
+
+export interface ServerRuntimeOptions {
+  dev?: boolean;
+  buildManifest?: BuildManifest;
+  devAssets?: Record<string, BuildRouteAsset>;
+  getDevAssets?: () => Record<string, BuildRouteAsset>;
+  reloadVersion?: () => number;
+  subscribeReload?: (listener: (version: number) => void) => (() => void) | void;
+  resolvePaths?: () => Partial<ResolvedConfig>;
+  onBeforeRequest?: () => Promise<void>;
+}

package/framework/runtime/utils.ts

@@ -0,0 +1,115 @@
+import path from "node:path";
+import { sha256Short, type HashInput } from "./io";
+
+export function normalizeSlashes(value: string): string {
+  return value.replace(/\\+/g, "/");
+}
+
+export function trimFileExtension(value: string): string {
+  return value.replace(/\.(tsx?|jsx?|mdx?)$/, "");
+}
+
+export function ensureLeadingSlash(value: string): string {
+  return value.startsWith("/") ? value : `/${value}`;
+}
+
+export function withoutTrailingSlash(value: string): string {
+  if (value === "/") {
+    return value;
+  }
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+export function toRouteId(relativeFilePath: string): string {
+  return normalizeSlashes(trimFileExtension(relativeFilePath))
+    .replace(/\//g, "__")
+    .replace(/\[\.\.\./g, "catchall_")
+    .replace(/\[/g, "param_")
+    .replace(/\]/g, "")
+    .replace(/\(|\)/g, "")
+    .replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
+export function isRouteGroup(segment: string): boolean {
+  return segment.startsWith("(") && segment.endsWith(")");
+}
+
+export function toImportPath(fromDir: string, absoluteTargetPath: string): string {
+  const relativePath = normalizeSlashes(path.relative(fromDir, absoluteTargetPath));
+  if (relativePath.startsWith(".")) {
+    return relativePath;
+  }
+  return `./${relativePath}`;
+}
+
+export function routePathFromSegments(segments: string[]): string {
+  const pathValue = segments.length === 0 ? "/" : `/${segments.join("/")}`;
+  return withoutTrailingSlash(pathValue === "" ? "/" : pathValue);
+}
+
+export function parseCookieHeader(headerValue: string | null): Map<string, string> {
+  const cookies = new Map<string, string>();
+  if (!headerValue) {
+    return cookies;
+  }
+
+  for (const part of headerValue.split(";")) {
+    const [rawName, ...rest] = part.trim().split("=");
+    if (!rawName) {
+      continue;
+    }
+    const rawValue = rest.join("=");
+    try {
+      cookies.set(rawName, decodeURIComponent(rawValue));
+    } catch {
+      cookies.set(rawName, rawValue);
+    }
+  }
+
+  return cookies;
+}
+
+export function isMutatingMethod(method: string): boolean {
+  return ["POST", "PUT", "PATCH", "DELETE"].includes(method.toUpperCase());
+}
+
+export function safeJsonSerialize(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+export function sanitizeErrorMessage(error: unknown, production: boolean): string {
+  if (!production) {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+  return "Internal Server Error";
+}
+
+export function stableHash(input: HashInput): string {
+  return sha256Short(input);
+}
+
+export function ensureWithin(baseDir: string, target: string): string | null {
+  const resolved = path.resolve(baseDir, target);
+  const relative = path.relative(baseDir, resolved);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return null;
+  }
+  return resolved;
+}
+
+export function toPosixPath(value: string): string {
+  return normalizeSlashes(value);
+}
+
+export function toFileImportUrl(filePath: string): string {
+  const resolved = path.resolve(filePath).replace(/\\/g, "/");
+  const withLeadingSlash = resolved.startsWith("/") ? resolved : `/${resolved}`;
+  const encoded = encodeURI(withLeadingSlash).replace(/#/g, "%23").replace(/\?/g, "%3F");
+  return `file://${encoded}`;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "react-bun-ssr",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "types": "./framework/runtime/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.9"
+  },
+  "files": [
+    "bin",
+    "framework",
+    "README.md"
+  ],
+  "bin": {
+    "rbssr": "./bin/rbssr.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./framework/runtime/index.ts",
+      "default": "./framework/index.ts"
+    },
+    "./route": {
+      "types": "./framework/runtime/route-api.ts",
+      "default": "./framework/runtime/route-api.ts"
+    }
+  },
+  "scripts": {
+    "init": "bun bin/rbssr.ts init",
+    "dev": "bun bin/rbssr.ts dev",
+    "build": "bun bin/rbssr.ts build",
+    "start": "bun bin/rbssr.ts start",
+    "typecheck": "bun bin/rbssr.ts typecheck",
+    "test": "bun bin/rbssr.ts test",
+    "test:unit": "bun test ./tests/unit",
+    "test:integration": "bun test ./tests/integration",
+    "test:e2e": "bunx playwright test",
+    "docs:dev": "bun run scripts/generate-api-docs.ts && bun run scripts/build-search-index.ts && bun bin/rbssr.ts dev",
+    "docs:build": "bun run scripts/docs-build.ts",
+    "docs:check": "bun run scripts/check-docs.ts",
+    "docs:preview": "bun run start"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.54.2",
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "react": "^19",
+    "react-dom": "^19",
+    "typescript": "^5.9.2"
+  }
+}