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

@bractjs/bractjs 0.1.16 → 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 (8) hide show

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.16",
+  "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/dev/server.ts CHANGED Viewed

@@ -5,6 +5,7 @@ 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.
@@ -16,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/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/serve.ts CHANGED Viewed

@@ -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 = {
@@ -175,6 +179,11 @@ async function warnIfStaleBuild(buildDir: string): Promise<void> {
   }
 }
+// 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;
 } {
@@ -192,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();
+    }
+  };
+  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);
+  };
-  // 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);
+  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;