react-bun-ssr 0.2.0 → 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

@@ -25,6 +25,21 @@ function log(message: string): void {
   console.log(`[rbssr] ${message}`);
 }
 
+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 }> {
   const userConfig = await loadUserConfig(cwd);
   const resolved = resolveConfig(userConfig, cwd);
@@ -48,41 +63,47 @@ 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,
-  });
+  await withNodeEnv("production", async () => {
+    const userConfig = await loadUserConfig(cwd);
+    const resolved = resolveConfig({
+      ...userConfig,
+      mode: "production",
+    }, 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/",
-  });
+    const routeAssets = await bundleClientEntries({
+      entries,
+      outDir: distClientDir,
+      dev: false,
+      publicPrefix: "/client/",
+    });
 
-  await copyDirRecursive(resolved.publicDir, distClientDir);
+    await copyDirRecursive(resolved.publicDir, distClientDir);
 
-  const buildManifest = createBuildManifest(routeAssets);
-  await writeText(
-    path.join(resolved.distDir, "manifest.json"),
-    JSON.stringify(buildManifest, null, 2),
-  );
+    const buildManifest = createBuildManifest(routeAssets);
+    await writeText(
+      path.join(resolved.distDir, "manifest.json"),
+      JSON.stringify(buildManifest, null, 2),
+    );
 
-  await writeProductionServerEntrypoint({ distDir: resolved.distDir });
+    await writeProductionServerEntrypoint({ distDir: resolved.distDir });
 
-  log(`build complete: ${resolved.distDir}`);
+    log(`build complete: ${resolved.distDir}`);
+  });
 }
 
 export async function runDev(cwd = process.cwd()): Promise<void> {
@@ -121,6 +142,7 @@ export async function runDev(cwd = process.cwd()): Promise<void> {
       stderr: "inherit",
       env: {
         ...process.env,
+        NODE_ENV: "development",
         RBSSR_DEV_LAUNCHER: "1",
         RBSSR_DEV_CHILD: "1",
       },

package/framework/cli/dev-client-watch.ts

@@ -89,6 +89,13 @@ export function createDevClientWatch(options: {
   let metafilePoller: ReturnType<typeof setInterval> | undefined;
   let lastMetafileMtime = "";
 
+  const resetReadyState = (): void => {
+    const deferred = createDeferred();
+    state.readyPromise = deferred.promise;
+    state.resolveReady = deferred.resolve;
+    state.rejectReady = deferred.reject;
+  };
+
   const stopPolling = (): void => {
     if (metafilePoller) {
       clearInterval(metafilePoller);
@@ -152,10 +159,6 @@ export function createDevClientWatch(options: {
     await removePath(options.metafilePath);
 
     const previousOutputFiles = [...state.outputFiles];
-    const deferred = createDeferred();
-    state.readyPromise = deferred.promise;
-    state.resolveReady = deferred.resolve;
-    state.rejectReady = deferred.reject;
     state.buildCount = 0;
     state.outputFiles = new Set<string>();
     lastMetafileMtime = "";
@@ -195,7 +198,10 @@ export function createDevClientWatch(options: {
       stdin: "ignore",
       stdout: "inherit",
       stderr: "inherit",
-      env: process.env,
+      env: {
+        ...process.env,
+        NODE_ENV: "development",
+      },
     });
 
     void state.process.exited.then((exitCode) => {
@@ -244,6 +250,7 @@ export function createDevClientWatch(options: {
       }
 
       state.entrySetSignature = nextEntrySetSignature;
+      resetReadyState();
       await stopProcess();
       await startProcess();
       options.onLog?.("restarted Bun client watch after entry set change");

package/framework/cli/internal.ts

@@ -22,11 +22,14 @@ export function parseFlags(args: string[]): CliFlags {
 
 export function createProductionServerEntrypointSource(): string {
   return `import path from "node:path";
-import config from "../../rbssr.config.ts";
 import { startHttpServer } from "react-bun-ssr";
 
+process.env.NODE_ENV = "production";
+
 const rootDir = path.resolve(path.dirname(Bun.fileURLToPath(import.meta.url)), "../..");
 process.chdir(rootDir);
+const configModule = await import("../../rbssr.config.ts");
+const config = configModule.default;
 
 const manifestPath = path.resolve(rootDir, "dist/manifest.json");
 const manifest = await Bun.file(manifestPath).json();
@@ -53,6 +56,7 @@ export function createDevHotEntrypointSource(options: {
 
   return `import { runHotDevChild } from ${runtimeModulePath};
 
+process.env.NODE_ENV = "development";
 process.chdir(${cwd});
 await runHotDevChild({
   cwd: ${cwd},
@@ -93,8 +97,8 @@ export function createTestCommands(extraArgs: string[]): string[][] {
   }
 
   return [
-    ["bun", "test", "./tests/unit"],
-    ["bun", "test", "./tests/integration"],
+    ["bun", "test", "./tests/framework/unit", "./tests/docs-app/unit"],
+    ["bun", "test", "./tests/framework/integration", "./tests/docs-app/integration"],
     ["bun", "x", "playwright", "test"],
   ];
 }

package/framework/runtime/build-tools.ts

@@ -23,7 +23,6 @@ const BUILD_OPTIMIZE_IMPORTS = [
   'react-bun-ssr/route',
   'react',
   'react-dom',
-  '@datadog/browser-rum-react',
 ];
 
 export interface ClientEntryFile {
@@ -338,6 +337,9 @@ export async function bundleClientEntries(options: {
     sourcemap: dev ? 'inline' : 'external',
     minify: !dev,
     naming: dev ? '[name].[ext]' : '[name]-[hash].[ext]',
+    define: {
+      "process.env.NODE_ENV": JSON.stringify(dev ? "development" : "production"),
+    },
   });
 
   if (!result.success) {

package/framework/runtime/client-runtime.tsx

@@ -60,6 +60,7 @@ interface NavigateOptions {
 interface NavigateResult {
   from: string;
   to: string;
+  nextUrl: URL;
   status: number;
   kind: "page" | "not_found" | "catch" | "error";
   redirected: boolean;
@@ -128,6 +129,16 @@ interface RuntimeState {
   transitionAbortController: AbortController | null;
 }
 
+interface ClientRuntimeSingleton {
+  moduleRegistry: Map<string, RouteModuleBundle>;
+  pendingNavigationTransitions: Map<string, PendingNavigationTransition>;
+  navigationListeners: Set<(info: NavigateResult) => void>;
+  runtimeState: RuntimeState | null;
+  popstateBound: boolean;
+  navigationApiListenerBound: boolean;
+  navigationApiTransitionCounter: number;
+}
+
 declare global {
   interface Window {
     __RBSSR_DEFERRED__?: DeferredClientRuntime;
@@ -137,12 +148,42 @@ declare global {
 const NAVIGATION_API_PENDING_TIMEOUT_MS = 1_500;
 const NAVIGATION_API_PENDING_MATCH_WINDOW_MS = 10_000;
 const ROUTE_ANNOUNCER_ID = "__rbssr-route-announcer";
-const moduleRegistry = new Map<string, RouteModuleBundle>();
-const pendingNavigationTransitions = new Map<string, PendingNavigationTransition>();
-let runtimeState: RuntimeState | null = null;
-let popstateBound = false;
-let navigationApiListenerBound = false;
-let navigationApiTransitionCounter = 0;
+const CLIENT_RUNTIME_SINGLETON_KEY = Symbol.for("react-bun-ssr.client-runtime");
+
+function getClientRuntimeSingleton(): ClientRuntimeSingleton {
+  const globalRegistry = globalThis as typeof globalThis & {
+    [CLIENT_RUNTIME_SINGLETON_KEY]?: ClientRuntimeSingleton;
+  };
+  const existing = globalRegistry[CLIENT_RUNTIME_SINGLETON_KEY];
+  if (existing) {
+    return existing;
+  }
+
+  const singleton: ClientRuntimeSingleton = {
+    moduleRegistry: new Map(),
+    pendingNavigationTransitions: new Map(),
+    navigationListeners: new Set(),
+    runtimeState: null,
+    popstateBound: false,
+    navigationApiListenerBound: false,
+    navigationApiTransitionCounter: 0,
+  };
+  globalRegistry[CLIENT_RUNTIME_SINGLETON_KEY] = singleton;
+  return singleton;
+}
+
+const clientRuntimeSingleton = getClientRuntimeSingleton();
+
+function emitNavigation(info: NavigateResult): void {
+  for (const listener of clientRuntimeSingleton.navigationListeners) {
+    try {
+      listener(info);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.warn("[rbssr] router navigation listener failed", error);
+    }
+  }
+}
 
 function pickOptionalClientModuleExport<T>(
   moduleValue: Record<string, unknown>,
@@ -291,18 +332,18 @@ function readNavigationDestinationHref(event: NavigateEventLike): string | null
 }
 
 function clearPendingNavigationTransition(id: string): void {
-  const entry = pendingNavigationTransitions.get(id);
+  const entry = clientRuntimeSingleton.pendingNavigationTransitions.get(id);
   if (!entry) {
     return;
   }
 
   clearTimeout(entry.timeoutId);
-  pendingNavigationTransitions.delete(id);
+  clientRuntimeSingleton.pendingNavigationTransitions.delete(id);
 }
 
 function findPendingTransitionForEvent(event: NavigateEventLike): PendingNavigationTransition | null {
   if (isFrameworkNavigationInfo(event.info)) {
-    return pendingNavigationTransitions.get(event.info.id) ?? null;
+    return clientRuntimeSingleton.pendingNavigationTransitions.get(event.info.id) ?? null;
   }
 
   if (event.userInitiated) {
@@ -316,7 +357,7 @@ function findPendingTransitionForEvent(event: NavigateEventLike): PendingNavigat
 
   const now = Date.now();
   let bestMatch: PendingNavigationTransition | null = null;
-  for (const candidate of pendingNavigationTransitions.values()) {
+  for (const candidate of clientRuntimeSingleton.pendingNavigationTransitions.values()) {
     if (candidate.destinationHref !== destinationHref) {
       continue;
     }
@@ -359,11 +400,11 @@ function reviveDeferredPayload(payload: RenderPayload): RenderPayload {
 }
 
 function ensureRuntimeState(): RuntimeState {
-  if (!runtimeState) {
+  if (!clientRuntimeSingleton.runtimeState) {
     throw new Error("Client runtime is not initialized. Ensure hydrateInitialRoute() ran first.");
   }
 
-  return runtimeState;
+  return clientRuntimeSingleton.runtimeState;
 }
 
 function createTransitionUrl(toUrl: URL): URL {
@@ -467,7 +508,7 @@ function applyDeferredChunk(chunk: TransitionDeferredChunk): void {
 }
 
 async function ensureRouteModuleLoaded(routeId: string, snapshot: ClientRouterSnapshot): Promise<void> {
-  if (moduleRegistry.has(routeId)) {
+  if (clientRuntimeSingleton.moduleRegistry.has(routeId)) {
     return;
   }
 
@@ -810,6 +851,7 @@ async function renderTransitionInitial(
   return {
     from: options.fromPath,
     to: toUrl.pathname + toUrl.search + toUrl.hash,
+    nextUrl: new URL(toUrl.toString()),
     status: chunk.status,
     kind: chunk.kind,
     redirected: options.redirected ?? false,
@@ -941,6 +983,7 @@ async function navigateToInternal(
       fromPath: currentPath,
     });
     options.onNavigate?.(result);
+    emitNavigation(result);
     return result;
   } catch {
     hardNavigate(toUrl);
@@ -953,8 +996,8 @@ async function navigateToInternal(
 }
 
 function nextNavigationTransitionId(): string {
-  navigationApiTransitionCounter += 1;
-  return `rbssr-nav-${Date.now()}-${navigationApiTransitionCounter}`;
+  clientRuntimeSingleton.navigationApiTransitionCounter += 1;
+  return `rbssr-nav-${Date.now()}-${clientRuntimeSingleton.navigationApiTransitionCounter}`;
 }
 
 function settlePendingNavigationTransition(
@@ -971,7 +1014,7 @@ function settlePendingNavigationTransition(
 }
 
 function cancelPendingNavigationTransition(id: string): void {
-  const pending = pendingNavigationTransitions.get(id);
+  const pending = clientRuntimeSingleton.pendingNavigationTransitions.get(id);
   if (!pending || pending.settled) {
     return;
   }
@@ -1007,7 +1050,7 @@ function createPendingNavigationTransition(options: {
 }): Promise<NavigateResult | null> {
   return new Promise(resolve => {
     const timeoutId = window.setTimeout(() => {
-      const pending = pendingNavigationTransitions.get(options.id);
+      const pending = clientRuntimeSingleton.pendingNavigationTransitions.get(options.id);
       if (!pending || pending.settled) {
         return;
       }
@@ -1023,7 +1066,7 @@ function createPendingNavigationTransition(options: {
       });
     }, NAVIGATION_API_PENDING_TIMEOUT_MS);
 
-    pendingNavigationTransitions.set(options.id, {
+    clientRuntimeSingleton.pendingNavigationTransitions.set(options.id, {
       id: options.id,
       destinationHref: options.toUrl.toString(),
       replace: options.replace,
@@ -1038,7 +1081,7 @@ function createPendingNavigationTransition(options: {
 }
 
 function bindNavigationApiNavigateListener(): void {
-  if (navigationApiListenerBound || typeof window === "undefined") {
+  if (clientRuntimeSingleton.navigationApiListenerBound || typeof window === "undefined") {
     return;
   }
 
@@ -1098,15 +1141,15 @@ function bindNavigationApiNavigateListener(): void {
     return;
   }
 
-  navigationApiListenerBound = true;
+  clientRuntimeSingleton.navigationApiListenerBound = true;
 }
 
 function bindPopstate(): void {
-  if (popstateBound || typeof window === "undefined") {
+  if (clientRuntimeSingleton.popstateBound || typeof window === "undefined") {
     return;
   }
 
-  popstateBound = true;
+  clientRuntimeSingleton.popstateBound = true;
   window.addEventListener("popstate", () => {
     const targetUrl = new URL(window.location.href);
     void navigateToInternal(targetUrl, {
@@ -1122,10 +1165,10 @@ export async function prefetchTo(to: string): Promise<void> {
     return;
   }
 
-  if (!runtimeState) {
+  if (!clientRuntimeSingleton.runtimeState) {
     return;
   }
-  const state = runtimeState;
+  const state = clientRuntimeSingleton.runtimeState;
   const toUrl = new URL(to, window.location.href);
   if (!isInternalUrl(toUrl)) {
     return;
@@ -1150,7 +1193,7 @@ export async function navigateWithNavigationApiOrFallback(
     return null;
   }
 
-  if (!runtimeState) {
+  if (!clientRuntimeSingleton.runtimeState) {
     hardNavigate(toUrl);
     return null;
   }
@@ -1205,7 +1248,7 @@ export async function navigateTo(to: string, options: NavigateOptions = {}): Pro
     return null;
   }
 
-  if (!runtimeState) {
+  if (!clientRuntimeSingleton.runtimeState) {
     hardNavigate(toUrl);
     return null;
   }
@@ -1213,21 +1256,28 @@ export async function navigateTo(to: string, options: NavigateOptions = {}): Pro
   return navigateToInternal(toUrl, options);
 }
 
+export function subscribeToNavigation(listener: (info: NavigateResult) => void): () => void {
+  clientRuntimeSingleton.navigationListeners.add(listener);
+  return () => {
+    clientRuntimeSingleton.navigationListeners.delete(listener);
+  };
+}
+
 export function registerRouteModules(routeId: string, modules: RouteModuleBundle): void {
-  moduleRegistry.set(routeId, modules);
-  if (runtimeState) {
-    runtimeState.moduleRegistry.set(routeId, modules);
+  clientRuntimeSingleton.moduleRegistry.set(routeId, modules);
+  if (clientRuntimeSingleton.runtimeState) {
+    clientRuntimeSingleton.runtimeState.moduleRegistry.set(routeId, modules);
   }
 }
 
 export function hydrateInitialRoute(routeId: string): void {
-  if (typeof document === "undefined" || runtimeState) {
+  if (typeof document === "undefined" || clientRuntimeSingleton.runtimeState) {
     return;
   }
 
   const payload = reviveDeferredPayload(getScriptJson<RenderPayload>(RBSSR_PAYLOAD_SCRIPT_ID));
   const routerSnapshot = getScriptJson<ClientRouterSnapshot>(RBSSR_ROUTER_SCRIPT_ID);
-  const modules = moduleRegistry.get(routeId);
+  const modules = clientRuntimeSingleton.moduleRegistry.get(routeId);
   if (!modules) {
     throw new Error(`Missing module registry for initial route "${routeId}"`);
   }
@@ -1247,13 +1297,13 @@ export function hydrateInitialRoute(routeId: string): void {
   }
 
   const root = hydrateRoot(container, appTree);
-  runtimeState = {
+  clientRuntimeSingleton.runtimeState = {
     root,
     currentPayload: payload,
     currentRouteId: routeId,
     currentModules: modules,
     routerSnapshot,
-    moduleRegistry,
+    moduleRegistry: clientRuntimeSingleton.moduleRegistry,
     prefetchCache: new Map(),
     navigationToken: 0,
     transitionAbortController: null,

package/framework/runtime/config.ts

@@ -71,15 +71,20 @@ function toHeaderRules(config: FrameworkConfig): ResolvedResponseHeaderRule[] {
       throw new Error(`[rbssr config] \`headers[${index}].headers\` must include at least one header.`);
     }
 
-    const headers: Record<string, string> = {};
+    const headers: Record<string, string | null> = {};
     for (const [key, value] of entries) {
       if (typeof key !== "string" || key.trim().length === 0) {
         throw new Error(`[rbssr config] \`headers[${index}].headers\` contains an empty header name.`);
       }
 
+      if (value === null) {
+        headers[key] = null;
+        continue;
+      }
+
       if (typeof value !== "string" || value.trim().length === 0) {
         throw new Error(
-          `[rbssr config] \`headers[${index}].headers.${key}\` must be a non-empty string value.`,
+          `[rbssr config] \`headers[${index}].headers.${key}\` must be a non-empty string value or null.`,
         );
       }
 

package/framework/runtime/index.ts

@@ -26,5 +26,5 @@ export { createServer, startHttpServer } from "./server";
 export { defer, json, redirect, defineConfig } from "./helpers";
 export { isRouteErrorResponse, notFound, routeError } from "./route-errors";
 export { Link, type LinkProps } from "./link";
-export { useRouter, type Router, type RouterNavigateOptions } from "./router";
+export { useRouter, type Router, type RouterNavigateInfo, type RouterNavigateListener, type RouterNavigateOptions } from "./router";
 export { Outlet, useLoaderData, useParams, useRequestUrl, useRouteError } from "./tree";

package/framework/runtime/link.tsx

@@ -4,15 +4,7 @@ import type {
   MouseEvent,
   TouchEvent,
 } from "react";
-
-interface NavigateInfo {
-  from: string;
-  to: string;
-  status: number;
-  kind: "page" | "not_found" | "catch" | "error";
-  redirected: boolean;
-  prefetched: boolean;
-}
+import type { RouterNavigateInfo } from "./router";
 
 export interface LinkProps
   extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
@@ -20,7 +12,7 @@ export interface LinkProps
   replace?: boolean;
   scroll?: boolean;
   prefetch?: "intent" | "none";
-  onNavigate?: (info: NavigateInfo) => void;
+  onNavigate?: (info: RouterNavigateInfo) => void;
 }
 
 function shouldHandleNavigation(event: MouseEvent<HTMLAnchorElement>): boolean {
@@ -89,7 +81,7 @@ async function prefetch(href: string): Promise<void> {
 async function navigate(href: string, options: {
   replace?: boolean;
   scroll?: boolean;
-  onNavigate?: (info: NavigateInfo) => void;
+  onNavigate?: (info: RouterNavigateInfo) => void;
 }): Promise<void> {
   if (typeof window === "undefined") {
     return;

package/framework/runtime/module-loader.ts

@@ -29,21 +29,26 @@ export interface RouteModuleLoadOptions {
   cacheBustKey?: string;
   serverBytecode?: boolean;
   devSourceImports?: boolean;
+  nodeEnv?: "development" | "production";
 }
 
 export function createServerModuleCacheKey(options: {
   absoluteFilePath: string;
   cacheBustKey?: string;
   serverBytecode: boolean;
+  nodeEnv?: "development" | "production";
 }): string {
-  return `${options.absoluteFilePath}|${options.cacheBustKey ?? 'prod'}|bytecode:${options.serverBytecode ? '1' : '0'}|bun:${Bun.version}`;
+  const nodeEnv = options.nodeEnv ?? (process.env.NODE_ENV === "production" ? "production" : "development");
+  return `${options.absoluteFilePath}|${options.cacheBustKey ?? 'prod'}|bytecode:${options.serverBytecode ? '1' : '0'}|env:${nodeEnv}|bun:${Bun.version}`;
 }
 
 export function createServerBuildConfig(options: {
   absoluteFilePath: string;
   outDir: string;
   serverBytecode: boolean;
+  nodeEnv?: "development" | "production";
 }): Bun.BuildConfig {
+  const nodeEnv = options.nodeEnv ?? (process.env.NODE_ENV === "production" ? "production" : "development");
   return {
     entrypoints: [options.absoluteFilePath],
     outdir: options.outDir,
@@ -56,6 +61,9 @@ export function createServerBuildConfig(options: {
     minify: false,
     naming: 'entry-[hash].[ext]',
     external: SERVER_BUILD_EXTERNAL,
+    define: {
+      "process.env.NODE_ENV": JSON.stringify(nodeEnv),
+    },
   };
 }
 
@@ -128,10 +136,12 @@ async function buildServerModule(
 
   const cacheBustKey = options.cacheBustKey;
   const serverBytecode = options.serverBytecode ?? true;
+  const nodeEnv = options.nodeEnv ?? (process.env.NODE_ENV === "production" ? "production" : "development");
   const cacheKey = createServerModuleCacheKey({
     absoluteFilePath,
     cacheBustKey,
     serverBytecode,
+    nodeEnv,
   });
   const existing = serverBundlePathCache.get(cacheKey);
   if (existing) {
@@ -153,6 +163,7 @@ async function buildServerModule(
         absoluteFilePath,
         outDir,
         serverBytecode,
+        nodeEnv,
       }),
     );
 
@@ -169,6 +180,7 @@ async function buildServerModule(
           absoluteFilePath,
           outDir,
           serverBytecode: false,
+          nodeEnv,
         }),
       );
 

package/framework/runtime/render.tsx

@@ -1,6 +1,7 @@
 import {
   Children,
   cloneElement,
+  Fragment,
   isValidElement,
   Suspense,
   use,
@@ -29,6 +30,50 @@ import {
   createPageAppTree,
 } from "./tree";
 
+function isTitleElement(node: ReactNode): node is ReactElement {
+  return isValidElement(node) && node.type === "title";
+}
+
+function isMetaElement(node: ReactNode): node is ReactElement {
+  return isValidElement(node) && node.type === "meta";
+}
+
+function getMetaDedupeKey(node: ReactNode): string | null {
+  if (!isMetaElement(node)) {
+    return null;
+  }
+
+  const props = node.props as {
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+    charSet?: string;
+    itemProp?: string;
+  };
+
+  if (typeof props.name === "string" && props.name.length > 0) {
+    return `name:${props.name}`;
+  }
+
+  if (typeof props.property === "string" && props.property.length > 0) {
+    return `property:${props.property}`;
+  }
+
+  if (typeof props.httpEquiv === "string" && props.httpEquiv.length > 0) {
+    return `httpEquiv:${props.httpEquiv}`;
+  }
+
+  if (typeof props.itemProp === "string" && props.itemProp.length > 0) {
+    return `itemProp:${props.itemProp}`;
+  }
+
+  if (props.charSet !== undefined) {
+    return "charSet";
+  }
+
+  return null;
+}
+
 export function renderPageApp(modules: RouteModuleBundle, payload: RenderPayload): string {
   return renderToString(createPageAppTree(modules, payload));
 }
@@ -84,6 +129,27 @@ function normalizeTitleChildren(node: ReactNode): ReactNode {
   return cloneElement(node, undefined, nextChildren);
 }
 
+function expandHeadNodes(node: ReactNode): ReactNode[] {
+  if (Array.isArray(node)) {
+    return node.flatMap(value => expandHeadNodes(value));
+  }
+
+  if (node === null || node === undefined || typeof node === "boolean") {
+    return [];
+  }
+
+  if (!isValidElement(node)) {
+    return [node];
+  }
+
+  if (node.type === Fragment) {
+    const props = node.props as { children?: ReactNode };
+    return Children.toArray(props.children).flatMap(child => expandHeadNodes(child));
+  }
+
+  return [node];
+}
+
 function moduleHeadToElements(moduleValue: RouteModule, payload: RenderPayload, keyPrefix: string): ReactNode[] {
   const tags: ReactNode[] = [];
 
@@ -99,7 +165,7 @@ function moduleHeadToElements(moduleValue: RouteModule, payload: RenderPayload,
     if (typeof headResult === "string") {
       tags.push(<title key={`${keyPrefix}:title`}>{headResult}</title>);
     } else if (headResult !== null && headResult !== undefined) {
-      const nodes = Children.toArray(normalizeTitleChildren(headResult));
+      const nodes = expandHeadNodes(normalizeTitleChildren(headResult));
       for (let index = 0; index < nodes.length; index += 1) {
         const node = nodes[index]!;
         if (isValidElement(node)) {
@@ -122,11 +188,37 @@ function moduleHeadToElements(moduleValue: RouteModule, payload: RenderPayload,
 }
 
 export function collectHeadElements(modules: RouteModuleBundle, payload: RenderPayload): ReactNode[] {
-  return [
+  const elements = [
     ...moduleHeadToElements(modules.root, payload, "root"),
     ...modules.layouts.flatMap((layout, index) => moduleHeadToElements(layout, payload, `layout:${index}`)),
     ...moduleHeadToElements(modules.route, payload, "route"),
   ];
+
+  let lastTitleIndex = -1;
+  const lastMetaIndexes = new Map<string, number>();
+  for (let index = 0; index < elements.length; index += 1) {
+    if (isTitleElement(elements[index])) {
+      lastTitleIndex = index;
+    }
+
+    const metaKey = getMetaDedupeKey(elements[index]);
+    if (metaKey) {
+      lastMetaIndexes.set(metaKey, index);
+    }
+  }
+
+  return elements.filter((element, index) => {
+    if (isTitleElement(element)) {
+      return lastTitleIndex === -1 || index === lastTitleIndex;
+    }
+
+    const metaKey = getMetaDedupeKey(element);
+    if (metaKey) {
+      return lastMetaIndexes.get(metaKey) === index;
+    }
+
+    return true;
+  });
 }
 
 export function collectHeadMarkup(modules: RouteModuleBundle, payload: RenderPayload): string {

package/framework/runtime/route-api.ts

@@ -19,5 +19,5 @@ export type {
 export { defer, json, redirect } from "./helpers";
 export { isRouteErrorResponse, notFound, routeError } from "./route-errors";
 export { Link, type LinkProps } from "./link";
-export { useRouter, type Router, type RouterNavigateOptions } from "./router";
+export { useRouter, type Router, type RouterNavigateInfo, type RouterNavigateListener, type RouterNavigateOptions } from "./router";
 export { Outlet, useLoaderData, useParams, useRequestUrl, useRouteError } from "./tree";

package/framework/runtime/router.ts

@@ -1,10 +1,36 @@
-import { useMemo } from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
 import { goBack, goForward, reloadPage } from "./navigation-api";
 
 export interface RouterNavigateOptions {
   scroll?: boolean;
 }
 
+export interface RouterNavigateInfo {
+  from: string;
+  to: string;
+  nextUrl: URL;
+  status: number;
+  kind: "page" | "not_found" | "catch" | "error";
+  redirected: boolean;
+  prefetched: boolean;
+}
+
+export type RouterNavigateListener = (nextUrl: URL) => void;
+
+export function notifyRouterNavigateListeners(
+  listeners: readonly RouterNavigateListener[],
+  nextUrl: URL,
+): void {
+  for (const listener of listeners) {
+    try {
+      listener(nextUrl);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.warn("[rbssr] router onNavigate listener failed", error);
+    }
+  }
+}
+
 export interface Router {
   push(href: string, options?: RouterNavigateOptions): void;
   replace(href: string, options?: RouterNavigateOptions): void;
@@ -12,6 +38,7 @@ export interface Router {
   back(): void;
   forward(): void;
   refresh(): void;
+  onNavigate(listener: RouterNavigateListener): void;
 }
 
 function toAbsoluteHref(href: string): string {
@@ -28,9 +55,10 @@ const SERVER_ROUTER: Router = {
   back: () => undefined,
   forward: () => undefined,
   refresh: () => undefined,
+  onNavigate: () => undefined,
 };
 
-function createClientRouter(): Router {
+function createClientRouter(onNavigate: Router["onNavigate"]): Router {
   return {
     push: (href, options) => {
       const absoluteHref = toAbsoluteHref(href);
@@ -69,12 +97,55 @@ function createClientRouter(): Router {
     refresh: () => {
       reloadPage();
     },
+    onNavigate,
   };
 }
 
 export function useRouter(): Router {
+  const navigateListenersRef = useRef<RouterNavigateListener[]>([]);
+  const didEmitInitialNavigationRef = useRef(false);
+  navigateListenersRef.current = [];
+
+  const onNavigate = useCallback<Router["onNavigate"]>((listener) => {
+    navigateListenersRef.current.push(listener);
+  }, []);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    if (!didEmitInitialNavigationRef.current) {
+      didEmitInitialNavigationRef.current = true;
+      notifyRouterNavigateListeners(
+        navigateListenersRef.current,
+        new URL(window.location.href),
+      );
+    }
+
+    let unsubscribe: () => void = () => undefined;
+    let active = true;
+
+    void import("./client-runtime")
+      .then(runtime => {
+        if (!active) {
+          return;
+        }
+
+        unsubscribe = runtime.subscribeToNavigation((info) => {
+          notifyRouterNavigateListeners(navigateListenersRef.current, info.nextUrl);
+        });
+      })
+      .catch(() => undefined);
+
+    return () => {
+      active = false;
+      unsubscribe();
+    };
+  }, []);
+
   return useMemo(
-    () => (typeof window === "undefined" ? SERVER_ROUTER : createClientRouter()),
-    [],
+    () => (typeof window === "undefined" ? SERVER_ROUTER : createClientRouter(onNavigate)),
+    [onNavigate],
   );
 }

package/framework/runtime/server.ts

@@ -227,6 +227,11 @@ function applyConfiguredHeaders(options: {
     }
 
     for (const [name, value] of Object.entries(rule.headers)) {
+      if (value === null) {
+        headers.delete(name);
+        continue;
+      }
+
       headers.set(name, value);
     }
   }
@@ -630,15 +635,18 @@ export function createServer(
 
     const routeAdapter = await getRouteAdapter(activeConfig);
     const devCacheBustKey = dev ? String(runtimeOptions.reloadVersion?.() ?? 0) : undefined;
+    const nodeEnv: "development" | "production" = dev ? "development" : "production";
     const routeModuleLoadOptions = {
       cacheBustKey: devCacheBustKey,
       serverBytecode: activeConfig.serverBytecode,
       devSourceImports: false,
+      nodeEnv,
     };
     const requestModuleLoadOptions = {
       cacheBustKey: undefined,
       serverBytecode: activeConfig.serverBytecode,
       devSourceImports: dev,
+      nodeEnv,
     };
     const routeAssetsById = resolveAllRouteAssets({
       dev,

package/framework/runtime/tree.tsx

@@ -2,6 +2,7 @@ import {
   createContext,
   useContext,
   type ComponentType,
+  type Context,
   type ReactElement,
   type ReactNode,
 } from "react";
@@ -15,8 +16,29 @@ interface RuntimeState {
   reset: () => void;
 }
 
-const RuntimeContext = createContext<RuntimeState | null>(null);
-const OutletContext = createContext<ReactNode>(null);
+const RUNTIME_CONTEXT_KEY = Symbol.for("react-bun-ssr.runtime-context");
+const OUTLET_CONTEXT_KEY = Symbol.for("react-bun-ssr.outlet-context");
+
+function getGlobalContext<T>(key: symbol, createValue: () => Context<T>): Context<T> {
+  const globalRegistry = globalThis as typeof globalThis & { [contextKey: symbol]: Context<T> | undefined };
+  const existing = globalRegistry[key];
+  if (existing) {
+    return existing;
+  }
+
+  const context = createValue();
+  globalRegistry[key] = context;
+  return context;
+}
+
+const RuntimeContext = getGlobalContext<RuntimeState | null>(
+  RUNTIME_CONTEXT_KEY,
+  () => createContext<RuntimeState | null>(null),
+);
+const OutletContext = getGlobalContext<ReactNode>(
+  OUTLET_CONTEXT_KEY,
+  () => createContext<ReactNode>(null),
+);
 const NOOP_RESET = () => undefined;
 
 function useRuntimeState(): RuntimeState {

package/framework/runtime/types.ts

@@ -123,7 +123,7 @@ export interface ApiRouteModule {
 
 export interface ResponseHeaderRule {
   source: string;
-  headers: Record<string, string>;
+  headers: Record<string, string | null>;
 }
 
 export interface ResolvedResponseHeaderRule extends ResponseHeaderRule {

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "react-bun-ssr",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
+  "workspaces": [
+    "app"
+  ],
   "types": "./framework/runtime/index.ts",
   "repository": {
     "type": "git",
@@ -44,10 +47,16 @@
     "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:consumer": "RBSSR_RUN_CONSUMER_SMOKE=1 bun test ./tests/integration/package-smoke.test.ts",
+    "test:unit": "bun test ./tests/framework/unit ./tests/docs-app/unit",
+    "test:integration": "bun test ./tests/framework/integration ./tests/docs-app/integration",
+    "test:consumer": "RBSSR_RUN_CONSUMER_SMOKE=1 bun test ./tests/framework/integration/package-smoke.test.ts",
+    "test:watch": "bunx chokidar-cli \"framework/**/*\" \"app/**/*\" \"scripts/**/*\" \"tests/**/*\" -c \"bun run test:unit && bun run test:integration\"",
+    "test:watch:framework:unit": "bunx chokidar-cli \"framework/**/*\" \"scripts/**/*\" \"tests/framework/unit/**/*\" \"tests/framework/helpers/**/*\" -c \"bun test ./tests/framework/unit\"",
+    "test:watch:framework:integration": "bunx chokidar-cli \"framework/**/*\" \"scripts/**/*\" \"tests/framework/integration/**/*\" \"tests/framework/helpers/**/*\" \"app/**/*\" -c \"bun test ./tests/framework/integration\"",
+    "test:watch:docs-app:unit": "bunx chokidar-cli \"app/**/*\" \"tests/docs-app/unit/**/*\" -c \"bun test ./tests/docs-app/unit\"",
+    "test:watch:docs-app:integration": "bunx chokidar-cli \"app/**/*\" \"scripts/**/*\" \"tests/docs-app/integration/**/*\" -c \"bun test ./tests/docs-app/integration\"",
     "test:e2e": "bunx playwright test",
+    "test:e2e:ui": "bunx playwright test --ui",
     "docs:dev": "bun run scripts/generate-api-docs.ts && bun run scripts/build-docs-manifest.ts && bun run scripts/build-search-index.ts && bun run scripts/build-blog-manifest.ts && bun run scripts/build-sitemap.ts && bun bin/rbssr.ts dev",
     "docs:build": "bun run scripts/docs-build.ts",
     "docs:check": "bun run scripts/check-docs.ts",
@@ -65,9 +74,5 @@
     "react": "^19",
     "react-dom": "^19",
     "typescript": "^5.9.2"
-  },
-  "dependencies": {
-    "@datadog/browser-rum": "^6.28.1",
-    "@datadog/browser-rum-react": "^6.28.1"
   }
 }