react-bun-ssr 0.1.0 → 0.2.0

package/README.md

@@ -1,48 +1,45 @@
 # react-bun-ssr
 
-`react-bun-ssr` is a TypeScript-first SSR React framework built for Bun.
+`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.
 
-Documentation: https://react-bun-ssr.fly.dev/docs/getting-started/introduction
+- Documentation: https://react-bun-ssr.fly.dev/docs
+- API reference: https://react-bun-ssr.fly.dev/docs/api/overview
+- Blog: https://react-bun-ssr.fly.dev/blog
+- Repository: https://github.com/react-formation/react-bun-ssr
 
-This repository contains both:
-- The framework implementation (`framework/**`, `bin/**`).
-- The official documentation site built with the framework itself (`app/**`).
+## Why react-bun-ssr?
 
-## Project layout
+`react-bun-ssr` exists for teams that want server-rendered React without starting from Node-first assumptions.
 
-- `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.
+It is designed around Bun's runtime, server, bundler, markdown support, and file APIs instead of treating Bun as a compatibility layer. The goal is to stay small enough to understand, but complete enough to use seriously for real SSR applications. The documentation site in this repository is built with the framework itself, so the framework is continuously exercised by its own product surface.
 
-## Requirements
+## What it includes
 
-- Bun `>= 1.3.9`
-- macOS/Linux (or equivalent Bun-supported environment)
+- [File-based routing](/docs/routing/file-based-routing) for pages, APIs, dynamic params, and markdown routes
+- [Layouts, route groups, and middleware](/docs/routing/layouts-and-groups) with a dedicated [middleware pipeline](/docs/routing/middleware)
+- [Loaders and actions](/docs/data/loaders) for explicit data fetching and mutation flow
+- [Streaming SSR and deferred data](/docs/rendering/streaming-deferred)
+- Soft client transitions with [`Link` and `useRouter`](/docs/routing/navigation)
+- [Bun-first runtime, build, and deployment model](/docs/deployment/bun-deployment)
+- [CSS Modules and static asset support](/docs/styling/css-modules)
+- [Response header config and static caching defaults](/docs/deployment/configuration)
 
-## Runtime API policy
+## Installation
 
-- 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.
+Prerequisites:
 
-## Run locally
+- Bun `>= 1.3.10`
+- `rbssr` available on PATH in the workflow you use to start a new app
 
-Install dependencies:
+Minimal setup:
 
 ```bash
+bun --version
+mkdir my-app
+cd my-app
+rbssr init
 bun install
-```
-
-Run docs site in development:
-
-```bash
-bun run docs:dev
+bun run dev
 ```
 
 Open:
@@ -51,155 +48,142 @@ Open:
 http://127.0.0.1:3000
 ```
 
-Build production artifacts:
-
-```bash
-bun run docs:build
-```
-
-Start production server:
+For the full setup walkthrough, read the installation guide:
 
-```bash
-bun run docs:preview
-```
+- https://react-bun-ssr.fly.dev/docs/start/installation
 
-## Useful commands
+## What `rbssr init` gives you
 
-Framework:
+`rbssr init` scaffolds a small Bun-first SSR app:
 
-```bash
-bun run dev
-bun run build
-bun run start
-bun run typecheck
-bun run test
+```text
+app/
+  root.tsx
+  middleware.ts
+  routes/
+    index.tsx
+    api/
+      health.ts
+rbssr.config.ts
 ```
 
-Docs:
+- `app/root.tsx`: document shell and top-level layout
+- `app/middleware.ts`: global request pipeline hook
+- `app/routes/index.tsx`: first SSR page route
+- `app/routes/api/health.ts`: first API route
+- `rbssr.config.ts`: runtime configuration entrypoint
 
-```bash
-bun run docs:dev
-bun run docs:check
-bun run docs:build
-bun run docs:preview
-```
+The quickest follow-up is:
 
-## Generated files
+- https://react-bun-ssr.fly.dev/docs/start/quick-start
 
-Do not hand-edit generated docs artifacts:
-- `app/routes/docs/api/*.md`
-- `app/routes/docs/search-index.json`
+## How it works
 
-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`
+### File-based routing
 
-## Collaboration guide
+Routes live under `app/routes`. Page routes, API routes, dynamic params, and markdown routes all share one route tree. Files like `_layout` and `_middleware` participate in routing and request flow without becoming public URL segments.
 
-### 1. Create a branch
+Read more:
 
-```bash
-git checkout -b feat/<short-description>
-```
+- https://react-bun-ssr.fly.dev/docs/routing/file-based-routing
 
-### 2. Make changes
+### Request pipeline
 
-- 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.
+For a page request, the framework resolves the matching route, runs global and nested middleware, executes the matched loader or action, and then renders an HTML response or returns a direct `Response` when the route short-circuits. API routes use the same route tree and middleware model, but return handler responses instead of page HTML.
 
-### 3. Validate before pushing
+Read more:
 
-```bash
-bun run test
-bun run docs:check
-bun run docs:build
-```
+- https://react-bun-ssr.fly.dev/docs/routing/middleware
+- https://react-bun-ssr.fly.dev/docs/data/loaders
 
-### 4. Commit with generated artifacts when needed
+### Rendering model
 
-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`.
+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.
 
-### 5. Open a PR
+Read more:
 
-Include:
-- Problem statement.
-- Approach and tradeoffs.
-- Testing performed.
-- Screenshots/GIF for docs UI changes (if relevant).
+- https://react-bun-ssr.fly.dev/docs/rendering/streaming-deferred
+- https://react-bun-ssr.fly.dev/docs/routing/navigation
 
-## CI contract
+### Bun-first runtime
 
-CI runs:
-- `bun run test:unit`
-- `bun run test:integration`
-- `bun run docs:check`
-- `bun run docs:build`
+Bun provides the runtime, server, bundler, markdown support, and file APIs that the framework is built around. `react-bun-ssr` is designed to use those primitives directly instead of layering itself on top of a Node-first base.
 
-`docs:check` fails when docs metadata, links, or generated artifacts are stale.
+Read more:
 
-E2E (`bun run test:e2e`) runs on `push` to `main` only.
+- https://react-bun-ssr.fly.dev/docs/api/bun-runtime-apis
 
-## Deploy to Fly.io
+## Core commands
 
-### Prerequisites
+Framework commands:
 
-- Install `flyctl`: https://fly.io/docs/hands-on/install-flyctl/
-- Login:
+- `rbssr init`: scaffold a new app in the current directory
+- `rbssr dev`: start the Bun dev server
+- `rbssr build`: create production output in `dist/`
+- `rbssr start`: run the built app in production mode
 
-```bash
-fly auth login
-```
+Repository maintenance commands:
+
+- `bun run docs:dev`
+- `bun run docs:check`
+- `bun run docs:build`
+- `bun run test`
+- `bun run typecheck`
 
-### One-time setup
+CLI reference:
 
-`fly.toml` is included in this repository. Update the `app` name if needed:
+- https://react-bun-ssr.fly.dev/docs/tooling/cli
 
-- `fly.toml`
+## Working on this repository
 
-Initialize without deploying (optional):
+This repository contains both the framework and the official docs site built with it.
 
 ```bash
-fly launch --no-deploy
+git clone git@github.com:react-formation/react-bun-ssr.git
+cd react-bun-ssr
+bun install
+bun run docs:dev
 ```
 
-### Deploy
+That starts the docs site locally using the framework itself.
 
-```bash
-fly deploy
-```
+## Project layout
 
-### Validate deployment
+- `framework/`: runtime, renderer, route handling, build tooling, and CLI internals
+- `bin/rbssr.ts`: CLI entrypoint
+- `app/`: docs site routes, layouts, middleware, blog, and styles
+- `app/routes/docs/**/*.md`: authored documentation pages
+- `app/routes/blog/*.md`: authored blog posts
+- `scripts/`: generators and validation scripts
+- `tests/`: unit and integration tests
+- `e2e/`: Playwright end-to-end tests
 
-```bash
-fly status
-fly logs
-```
+## Contributing
 
-Open:
+Contributions should keep framework behavior, docs, tests, and generated artifacts aligned. For local setup, workflow, validation requirements, and generated-file policy, read [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-```text
-https://<your-fly-app>.fly.dev/docs/getting-started/introduction
-```
+## Release and deploy
 
-### Rollback
+- Pushes to `main` run the main-branch CI gate and deploy automatically to Fly.io.
+- Tags like `v0.1.1-rc.0` publish prereleases to npm under `rc`.
+- Tags like `v0.1.1` publish stable releases to npm under `latest`.
+- 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`.
 
-```bash
-fly releases
-fly deploy --image <image-ref-from-release>
-```
+## Deploying
+
+Fly.io deployment support is already documented and used by this project.
 
-### Scaling (optional)
+Happy path:
 
 ```bash
-fly scale vm shared-cpu-1x
+fly auth login
+fly deploy
 ```
 
-### Optional CI deploy
-
-The workflow includes an optional `deploy-fly` job on `main` push.  
-Set this repository secret before enabling production deploys:
+Full deployment docs:
 
-- `FLY_API_TOKEN`
+- https://react-bun-ssr.fly.dev/docs/deployment/bun-deployment
+- https://react-bun-ssr.fly.dev/docs/deployment/configuration
+- https://react-bun-ssr.fly.dev/docs/deployment/troubleshooting

package/framework/cli/commands.ts

@@ -1,18 +1,23 @@
-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 { ensureDir, existsPath, writeText, writeTextIfChanged } from "../runtime/io";
+import type { FrameworkConfig, ResolvedConfig } from "../runtime/types";
+import {
+  createDevHotEntrypointSource,
+  createProductionServerEntrypointSource,
+  createTestCommands,
+  createTypecheckCommand,
+  parseFlags,
+  RBSSR_DEV_RESTART_EXIT_CODE,
+} from "./internal";
 import { scaffoldApp } from "./scaffold";
 
 function log(message: string): void {
@@ -20,12 +25,6 @@ function log(message: string): void {
   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);
@@ -37,29 +36,7 @@ async function writeProductionServerEntrypoint(options: { distDir: string }): Pr
   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);
+  await writeText(serverEntryPath, createProductionServerEntrypointSource());
 }
 
 export async function runInit(args: string[], cwd = process.cwd()): Promise<void> {
@@ -109,200 +86,64 @@ export async function runBuild(cwd = process.cwd()): Promise<void> {
 }
 
 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(":");
+  await getConfig(cwd);
+
+  const generatedDevDir = path.resolve(cwd, ".rbssr/generated/dev");
+  const generatedEntryPath = path.join(generatedDevDir, "entry.ts");
+  await ensureDir(generatedDevDir);
+  await writeTextIfChanged(generatedEntryPath, createDevHotEntrypointSource({
+    cwd,
+    runtimeModulePath: path.resolve(import.meta.dir, "dev-runtime.ts"),
+  }));
+
+  let activeChild: Bun.Subprocess<"inherit", "inherit", "inherit"> | null = null;
+  let shuttingDown = false;
+
+  const forwardSignal = (signal: NodeJS.Signals): void => {
+    shuttingDown = true;
+    activeChild?.kill(signal);
   };
 
-  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/",
-    });
+  process.once("SIGINT", () => {
+    forwardSignal("SIGINT");
+  });
 
-    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})`);
-  };
+  process.once("SIGTERM", () => {
+    forwardSignal("SIGTERM");
+  });
 
-  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);
+  while (true) {
+    activeChild = Bun.spawn({
+      cmd: ["bun", "--hot", generatedEntryPath],
+      cwd,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: {
+        ...process.env,
+        RBSSR_DEV_LAUNCHER: "1",
+        RBSSR_DEV_CHILD: "1",
+      },
     });
-    return task;
-  };
 
-  await enqueueRebuild(true);
+    const exitCode = await activeChild.exited;
+    activeChild = null;
 
-  let rebuildTimer: ReturnType<typeof setTimeout> | undefined;
-  const scheduleRebuild = (): void => {
-    if (rebuildTimer) {
-      clearTimeout(rebuildTimer);
+    if (shuttingDown) {
+      return;
     }
 
-    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`);
+    if (exitCode === RBSSR_DEV_RESTART_EXIT_CODE) {
+      log("restarting dev child after config change");
+      continue;
     }
-  }
 
-  const cleanup = (): void => {
-    if (rebuildTimer) {
-      clearTimeout(rebuildTimer);
-      rebuildTimer = undefined;
-    }
-    for (const watcher of watchers) {
-      watcher.close();
+    if (exitCode !== 0) {
+      process.exit(exitCode);
     }
-  };
-
-  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}`);
+    return;
+  }
 }
 
 export async function runStart(cwd = process.cwd()): Promise<void> {
@@ -328,16 +169,11 @@ function runSubprocess(cmd: string[]): void {
 }
 
 export async function runTypecheck(): Promise<void> {
-  runSubprocess(["bun", "x", "tsc", "--noEmit"]);
+  runSubprocess(createTypecheckCommand());
 }
 
 export async function runTest(extraArgs: string[]): Promise<void> {
-  if (extraArgs.length > 0) {
-    runSubprocess(["bun", "test", ...extraArgs]);
-    return;
+  for (const cmd of createTestCommands(extraArgs)) {
+    runSubprocess(cmd);
   }
-
-  runSubprocess(["bun", "test", "./tests/unit"]);
-  runSubprocess(["bun", "test", "./tests/integration"]);
-  runSubprocess(["bun", "x", "playwright", "test"]);
 }