@bractjs/bractjs 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",

package/src/build/bundler.ts

@@ -102,7 +102,7 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
   }
 
   // ── 5. Write manifest ──────────────────────────────────────────────────
-  const manifest = generateManifest({ clientEntry, rootChunk, routeChunks });
+  const manifest = generateManifest({ clientEntry, rootChunk, routeChunks, mode: "production" });
   await writeManifest(manifest, "build");
   console.log("[bract] build complete →", Object.keys(manifest.routes).length, "routes");
 }

package/src/build/manifest.ts

@@ -9,6 +9,8 @@ export interface RouteManifestEntry {
 
 export interface RouteManifest {
   version: 1;
+  /** "production" = produced by `bractjs build`. Absent on dev-rebuilder manifests. */
+  mode?: "production";
   clientEntry: string;
   rootChunk?: string;
   routes: Record<string, RouteManifestEntry>;
@@ -29,12 +31,13 @@ export function generateManifest(opts: {
   clientEntry: string;
   rootChunk?: string;
   routeChunks: Map<string, string>;
+  mode?: "production";
 }): RouteManifest {
   const routes: Record<string, RouteManifestEntry> = {};
   for (const [pattern, chunk] of opts.routeChunks) {
     routes[pattern] = { chunk, pattern };
   }
-  return { version: 1, clientEntry: opts.clientEntry, rootChunk: opts.rootChunk, routes };
+  return { version: 1, mode: opts.mode, clientEntry: opts.clientEntry, rootChunk: opts.rootChunk, routes };
 }
 
 /**

package/src/client/components/LiveReload.tsx

@@ -1,12 +1,21 @@
 import { type ReactElement } from "react";
 import { hmrClientScript } from "../../dev/hmr-client.ts";
+import { isDevRuntime } from "../../server/env.ts";
 
 /**
  * Renders an inline WebSocket HMR client in development.
  * Returns null in production.
+ *
+ * Two gates:
+ *  1. Build-time `process.env.NODE_ENV === "production"` — strips the script from
+ *     the client bundle entirely (Bun substitutes this define at build time).
+ *  2. Runtime `isDevRuntime()` — kills SSR injection unless the server was
+ *     actually started via `bractjs dev`. Prevents `NODE_ENV=development
+ *     bractjs start` from shipping an HMR client that retries WS forever.
  */
 export function LiveReload(): ReactElement | null {
   if (process.env.NODE_ENV === "production") return null;
+  if (!isDevRuntime()) return null;
 
   // SECURITY(low): dangerouslySetInnerHTML is safe here — hmrClientScript is a
   // build-time constant string with no user input. The NODE_ENV gate above

package/src/dev/server.ts

@@ -1,10 +1,15 @@
 import { createServer } from "../server/serve.ts";
+import { setRuntimeMode } from "../server/env.ts";
 import { createHmrServer } from "./hmr-server.ts";
 import { watchApp } from "./watcher.ts";
 import { rebuildClient } from "./rebuilder.ts";
 import { filePathToPattern } from "../server/scanner.ts";
 import { basename, extname } from "node:path";
 
+// Must precede any user-code import so SSR-time isDevRuntime() checks
+// (e.g. inside <LiveReload>) observe the dev mode.
+setRuntimeMode("dev");
+
 const hmr = createHmrServer(3001);
 
 // Build client bundle before the HTTP server starts accepting requests

package/src/server/env.ts

@@ -2,6 +2,24 @@ export function isDev(): boolean {
   return Bun.env.NODE_ENV !== "production";
 }
 
+/**
+ * Runtime mode — what the server is actually doing, independent of NODE_ENV.
+ * `bractjs dev` sets this to "dev". `bractjs start` leaves it at "prod".
+ *
+ * Use this (not isDev()) to gate dev-only behavior like HMR injection or
+ * re-reading the route manifest on every request. NODE_ENV alone is unreliable:
+ * a user running `NODE_ENV=development bractjs start` would otherwise get a
+ * production server that still ships an HMR client trying to reconnect to a
+ * non-existent ws://localhost:3001 forever.
+ */
+let _runtimeMode: "dev" | "prod" = "prod";
+export function setRuntimeMode(m: "dev" | "prod"): void {
+  _runtimeMode = m;
+}
+export function isDevRuntime(): boolean {
+  return _runtimeMode === "dev";
+}
+
 /**
  * Strict "is development?" check used to gate sensitive output (error
  * messages, stack traces) that would otherwise leak in production.

package/src/server/index.ts

@@ -5,4 +5,4 @@ export { renderRoute } from "./render.ts";
 export type { RenderOptions, ServerManifest } from "./render.ts";
 
 export { redirect, json, error } from "./response.ts";
-export { isDev, requireEnv, safeStringify } from "./env.ts";
+export { isDev, isDevRuntime, setRuntimeMode, requireEnv, safeStringify } from "./env.ts";

package/src/server/render.ts

@@ -1,7 +1,7 @@
 import { renderToReadableStream } from "react-dom/server";
 import type { ReactNode } from "react";
 import type { MetaDescriptor } from "../shared/route-types.ts";
-import { safeStringify, isDev } from "./env.ts";
+import { safeStringify, isDevRuntime } from "./env.ts";
 import { errorOverlayScript } from "../dev/error-overlay.ts";
 import { mergeMeta, renderMetaTags } from "./meta.ts";
 
@@ -35,8 +35,8 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
     status = 200,
   } = options;
 
-  const devFlag = isDev() ? "window.__BRACT_DEV__=true;" : "";
-  const devOverlay = isDev() ? devFlag + errorOverlayScript + "\n" : "";
+  const devFlag = isDevRuntime() ? "window.__BRACT_DEV__=true;" : "";
+  const devOverlay = isDevRuntime() ? devFlag + errorOverlayScript + "\n" : "";
   const mergedMeta = mergeMeta(options.meta ?? []);
   // metaHtml is injected into <head> via React (the renderToReadableStream tree
   // is expected to use it). The merged descriptor array is what the client

package/src/server/serve.ts

@@ -2,7 +2,7 @@ import { scanRoutes } from "./scanner.ts";
 import { buildTrie } from "./matcher.ts";
 import { handleRequest, type HandlerConfig } from "./request-handler.ts";
 import { type ServerManifest } from "./render.ts";
-import { isDev, isExplicitDev } from "./env.ts";
+import { isDevRuntime, isExplicitDev } from "./env.ts";
 import { loadManifest } from "../build/manifest.ts";
 import { serveStatic } from "./static.ts";
 import { handleImageRequest } from "../image/handler.ts";
@@ -68,7 +68,7 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
   const buildDir = resolve(config.buildDir ?? "./build");
   const imageCacheDir = resolve(config.imageCacheDir ?? ".bract-image-cache");
 
-  const manifestReady: Promise<ServerManifest> = !isDev() && !config.manifest
+  const manifestReady: Promise<ServerManifest> = !isDevRuntime() && !config.manifest
     ? loadManifest(buildDir).then((m) => ({
         clientEntry: m.clientEntry,
         rootChunk: m.rootChunk,
@@ -147,17 +147,43 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     if (staticRes) return staticRes;
 
     const trie = await trieReady;
-    const manifest = isDev() ? await readDevManifest(buildDir) : await manifestReady;
+    const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
     const handlerConfig: HandlerConfig = { appDir, publicDir, manifest };
     return handleRequest(request, trie, handlerConfig);
   };
 }
 
+/**
+ * In production-runtime mode, surface a warning when the manifest on disk
+ * wasn't produced by `bractjs build` (missing `"mode": "production"`).
+ * Almost always means the user is running `bractjs start` against a dev
+ * rebuilder's manifest, or hasn't run `bractjs build` at all.
+ */
+async function warnIfStaleBuild(buildDir: string): Promise<void> {
+  const f = Bun.file(join(buildDir, "route-manifest.json"));
+  if (!(await f.exists())) {
+    console.warn(`[bract] No build found at ${buildDir}/route-manifest.json. Run \`bractjs build\` before \`bractjs start\`.`);
+    return;
+  }
+  try {
+    const m = (await f.json()) as { mode?: string };
+    if (m.mode !== "production") {
+      console.warn(`[bract] Build at ${buildDir} was not produced by \`bractjs build\` (mode=${m.mode ?? "unset"}). Re-run \`bractjs build\` for a production-ready manifest.`);
+    }
+  } catch {
+    // Malformed manifest — the request path will surface the real error.
+  }
+}
+
 export function createServer(config?: Partial<BractJSConfig>): {
   stop(): void;
 } {
   const port = config?.port ?? 3000;
 
+  if (!isDevRuntime()) {
+    void warnIfStaleBuild(resolve(config?.buildDir ?? "./build"));
+  }
+
   const fetchHandler = buildFetchHandler(config ?? {});
 
   // Use provided adapter or fall back to the default Bun adapter.