react-bun-ssr 0.1.1 → 0.3.0

package/README.md

@@ -2,9 +2,9 @@
 
 `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
-- API reference: https://react-bun-ssr.fly.dev/docs/api/overview
-- Blog: https://react-bun-ssr.fly.dev/blog
+- Documentation: https://react-bun-ssr.dev/docs
+- API reference: https://react-bun-ssr.dev/docs/api/overview
+- Blog: https://react-bun-ssr.dev/blog
 - Repository: https://github.com/react-formation/react-bun-ssr
 
 ## Why react-bun-ssr?
@@ -50,7 +50,7 @@ http://127.0.0.1:3000
 
 For the full setup walkthrough, read the installation guide:
 
-- https://react-bun-ssr.fly.dev/docs/start/installation
+- https://react-bun-ssr.dev/docs/start/installation
 
 ## What `rbssr init` gives you
 
@@ -75,7 +75,7 @@ rbssr.config.ts
 
 The quickest follow-up is:
 
-- https://react-bun-ssr.fly.dev/docs/start/quick-start
+- https://react-bun-ssr.dev/docs/start/quick-start
 
 ## How it works
 
@@ -85,7 +85,7 @@ Routes live under `app/routes`. Page routes, API routes, dynamic params, and mar
 
 Read more:
 
-- https://react-bun-ssr.fly.dev/docs/routing/file-based-routing
+- https://react-bun-ssr.dev/docs/routing/file-based-routing
 
 ### Request pipeline
 
@@ -93,8 +93,8 @@ For a page request, the framework resolves the matching route, runs global and n
 
 Read more:
 
-- https://react-bun-ssr.fly.dev/docs/routing/middleware
-- https://react-bun-ssr.fly.dev/docs/data/loaders
+- https://react-bun-ssr.dev/docs/routing/middleware
+- https://react-bun-ssr.dev/docs/data/loaders
 
 ### Rendering model
 
@@ -102,8 +102,8 @@ SSR is the default model. HTML responses stream, deferred loader data is support
 
 Read more:
 
-- https://react-bun-ssr.fly.dev/docs/rendering/streaming-deferred
-- https://react-bun-ssr.fly.dev/docs/routing/navigation
+- https://react-bun-ssr.dev/docs/rendering/streaming-deferred
+- https://react-bun-ssr.dev/docs/routing/navigation
 
 ### Bun-first runtime
 
@@ -111,7 +111,7 @@ Bun provides the runtime, server, bundler, markdown support, and file APIs that
 
 Read more:
 
-- https://react-bun-ssr.fly.dev/docs/api/bun-runtime-apis
+- https://react-bun-ssr.dev/docs/api/bun-runtime-apis
 
 ## Core commands
 
@@ -132,7 +132,7 @@ Repository maintenance commands:
 
 CLI reference:
 
-- https://react-bun-ssr.fly.dev/docs/tooling/cli
+- https://react-bun-ssr.dev/docs/tooling/cli
 
 ## Working on this repository
 
@@ -147,16 +147,24 @@ bun run docs:dev
 
 That starts the docs site locally using the framework itself.
 
+Dependency ownership is split intentionally:
+
+- the repo-root `package.json` is the published framework manifest
+- [`app/package.json`](/Users/react-formation/code/my-app/app/package.json) owns docs-app runtime dependencies
+
+Contributors should still use the repo-root commands; the workspace split is there to keep npm package metadata accurate, not to change the day-to-day workflow.
+
 ## Project layout
 
 - `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/package.json`: private docs-app dependency manifest
 - `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
+- `tests/framework/`: framework runtime, CLI, build, unit/integration, and framework Playwright tests
+- `tests/docs-app/`: docs site, blog, analytics, and docs-app Playwright tests
 
 ## Contributing
 
@@ -184,6 +192,6 @@ fly deploy
 
 Full deployment docs:
 
-- 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
+- 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/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,10 +25,19 @@ function log(message: string): void {
   console.log(`[rbssr] ${message}`);
 }
 
