react-bun-ssr 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# react-bun-ssr
+
+`react-bun-ssr` is a TypeScript-first SSR React framework built for Bun.
+
+Documentation: https://react-bun-ssr.fly.dev/docs/getting-started/introduction
+
+This repository contains both:
+- The framework implementation (`framework/**`, `bin/**`).
+- The official documentation site built with the framework itself (`app/**`).
+
+## Project layout
+
+- `framework/`: runtime, router, renderer, build tooling, and CLI internals.
+- `bin/rbssr.ts`: CLI entrypoint.
+- `app/`: docs web app routes, layouts, middleware, and styles.
+- `app/routes/docs/**/*.md`: hand-authored markdown docs routes.
+- `app/routes/docs/_sidebar.ts`: docs navigation source of truth.
+- `app/routes/docs/api/*.md`: generated API docs.
+- `app/routes/docs/search-index.json`: generated search index.
+- `tests/`: unit + integration tests.
+- `e2e/`: Playwright end-to-end tests.
+
+## Requirements
+
+- Bun `>= 1.3.9`
+- macOS/Linux (or equivalent Bun-supported environment)
+
+## Runtime API policy
+
+- Prefer Bun APIs for file content I/O, hashing, build, and runtime operations.
+- `node:path` is intentionally retained for robust path resolution behavior.
+- `node:fs` is retained only for `watch` usage in dev mode.
+
+## Run locally
+
+Install dependencies:
+
+```bash
+bun install
+```
+
+Run docs site in development:
+
+```bash
+bun run docs:dev
+```
+
+Open:
+
+```text
+http://127.0.0.1:3000
+```
+
+Build production artifacts:
+
+```bash
+bun run docs:build
+```
+
+Start production server:
+
+```bash
+bun run docs:preview
+```
+
+## Useful commands
+
+Framework:
+
+```bash
+bun run dev
+bun run build
+bun run start
+bun run typecheck
+bun run test
+```
+
+Docs:
+
+```bash
+bun run docs:dev
+bun run docs:check
+bun run docs:build
+bun run docs:preview
+```
+
+## Generated files
+
+Do not hand-edit generated docs artifacts:
+- `app/routes/docs/api/*.md`
+- `app/routes/docs/search-index.json`
+
+They are regenerated by:
+- `bun run scripts/generate-api-docs.ts`
+- `bun run scripts/build-search-index.ts`
+- or automatically via `bun run docs:build`
+
+## Collaboration guide
+
+### 1. Create a branch
+
+```bash
+git checkout -b feat/<short-description>
+```
+
+### 2. Make changes
+
+- Framework code: update `framework/**`.
+- Docs content: update `app/routes/docs/**/*.md`.
+- Nav changes: update `app/routes/docs/_sidebar.ts`.
+- If exports change, regenerate API docs/search index.
+
+### 3. Validate before pushing
+
+```bash
+bun run test
+bun run docs:check
+bun run docs:build
+```
+
+### 4. Commit with generated artifacts when needed
+
+If your changes affect API docs or search corpus, commit updated files under `app/routes/docs/api/*.md` and `app/routes/docs/search-index.json`.
+
+### 5. Open a PR
+
+Include:
+- Problem statement.
+- Approach and tradeoffs.
+- Testing performed.
+- Screenshots/GIF for docs UI changes (if relevant).
+
+## CI contract
+
+CI runs:
+- `bun run test:unit`
+- `bun run test:integration`
+- `bun run docs:check`
+- `bun run docs:build`
+
+`docs:check` fails when docs metadata, links, or generated artifacts are stale.
+
+E2E (`bun run test:e2e`) runs on `push` to `main` only.
+
+## Deploy to Fly.io
+
+### Prerequisites
+
+- Install `flyctl`: https://fly.io/docs/hands-on/install-flyctl/
+- Login:
+
+```bash
+fly auth login
+```
+
+### One-time setup
+
+`fly.toml` is included in this repository. Update the `app` name if needed:
+
+- `fly.toml`
+
+Initialize without deploying (optional):
+
+```bash
+fly launch --no-deploy
+```
+
+### Deploy
+
+```bash
+fly deploy
+```
+
+### Validate deployment
+
+```bash
+fly status
+fly logs
+```
+
+Open:
+
+```text
+https://<your-fly-app>.fly.dev/docs/getting-started/introduction
+```
+
+### Rollback
+
+```bash
+fly releases
+fly deploy --image <image-ref-from-release>
+```
+
+### Scaling (optional)
+
+```bash
+fly scale vm shared-cpu-1x
+```
+
+### Optional CI deploy
+
+The workflow includes an optional `deploy-fly` job on `main` push.  
+Set this repository secret before enabling production deploys:
+
+- `FLY_API_TOKEN`

