npm - @bractjs/bractjs - Versions diffs - 0.1.15 → 0.1.17 - Mend

@bractjs/bractjs 0.1.15 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md +41 -0
package/package.json +1 -1
package/src/build/bundler.ts +1 -1
package/src/build/manifest.ts +4 -1
package/src/client/components/LiveReload.tsx +9 -0
package/src/dev/server.ts +16 -1
package/src/index.ts +2 -0
package/src/server/env.ts +18 -0
package/src/server/index.ts +1 -1
package/src/server/lifecycle.ts +9 -0
package/src/server/render.ts +3 -3
package/src/server/serve.ts +80 -18
package/types/config.d.ts +4 -0
package/types/index.d.ts +5 -0

package/README.md CHANGED Viewed

@@ -440,6 +440,44 @@ export const db = new Database(Bun.env.DATABASE_URL);
 ---
+## Server Lifecycle Hooks
+Use `defineLifecycle()` in `app/lifecycle.ts` to run code when the server starts or shuts down. The shutdown hook runs on **any** exit signal (`SIGTERM`, `SIGINT`, `SIGUSR2`, `beforeExit`, and uncaught exceptions), so database connections are always closed cleanly.
+```ts
+// app/lifecycle.ts
+import { defineLifecycle } from "@bractjs/bractjs";
+import { db } from "./db.server.ts";
+export default defineLifecycle({
+  async onStart() {
+    await db.connect();
+    console.log("Database connected");
+  },
+  async onShutdown() {
+    await db.disconnect();
+    console.log("Database disconnected");
+  },
+});
+```
+BractJS picks up `app/lifecycle.ts` automatically in dev mode. In production, spread the hooks into `createServer()`:
+```ts
+// server.ts (production entry)
+import { createServer } from "@bractjs/bractjs";
+import lifecycle from "./app/lifecycle.ts";
+createServer({ port: 3000, ...lifecycle });
+```
+| Hook | When it runs |
+|------|-------------|
+| `onStart` | Once, after the server begins accepting requests |
+| `onShutdown` | Before process exit — any signal or uncaught exception |
+---
 ## Configuration Reference
 All fields are optional. BractJS works with zero configuration.