-function parseFlags(args: string[]): { force: boolean } {
-  return {
-    force: args.includes("--force"),
-  };
+async function withNodeEnv<T>(nodeEnv: "development" | "production", run: () => Promise<T>): Promise<T> {
+  const previousNodeEnv = process.env.NODE_ENV;
+  process.env.NODE_ENV = nodeEnv;
+
+  try {
+    return await run();
+  } finally {
+    if (previousNodeEnv === undefined) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = previousNodeEnv;
+    }
+  }
 }
 
 async function getConfig(cwd: string): Promise<{ userConfig: FrameworkConfig; resolved: ResolvedConfig }> {
@@ -37,29 +51,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> {
@@ -71,238 +63,109 @@ export async function runInit(args: string[], cwd = process.cwd()): Promise<void
 }
 
 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;
-    }
+  await withNodeEnv("production", async () => {
+    const userConfig = await loadUserConfig(cwd);
+    const resolved = resolveConfig({
+      ...userConfig,
+      mode: "production",
+    }, cwd);
 
-    signature = nextSignature;
+    const distClientDir = path.join(resolved.distDir, "client");
+    const generatedDir = path.resolve(cwd, ".rbssr/generated/client-entries");
 
-    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),
+      ensureCleanDirectory(resolved.distDir),
+      ensureCleanDirectory(generatedDir),
     ]);
 
-    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 routeManifest = await buildRouteManifest(resolved);
     const entries = await generateClientEntries({
-      config: snapshotConfig,
-      manifest,
+      config: resolved,
+      manifest: routeManifest,
       generatedDir,
     });
 
-    await ensureCleanDirectory(devClientDir);
-
-    routeAssets = await bundleClientEntries({
+    const routeAssets = await bundleClientEntries({
       entries,
-      outDir: devClientDir,
-      dev: true,
-      publicPrefix: "/__rbssr/client/",
+      outDir: distClientDir,
+      dev: false,
+      publicPrefix: "/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 copyDirRecursive(resolved.publicDir, distClientDir);
 
-  await enqueueRebuild(true);
-
-  let rebuildTimer: ReturnType<typeof setTimeout> | undefined;
-  const scheduleRebuild = (): void => {
-    if (rebuildTimer) {
-      clearTimeout(rebuildTimer);
-    }
+    const buildManifest = createBuildManifest(routeAssets);
+    await writeText(
+      path.join(resolved.distDir, "manifest.json"),
+      JSON.stringify(buildManifest, null, 2),
+    );
 
-    rebuildTimer = setTimeout(() => {
-      rebuildTimer = undefined;
-      void enqueueRebuild(false);
-    }, 75);
-  };
+    await writeProductionServerEntrypoint({ distDir: resolved.distDir });
 
-  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`);
-    }
-  }
+    log(`build complete: ${resolved.distDir}`);
+  });
+}
 
-  const cleanup = (): void => {
-    if (rebuildTimer) {
-      clearTimeout(rebuildTimer);
-      rebuildTimer = undefined;
-    }
-    for (const watcher of watchers) {
-      watcher.close();
-    }
+export async function runDev(cwd = process.cwd()): Promise<void> {
+  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);
   };
 
   process.once("SIGINT", () => {
-    cleanup();
-    process.exit(0);
+    forwardSignal("SIGINT");
   });
 
   process.once("SIGTERM", () => {
-    cleanup();
-    process.exit(0);
+    forwardSignal("SIGTERM");
   });
 
-  const server = createServer(
-    {
-      ...userConfig,
-      mode: "development",
-    },
-    {
-      dev: true,
-      getDevAssets: () => routeAssets,
-      reloadVersion: () => version,
-      subscribeReload: listener => {
-        reloadListeners.add(listener);
-        return () => {
-          reloadListeners.delete(listener);
-        };
+  while (true) {
+    activeChild = Bun.spawn({
+      cmd: ["bun", "--hot", generatedEntryPath],
+      cwd,
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: {
+        ...process.env,
+        NODE_ENV: "development",
+        RBSSR_DEV_LAUNCHER: "1",
+        RBSSR_DEV_CHILD: "1",
       },
-      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,
-  });
+    });
+
+    const exitCode = await activeChild.exited;
+    activeChild = null;
 
-  log(`dev server listening on ${bunServer.url}`);
+    if (shuttingDown) {
+      return;
+    }
+
+    if (exitCode === RBSSR_DEV_RESTART_EXIT_CODE) {
+      log("restarting dev child after config change");
+      continue;
+    }
+
+    if (exitCode !== 0) {
+      process.exit(exitCode);
+    }
+
+    return;
+  }
 }
 
 export async function runStart(cwd = process.cwd()): Promise<void> {
@@ -328,16 +191,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"]);
 }