package/bin/rbssr.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../framework/cli/main.ts";

package/framework/cli/commands.ts

@@ -0,0 +1,343 @@
+import { watch, type FSWatcher } from "node:fs";
+import path from "node:path";
+import {
+  buildRouteManifest,
+  bundleClientEntries,
+  copyDirRecursive,
+  createBuildManifest,
+  discoverFileSignature,
+  ensureCleanDirectory,
+  generateClientEntries,
+} from "../runtime/build-tools";
+import { loadUserConfig, resolveConfig } from "../runtime/config";
+import { ensureDir, existsPath, listEntries, removePath, writeText } from "../runtime/io";
+import { createServer } from "../runtime/server";
+import type { BuildRouteAsset, FrameworkConfig, ResolvedConfig } from "../runtime/types";
+import { scaffoldApp } from "./scaffold";
+
+function log(message: string): void {
+  // eslint-disable-next-line no-console
+  console.log(`[rbssr] ${message}`);
+}
+
+function parseFlags(args: string[]): { force: boolean } {
+  return {
+    force: args.includes("--force"),
+  };
+}
+
+async function getConfig(cwd: string): Promise<{ userConfig: FrameworkConfig; resolved: ResolvedConfig }> {
+  const userConfig = await loadUserConfig(cwd);
+  const resolved = resolveConfig(userConfig, cwd);
+  return { userConfig, resolved };
+}
+
+async function writeProductionServerEntrypoint(options: { distDir: string }): Promise<void> {
+  const serverDir = path.join(options.distDir, "server");
+  await ensureDir(serverDir);
+
+  const serverEntryPath = path.join(serverDir, "server.mjs");
+  const content = `import path from "node:path";
+import config from "../../rbssr.config.ts";
+import { startHttpServer } from "../../framework/runtime/index.ts";
+
+const rootDir = path.resolve(path.dirname(Bun.fileURLToPath(import.meta.url)), "../..");
+process.chdir(rootDir);
+
+const manifestPath = path.resolve(rootDir, "dist/manifest.json");
+const manifest = await Bun.file(manifestPath).json();
+
+startHttpServer({
+  config: {
+    ...(config ?? {}),
+    mode: "production",
+  },
+  runtimeOptions: {
+    dev: false,
+    buildManifest: manifest,
+  },
+});
+`;
+
+  await writeText(serverEntryPath, content);
+}
+
+export async function runInit(args: string[], cwd = process.cwd()): Promise<void> {
+  const flags = parseFlags(args);
+  await scaffoldApp(cwd, {
+    force: flags.force,
+  });
+  log("project scaffolded");
+}
+
+export async function runBuild(cwd = process.cwd()): Promise<void> {
+  const { resolved } = await getConfig(cwd);
+
+  const distClientDir = path.join(resolved.distDir, "client");
+  const generatedDir = path.resolve(cwd, ".rbssr/generated/client-entries");
+
+  await Promise.all([
+    ensureCleanDirectory(resolved.distDir),
+    ensureCleanDirectory(generatedDir),
+  ]);
+
+  const routeManifest = await buildRouteManifest(resolved);
+  const entries = await generateClientEntries({
+    config: resolved,
+    manifest: routeManifest,
+    generatedDir,
+  });
+
+  const routeAssets = await bundleClientEntries({
+    entries,
+    outDir: distClientDir,
+    dev: false,
+    publicPrefix: "/client/",
+  });
+
+  await copyDirRecursive(resolved.publicDir, distClientDir);
+
+  const buildManifest = createBuildManifest(routeAssets);
+  await writeText(
+    path.join(resolved.distDir, "manifest.json"),
+    JSON.stringify(buildManifest, null, 2),
+  );
+
+  await writeProductionServerEntrypoint({ distDir: resolved.distDir });
+
+  log(`build complete: ${resolved.distDir}`);
+}
+
+export async function runDev(cwd = process.cwd()): Promise<void> {
+  const { userConfig, resolved } = await getConfig(cwd);
+  const generatedDir = path.resolve(cwd, ".rbssr/generated/client-entries");
+  const devClientDir = path.resolve(cwd, ".rbssr/dev/client");
+  const serverSnapshotsRoot = path.resolve(cwd, ".rbssr/dev/server-snapshots");
+  const docsSourceDir = path.resolve(cwd, "docs");
+  const docsSnapshotDir = path.join(serverSnapshotsRoot, "docs");
+
+  await Promise.all([
+    ensureDir(generatedDir),
+    ensureDir(devClientDir),
+    ensureCleanDirectory(serverSnapshotsRoot),
+  ]);
+
+  let routeAssets: Record<string, BuildRouteAsset> = {};
+  let signature = "";
+  let version = 0;
+  let currentServerSnapshotDir = resolved.appDir;
+  const reloadListeners = new Set<(nextVersion: number) => void>();
+  const docsDir = path.resolve(cwd, "docs");
+
+  const watchedRoots = [resolved.appDir];
+  if (await existsPath(docsDir)) {
+    watchedRoots.push(docsDir);
+  }
+
+  const getSourceSignature = async (): Promise<string> => {
+    const signatures = await Promise.all(
+      watchedRoots.map(root => discoverFileSignature(root)),
+    );
+    return signatures.join(":");
+  };
+
+  const notifyReload = (): void => {
+    for (const listener of reloadListeners) {
+      listener(version);
+    }
+  };
+
+  const rebuildIfNeeded = async (force = false): Promise<void> => {
+    const nextSignature = await getSourceSignature();
+    if (!force && nextSignature === signature) {
+      return;
+    }
+
+    signature = nextSignature;
+
+    const snapshotDir = path.join(serverSnapshotsRoot, `v${version + 1}`);
+    const hasDocsSourceDir = await existsPath(docsSourceDir);
+    await Promise.all([
+      (async () => {
+        await ensureCleanDirectory(snapshotDir);
+        await copyDirRecursive(resolved.appDir, snapshotDir);
+      })(),
+      hasDocsSourceDir
+        ? (async () => {
+            await ensureCleanDirectory(docsSnapshotDir);
+            await copyDirRecursive(docsSourceDir, docsSnapshotDir);
+          })()
+        : removePath(docsSnapshotDir),
+    ]);
+
+    const snapshotConfig: ResolvedConfig = {
+      ...resolved,
+      appDir: snapshotDir,
+      routesDir: path.join(snapshotDir, "routes"),
+      rootModule: path.join(snapshotDir, "root.tsx"),
+      middlewareFile: path.join(snapshotDir, "middleware.ts"),
+    };
+
+    const manifest = await buildRouteManifest(snapshotConfig);
+    const entries = await generateClientEntries({
+      config: snapshotConfig,
+      manifest,
+      generatedDir,
+    });
+
+    await ensureCleanDirectory(devClientDir);
+
+    routeAssets = await bundleClientEntries({
+      entries,
+      outDir: devClientDir,
+      dev: true,
+      publicPrefix: "/__rbssr/client/",
+    });
+
+    currentServerSnapshotDir = snapshotDir;
+
+    const staleVersions = (await listEntries(serverSnapshotsRoot))
+      .filter(entry => entry.isDirectory && /^v\d+$/.test(entry.name))
+      .map(entry => entry.name)
+      .sort((a, b) => {
+        const aNum = Number(a.slice(1));
+        const bNum = Number(b.slice(1));
+        return bNum - aNum;
+      })
+      .slice(3);
+    await Promise.all(staleVersions.map(stale => removePath(path.join(serverSnapshotsRoot, stale))));
+
+    version += 1;
+    notifyReload();
+    log(`rebuilt client assets (version ${version})`);
+  };
+
+  let rebuildQueue: Promise<void> = Promise.resolve();
+  const enqueueRebuild = (force = false): Promise<void> => {
+    const task = rebuildQueue.then(() => rebuildIfNeeded(force));
+    rebuildQueue = task.catch(error => {
+      // eslint-disable-next-line no-console
+      console.error("[rbssr] rebuild failed", error);
+    });
+    return task;
+  };
+
+  await enqueueRebuild(true);
+
+  let rebuildTimer: ReturnType<typeof setTimeout> | undefined;
+  const scheduleRebuild = (): void => {
+    if (rebuildTimer) {
+      clearTimeout(rebuildTimer);
+    }
+
+    rebuildTimer = setTimeout(() => {
+      rebuildTimer = undefined;
+      void enqueueRebuild(false);
+    }, 75);
+  };
+
+  const watchers: FSWatcher[] = [];
+  for (const root of watchedRoots) {
+    try {
+      const watcher = watch(root, { recursive: true }, () => {
+        scheduleRebuild();
+      });
+      watchers.push(watcher);
+    } catch {
+      log(`recursive file watching unavailable for ${root}; relying on request-time rebuild checks`);
+    }
+  }
+
+  const cleanup = (): void => {
+    if (rebuildTimer) {
+      clearTimeout(rebuildTimer);
+      rebuildTimer = undefined;
+    }
+    for (const watcher of watchers) {
+      watcher.close();
+    }
+  };
+
+  process.once("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  process.once("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  const server = createServer(
+    {
+      ...userConfig,
+      mode: "development",
+    },
+    {
+      dev: true,
+      getDevAssets: () => routeAssets,
+      reloadVersion: () => version,
+      subscribeReload: listener => {
+        reloadListeners.add(listener);
+        return () => {
+          reloadListeners.delete(listener);
+        };
+      },
+      resolvePaths: () => ({
+        appDir: currentServerSnapshotDir,
+        routesDir: path.join(currentServerSnapshotDir, "routes"),
+        rootModule: path.join(currentServerSnapshotDir, "root.tsx"),
+        middlewareFile: path.join(currentServerSnapshotDir, "middleware.ts"),
+      }),
+      onBeforeRequest: () => {
+        return enqueueRebuild(false);
+      },
+    },
+  );
+
+  const bunServer = Bun.serve({
+    hostname: resolved.host,
+    port: resolved.port,
+    fetch: server.fetch,
+    development: true,
+  });
+
+  log(`dev server listening on ${bunServer.url}`);
+}
+
+export async function runStart(cwd = process.cwd()): Promise<void> {
+  const { resolved } = await getConfig(cwd);
+  const serverEntry = path.join(resolved.distDir, "server", "server.mjs");
+  if (!(await existsPath(serverEntry))) {
+    throw new Error("Missing dist/server/server.mjs. Run `rbssr build` first.");
+  }
+
+  runSubprocess(["bun", serverEntry]);
+}
+
+function runSubprocess(cmd: string[]): void {
+  const subprocess = Bun.spawnSync({
+    cmd,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  if (subprocess.exitCode !== 0) {
+    process.exit(subprocess.exitCode);
+  }
+}
+
+export async function runTypecheck(): Promise<void> {
+  runSubprocess(["bun", "x", "tsc", "--noEmit"]);
+}
+
+export async function runTest(extraArgs: string[]): Promise<void> {
+  if (extraArgs.length > 0) {
+    runSubprocess(["bun", "test", ...extraArgs]);
+    return;
+  }
+
+  runSubprocess(["bun", "test", "./tests/unit"]);
+  runSubprocess(["bun", "test", "./tests/integration"]);
+  runSubprocess(["bun", "x", "playwright", "test"]);
+}

package/framework/cli/main.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+
+import {
+  runBuild,
+  runDev,
+  runInit,
+  runStart,
+  runTest,
+  runTypecheck,
+} from "./commands";
+
+function printHelp(): void {
+  // eslint-disable-next-line no-console
+  console.log(`rbssr commands:
+  rbssr init [--force]
+  rbssr dev
+  rbssr build
+  rbssr start
+  rbssr typecheck
+  rbssr test [bun-test-args]
+`);
+}
+
+async function main(argv: string[]): Promise<void> {
+  const [command = "help", ...rest] = argv;
+
+  switch (command) {
+    case "init":
+      await runInit(rest);
+      return;
+    case "dev":
+      await runDev();
+      return;
+    case "build":
+      await runBuild();
+      return;
+    case "start":
+      await runStart();
+      return;
+    case "typecheck":
+      await runTypecheck();
+      return;
+    case "test":
+      await runTest(rest);
+      return;
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      return;
+    default:
+      // eslint-disable-next-line no-console
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main(process.argv.slice(2)).catch(error => {
+  // eslint-disable-next-line no-console
+  console.error(error);
+  process.exit(1);
+});

package/framework/cli/scaffold.ts

@@ -0,0 +1,97 @@
+import path from "node:path";
+import { existsPath, writeText } from "../runtime/io";
+
+interface ScaffoldFile {
+  filePath: string;
+  content: string;
+}
+
+async function writeIfMissing(filePath: string, content: string, force: boolean): Promise<void> {
+  if (!force && await existsPath(filePath)) {
+    return;
+  }
+
+  await writeText(filePath, content);
+}
+
+function templateFiles(cwd: string): ScaffoldFile[] {
+  return [
+    {
+      filePath: path.join(cwd, "rbssr.config.ts"),
+      content: `import { defineConfig } from "react-bun-ssr";
+
+export default defineConfig({
+  appDir: "app",
+  port: 3000,
+});
+`,
+    },
+    {
+      filePath: path.join(cwd, "app/root.tsx"),
+      content: `import { Outlet } from "react-bun-ssr/route";
+
+export default function RootLayout() {
+  return (
+    <main className="shell">
+      <header className="top">
+        <h1>react-bun-ssr</h1>
+      </header>
+      <Outlet />
+    </main>
+  );
+}
+
+export function head() {
+  return <title>react-bun-ssr app</title>;
+}
+`,
+    },
+    {
+      filePath: path.join(cwd, "app/routes/index.tsx"),
+      content: `import { useLoaderData } from "react-bun-ssr/route";
+
+export function loader() {
+  return {
+    message: "Hello from SSR",
+    now: new Date().toISOString(),
+  };
+}
+
+export default function IndexRoute() {
+  const data = useLoaderData<{ message: string; now: string }>();
+
+  return (
+    <section>
+      <p>{data.message}</p>
+      <small>{data.now}</small>
+    </section>
+  );
+}
+`,
+    },
+    {
+      filePath: path.join(cwd, "app/routes/api/health.ts"),
+      content: `export function GET() {
+  return Response.json({ status: "ok" });
+}
+`,
+    },
+    {
+      filePath: path.join(cwd, "app/middleware.ts"),
+      content: `import type { Middleware } from "react-bun-ssr/route";
+
+export const middleware: Middleware = async (ctx, next) => {
+  const response = await next();
+  response.headers.set("x-powered-by", "react-bun-ssr");
+  return response;
+};
+`,
+    },
+  ];
+}
+
+export async function scaffoldApp(cwd: string, options: { force: boolean }): Promise<void> {
+  for (const file of templateFiles(cwd)) {
+    await writeIfMissing(file.filePath, file.content, options.force);
+  }
+}

package/framework/index.ts

@@ -0,0 +1 @@
+export * from "./runtime";