@@ -454,6 +492,8 @@ All fields are optional. BractJS works with zero configuration.
 | `sourcemap` | `string` | `"external"` | `"none"` \| `"inline"` \| `"external"` |
 | `minify` | `boolean` | `true` | Minify client bundles |
 | `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
+| `onStart` | `() => void \| Promise<void>` | — | Called once after the server starts listening |
+| `onShutdown` | `() => void \| Promise<void>` | — | Called before process exit on any signal |
 ---
@@ -475,6 +515,7 @@ All fields are optional. BractJS works with zero configuration.
 my-app/
 ├── app/
 │   ├── root.tsx              # required — <html> shell
+│   ├── lifecycle.ts          # optional — onStart / onShutdown hooks
 │   ├── route-types.gen.ts    # generated by bractjs codegen
 │   ├── actions.ts            # "use server" actions
 │   └── routes/

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,9 +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";
+import type { LifecycleHooks } from "../server/lifecycle.ts";
+// 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);
@@ -11,7 +17,16 @@ const hmr = createHmrServer(3001);
 const { duration: initialMs } = await rebuildClient();
 console.log(`[bractjs] initial client build in ${initialMs}ms`);
-createServer({ port: 3000 });
+// Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
+let lifecycle: LifecycleHooks = {};
+try {
+  const mod = await import("../../app/lifecycle.ts");
+  if (mod.default) lifecycle = mod.default;
+} catch {
+  // No lifecycle file — that's fine
+}
+createServer({ port: 3000, ...lifecycle });
 watchApp("./app", async (file) => {
   const { duration } = await rebuildClient();

package/src/index.ts CHANGED Viewed

@@ -19,6 +19,8 @@ export { cssModulesPlugin, transformCssModule } from "./build/plugins/css-module
 // Client RPC
 export { createClient } from "./client/rpc.ts";
 export type { BractJSConfig, RenderOptions, ServerManifest } from "./server/index.ts";
+export { defineLifecycle } from "./server/lifecycle.ts";
+export type { LifecycleHooks } from "./server/lifecycle.ts";
 // Shared types
 export type {

package/src/server/env.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/lifecycle.ts ADDED Viewed

@@ -0,0 +1,9 @@
+export interface LifecycleHooks {
+  onStart?: () => Promise<void> | void;
+  onShutdown?: () => Promise<void> | void;
+}
+/** Type-safe helper for declaring server lifecycle hooks in app/lifecycle.ts. */
+export function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks {
+  return hooks;
+}

package/src/server/render.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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";
@@ -32,6 +32,10 @@ export interface BractJSConfig {
   buildDir?: string;
   /** Directory for transformed image cache. Defaults to .bract-image-cache */
   imageCacheDir?: string;
+  /** Called once after the server starts listening. Use to open DB connections, warm caches, etc. */
+  onStart?: () => Promise<void> | void;
+  /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
+  onShutdown?: () => Promise<void> | void;
 }
 const DEFAULT_MANIFEST: ServerManifest = {
@@ -68,7 +72,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 +151,48 @@ 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.
+  }
+}
+// Module-level guards so signal handlers are registered exactly once across
+// HMR restarts and multiple createServer() calls in the same process.
+let signalsRegistered = false;
+let isShuttingDown = false;
 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.
@@ -166,28 +201,55 @@ export function createServer(config?: Partial<BractJSConfig>): {
   if (adapter instanceof BunAdapter) {
     adapter.setHandler(fetchHandler);
     adapter.listen(port);
+  } else {
+    // Custom adapter: wire fetch handler in and call listen if available.
+    if ("setHandler" in adapter && typeof (adapter as unknown as { setHandler: unknown }).setHandler === "function") {
+      (adapter as unknown as { setHandler: (h: (r: Request) => Promise<Response>) => void }).setHandler(fetchHandler);
+    }
+    adapter.listen?.(port);
+  }
-    console.log(`[bract] Server running at http://localhost:${port}`);
+  console.log(`[bract] Server running at http://localhost:${port}`);
-    return {
-      stop() { adapter.stop(); },
-    };
-  }
+  const stopAdapter = () => {
+    if (adapter instanceof BunAdapter) {
+      adapter.stop();
+    } else if ("stop" in adapter && typeof (adapter as unknown as { stop: unknown }).stop === "function") {
+      (adapter as unknown as { stop: () => void }).stop();
+    }
+  };
-  // Custom adapter: wire fetch handler in and call listen if available.
-  if ("setHandler" in adapter && typeof (adapter as unknown as { setHandler: unknown }).setHandler === "function") {
-    (adapter as unknown as { setHandler: (h: (r: Request) => Promise<Response>) => void }).setHandler(fetchHandler);
+  const gracefulShutdown = async (signal?: string) => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
+    if (signal) console.log(`\n[bract] Received ${signal}, shutting down…`);
+    try {
+      await config?.onShutdown?.();
+    } catch (err) {
+      console.error("[bract] onShutdown error:", err);
+    }
+    stopAdapter();
+    process.exit(0);
+  };
+  if (!signalsRegistered) {
+    signalsRegistered = true;
+    process.on("SIGTERM", () => void gracefulShutdown("SIGTERM"));
+    process.on("SIGINT",  () => void gracefulShutdown("SIGINT"));
+    process.on("SIGUSR2", () => void gracefulShutdown("SIGUSR2"));
+    process.on("beforeExit", () => void gracefulShutdown());
+    process.on("uncaughtException", (err) => {
+      console.error("[bract] Uncaught exception:", err);
+      void gracefulShutdown("uncaughtException");
+    });
   }
-  adapter.listen?.(port);
-  console.log(`[bract] Server running at http://localhost:${port}`);
+  void Promise.resolve(config?.onStart?.()).catch((err) => {
+    console.error("[bract] onStart error:", err);
+  });
   return {
-    stop() {
-      if ("stop" in adapter && typeof (adapter as unknown as { stop: unknown }).stop === "function") {
-        (adapter as unknown as { stop: () => void }).stop();
-      }
-    },
+    stop() { void gracefulShutdown(); },
   };
 }

package/types/config.d.ts CHANGED Viewed

@@ -15,6 +15,10 @@ export interface BractJSConfig {
   minify?: boolean;
   /** process.env keys allowed to be inlined into client bundles. */
   clientEnv?: string[];
+  /** Called once after the server starts listening. Use to open DB connections, warm caches, etc. */
+  onStart?: () => Promise<void> | void;
+  /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
+  onShutdown?: () => Promise<void> | void;
 }
 export interface ServerManifest {

package/types/index.d.ts CHANGED Viewed

@@ -22,6 +22,11 @@ export interface RenderOptions {
   status?: number;
 }
+export interface LifecycleHooks {
+  onStart?: () => Promise<void> | void;
+  onShutdown?: () => Promise<void> | void;
+}
+export declare function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks;
 export declare function createServer(config?: Partial<BractJSConfig>): { stop(): void };
 export declare function renderRoute(options: RenderOptions): Promise<Response>;
 export declare function redirect(url: string, status?: number): Response;