react-bun-ssr 0.1.0 → 0.1.1

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/runtime/build-tools.ts

@@ -1,5 +1,5 @@
-import path from "node:path";
-import { createBunRouteAdapter } from "./bun-route-adapter";
+import path from 'node:path';
+import { createBunRouteAdapter } from './bun-route-adapter';
 import {
   ensureCleanDir,
   ensureDir,
@@ -7,15 +7,23 @@ import {
   glob,
   statPath,
   writeTextIfChanged,
-} from "./io";
+} from './io';
 import type {
   BuildManifest,
   BuildRouteAsset,
   PageRouteDefinition,
   ResolvedConfig,
   RouteManifest,
-} from "./types";
-import { normalizeSlashes, stableHash, toImportPath } from "./utils";
+} from './types';
+import { normalizeSlashes, stableHash, toImportPath } from './utils';
+
+const BUILD_OPTIMIZE_IMPORTS = [
+  'react-bun-ssr',
+  'react-bun-ssr/route',
+  'react',
+  'react-dom',
+  '@datadog/browser-rum-react',
+];
 
 interface ClientEntryFile {
   routeId: string;
@@ -28,7 +36,7 @@ async function walkFiles(rootDir: string): Promise<string[]> {
     return [];
   }
 
-  return glob("**/*", { cwd: rootDir, absolute: true });
+  return glob('**/*', { cwd: rootDir, absolute: true });
 }
 
 function buildClientEntrySource(options: {
@@ -41,11 +49,13 @@ function buildClientEntrySource(options: {
 
   const imports: string[] = [];
 
-  const runtimeImport = toImportPath(generatedDir, runtimeClientFile);
+  const runtimeImport = normalizeSlashes(path.resolve(runtimeClientFile));
   const rootImport = toImportPath(generatedDir, rootModulePath);
   const routeImport = toImportPath(generatedDir, route.filePath);
 
-  imports.push(`import { hydrateRoute } from "${runtimeImport}";`);
+  imports.push(
+    `import { hydrateInitialRoute, registerRouteModules } from "${runtimeImport}";`,
+  );
 
   imports.push(`import RootDefault from "${rootImport}";`);
   imports.push(`import * as RootModule from "${rootImport}";`);
@@ -58,19 +68,24 @@ function buildClientEntrySource(options: {
     const layoutFilePath = route.layoutFiles[index]!;
     const layoutImportPath = toImportPath(generatedDir, layoutFilePath);
     imports.push(`import Layout${index}Default from "${layoutImportPath}";`);
-    imports.push(`import * as Layout${index}Module from "${layoutImportPath}";`);
-    layoutModuleRefs.push(`{ ...Layout${index}Module, default: Layout${index}Default }`);
+    imports.push(
+      `import * as Layout${index}Module from "${layoutImportPath}";`,
+    );
+    layoutModuleRefs.push(
+      `{ ...Layout${index}Module, default: Layout${index}Default }`,
+    );
   }
 
-  return `${imports.join("\n")}
+  return `${imports.join('\n')}
 
 const modules = {
   root: { ...RootModule, default: RootDefault },
-  layouts: [${layoutModuleRefs.join(", ")}],
+  layouts: [${layoutModuleRefs.join(', ')}],
   route: { ...RouteModule, default: RouteDefault },
 };
 
-hydrateRoute(modules);
+registerRouteModules(${JSON.stringify(route.id)}, modules);
+hydrateInitialRoute(${JSON.stringify(route.id)});
 `;
 }
 
@@ -82,10 +97,10 @@ export async function generateClientEntries(options: {
   const { config, manifest, generatedDir } = options;
   await ensureDir(generatedDir);
 
-  const runtimeClientFile = path.resolve(config.cwd, "framework/runtime/client-runtime.tsx");
+  const runtimeClientFile = path.resolve(import.meta.dir, 'client-runtime.tsx');
 
   return Promise.all(
-    manifest.pages.map(async route => {
+    manifest.pages.map(async (route) => {
       const entryName = `route__${route.id}.tsx`;
       const entryFilePath = path.join(generatedDir, entryName);
       const source = buildClientEntrySource({
@@ -112,14 +127,20 @@ async function mapBuildOutputsByPrefix(options: {
   publicPrefix: string;
 }): Promise<Record<string, BuildRouteAsset>> {
   const { outDir, routeIds, publicPrefix } = options;
-  const files = (await walkFiles(outDir)).map(filePath => normalizeSlashes(path.relative(outDir, filePath)));
+  const files = (await walkFiles(outDir)).map((filePath) =>
+    normalizeSlashes(path.relative(outDir, filePath)),
+  );
 
   const routeAssets: Record<string, BuildRouteAsset> = {};
 
   for (const routeId of routeIds) {
     const base = `route__${routeId}`;
-    const script = files.find(file => file.startsWith(base) && file.endsWith(".js"));
-    const css = files.filter(file => file.startsWith(base) && file.endsWith(".css"));
+    const script = files.find(
+      (file) => file.startsWith(base) && file.endsWith('.js'),
+    );
+    const css = files.filter(
+      (file) => file.startsWith(base) && file.endsWith('.css'),
+    );
 
     if (!script) {
       continue;
@@ -127,7 +148,56 @@ async function mapBuildOutputsByPrefix(options: {
 
     routeAssets[routeId] = {
       script: `${publicPrefix}${script}`,
-      css: css.map(file => `${publicPrefix}${file}`),
+      css: css.map((file) => `${publicPrefix}${file}`),
+    };
+  }
+
+  return routeAssets;
+}
+
+function normalizeMetafilePath(filePath: string): string {
+  return normalizeSlashes(filePath).replace(/^\.\//, "");
+}
+
+function toPublicBuildPath(publicPrefix: string, filePath: string): string {
+  return `${publicPrefix}${normalizeMetafilePath(filePath)}`;
+}
+
+function mapBuildOutputsFromMetafile(options: {
+  metafile: Bun.BuildMetafile;
+  entries: ClientEntryFile[];
+  publicPrefix: string;
+}): Record<string, BuildRouteAsset> {
+  const routeIdByEntrypoint = new Map<string, string>();
+  const routeIdByEntryName = new Map<string, string>();
+  for (const entry of options.entries) {
+    const absoluteEntrypoint = normalizeMetafilePath(path.resolve(entry.entryFilePath));
+    const relativeEntrypoint = normalizeMetafilePath(path.relative(process.cwd(), entry.entryFilePath));
+    routeIdByEntrypoint.set(absoluteEntrypoint, entry.routeId);
+    routeIdByEntrypoint.set(relativeEntrypoint, entry.routeId);
+    routeIdByEntryName.set(path.basename(entry.entryFilePath), entry.routeId);
+  }
+
+  const routeAssets: Record<string, BuildRouteAsset> = {};
+
+  for (const [outputPath, metadata] of Object.entries(options.metafile.outputs)) {
+    if (!outputPath.endsWith(".js") || !metadata.entryPoint) {
+      continue;
+    }
+
+    const normalizedEntrypoint = normalizeMetafilePath(metadata.entryPoint);
+    const absoluteEntrypoint = normalizeMetafilePath(path.resolve(process.cwd(), normalizedEntrypoint));
+    const routeId =
+      routeIdByEntrypoint.get(normalizedEntrypoint) ??
+      routeIdByEntrypoint.get(absoluteEntrypoint) ??
+      routeIdByEntryName.get(path.basename(normalizedEntrypoint));
+    if (!routeId) {
+      continue;
+    }
+
+    routeAssets[routeId] = {
+      script: toPublicBuildPath(options.publicPrefix, outputPath),
+      css: metadata.cssBundle ? [toPublicBuildPath(options.publicPrefix, metadata.cssBundle)] : [],
     };
   }
 
@@ -148,42 +218,64 @@ export async function bundleClientEntries(options: {
   }
 
   const result = await Bun.build({
-    entrypoints: entries.map(entry => entry.entryFilePath),
+    entrypoints: entries.map((entry) => entry.entryFilePath),
     outdir: outDir,
-    target: "browser",
-    format: "esm",
-    splitting: false,
-    sourcemap: dev ? "inline" : "external",
+    target: 'browser',
+    format: 'esm',
+    metafile: true,
+    optimizeImports: BUILD_OPTIMIZE_IMPORTS,
+    splitting: true,
+    sourcemap: dev ? 'inline' : 'external',
     minify: !dev,
-    naming: dev ? "[name].[ext]" : "[name]-[hash].[ext]",
+    naming: dev ? '[name].[ext]' : '[name]-[hash].[ext]',
   });
 
   if (!result.success) {
-    const messages = result.logs.map(log => log.message).join("\n");
+    const messages = result.logs.map((log) => log.message).join('\n');
     throw new Error(`Client bundle failed:\n${messages}`);
   }
 
-  return mapBuildOutputsByPrefix({
+  const routeAssetsFromMetafile = result.metafile
+    ? mapBuildOutputsFromMetafile({
+      metafile: result.metafile,
+      entries,
+      publicPrefix,
+    })
+    : {};
+
+  if (Object.keys(routeAssetsFromMetafile).length === entries.length) {
+    return routeAssetsFromMetafile;
+  }
+
+  const routeAssetsFromPrefix = await mapBuildOutputsByPrefix({
     outDir,
-    routeIds: entries.map(entry => entry.routeId),
+    routeIds: entries.map((entry) => entry.routeId),
     publicPrefix,
   });
+
+  return {
+    ...routeAssetsFromPrefix,
+    ...routeAssetsFromMetafile,
+  };
 }
 
 export async function ensureCleanDirectory(dirPath: string): Promise<void> {
   await ensureCleanDir(dirPath);
 }
 
-export async function copyDirRecursive(sourceDir: string, destinationDir: string): Promise<void> {
+export async function copyDirRecursive(
+  sourceDir: string,
+  destinationDir: string,
+): Promise<void> {
   if (!(await existsPath(sourceDir))) {
     return;
   }
 
   await ensureDir(destinationDir);
 
-  const entries = await glob("**/*", { cwd: sourceDir });
+  const entries = await glob('**/*', { cwd: sourceDir });
   await Promise.all(
-    entries.map(async entry => {
+    entries.map(async (entry) => {
       const from = path.join(sourceDir, entry);
       const to = path.join(destinationDir, entry);
       const fileStat = await statPath(from);
@@ -197,7 +289,9 @@ export async function copyDirRecursive(sourceDir: string, destinationDir: string
   );
 }
 
-export function createBuildManifest(routeAssets: Record<string, BuildRouteAsset>): BuildManifest {
+export function createBuildManifest(
+  routeAssets: Record<string, BuildRouteAsset>,
+): BuildManifest {
   return {
     version: stableHash(JSON.stringify(routeAssets)),
     generatedAt: new Date().toISOString(),
@@ -207,28 +301,38 @@ export function createBuildManifest(routeAssets: Record<string, BuildRouteAsset>
 
 export async function discoverFileSignature(rootDir: string): Promise<string> {
   const files = (await walkFiles(rootDir))
-    .filter(file => !normalizeSlashes(file).includes("/node_modules/"))
+    .filter((file) => !normalizeSlashes(file).includes('/node_modules/'))
     .sort();
 
-  const signatureBits = (await Promise.all(
-    files.map(async filePath => {
-      const fileStat = await statPath(filePath);
-      if (!fileStat?.isFile()) {
-        return null;
-      }
-      const contentHash = stableHash(await Bun.file(filePath).bytes());
-      return `${normalizeSlashes(filePath)}:${contentHash}`;
-    }),
-  )).filter((value): value is string => Boolean(value));
-
-  return stableHash(signatureBits.join("|"));
+  const signatureBits = (
+    await Promise.all(
+      files.map(async (filePath) => {
+        const fileStat = await statPath(filePath);
+        if (!fileStat?.isFile()) {
+          return null;
+        }
+        const contentHash = stableHash(await Bun.file(filePath).bytes());
+        return `${normalizeSlashes(filePath)}:${contentHash}`;
+      }),
+    )
+  ).filter((value): value is string => Boolean(value));
+
+  return stableHash(signatureBits.join('|'));
 }
 
-export async function buildRouteManifest(config: ResolvedConfig): Promise<RouteManifest> {
+export async function buildRouteManifest(
+  config: ResolvedConfig,
+): Promise<RouteManifest> {
   const adapter = await createBunRouteAdapter({
     routesDir: config.routesDir,
-    generatedMarkdownRootDir: path.resolve(config.cwd, ".rbssr/generated/markdown-routes"),
-    projectionRootDir: path.resolve(config.cwd, ".rbssr/generated/router-projection/build-manifest"),
+    generatedMarkdownRootDir: path.resolve(
+      config.cwd,
+      '.rbssr/generated/markdown-routes',
+    ),
+    projectionRootDir: path.resolve(
+      config.cwd,
+      '.rbssr/generated/router-projection/build-manifest',
+    ),
   });
   return adapter.manifest;
 }