@bractjs/bractjs 0.1.22 → 0.1.24

package/src/codegen/module-registry.ts

@@ -0,0 +1,316 @@
+import { join, resolve } from "node:path";
+import { scanRoutes, type RouteFile } from "../server/scanner.ts";
+
+// Codegen entry-points: `bun build --compile` can't statically trace
+// `Bun.Glob` scans or `import(absPath)` calls, so we materialise the route /
+// layout / action graph into static `import` statements at build time. The
+// emitted files live at `<appDir>/_generated/{routes,actions}.ts` and are
+// imported by the user-facing `app/server.ts` entrypoint.
+
+// ── Path safety ────────────────────────────────────────────────────────────
+
+// Allow ASCII filename characters, `/` for nested directories, and `[`/`]`
+// for file-based dynamic route syntax (`[id]`, `[...slug]`). All emit sites
+// wrap the path in JSON.stringify, but we still allowlist the charset as
+// defense-in-depth against a hostile filename containing a backtick, $, quote,
+// backslash, or whitespace breaking out of the generated literal. `..` as a
+// whole segment is rejected separately below (path-traversal guard).
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]]+$/;
+
+function assertSafeFilePath(filePath: string): void {
+  if (!SAFE_FILEPATH_RE.test(filePath)) {
+    throw new Error(`[bractjs] codegen: refusing to emit unsafe file path: ${JSON.stringify(filePath)}`);
+  }
+  if (filePath.split("/").includes("..")) {
+    throw new Error(`[bractjs] codegen: refusing to emit path with .. segment: ${JSON.stringify(filePath)}`);
+  }
+}
+
+// Derive a JS identifier from an arbitrary relative path. Any character outside
+// `[A-Za-z0-9_]` collapses to `_`. The leading digit (if any) gets an `_`
+// prefix. This is purely for variable naming in the generated source; the
+// authoritative key for the registry is the JSON-stringified relPath.
+function pathToIdent(prefix: string, relPath: string): string {
+  const safe = relPath.replace(/[^A-Za-z0-9_]/g, "_");
+  return /^[0-9]/.test(safe) ? `${prefix}__${safe}` : `${prefix}_${safe}`;
+}
+
+// ── Layout discovery ───────────────────────────────────────────────────────
+
+function layoutDirsForPattern(urlPattern: string): string[] {
+  if (urlPattern === "") return [];
+  const segments = urlPattern.split("/");
+  segments.pop();
+  const dirs: string[] = [];
+  for (let i = 1; i <= segments.length; i++) {
+    dirs.push(segments.slice(0, i).join("/"));
+  }
+  return dirs;
+}
+
+/**
+ * Find every `routes/<dir>/layout.tsx` (or `.ts`) that exists on disk for the
+ * given set of routes. Mirrors the runtime probe in `resolveLayoutChain` but
+ * runs once at codegen time so the generated registry is exhaustive.
+ */
+async function collectLayouts(appDir: string, routes: RouteFile[]): Promise<string[]> {
+  const layoutPaths = new Set<string>();
+  for (const route of routes) {
+    for (const dir of layoutDirsForPattern(route.urlPattern)) {
+      for (const ext of ["tsx", "ts"]) {
+        const rel = `routes/${dir}/layout.${ext}`;
+        const abs = resolve(join(appDir, rel));
+        if (await Bun.file(abs).exists()) {
+          layoutPaths.add(rel);
+        }
+      }
+    }
+  }
+  return [...layoutPaths].sort();
+}
+
+// ── Action discovery ───────────────────────────────────────────────────────
+
+const SERVER_DIRECTIVE_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use server["']/;
+
+function isEligibleActionPath(rel: string): boolean {
+  return (
+    rel.endsWith(".server.ts") ||
+    rel.endsWith(".server.tsx") ||
+    rel.startsWith("routes/") ||
+    rel.startsWith("routes\\")
+  );
+}
+
+async function collectActionFiles(appDir: string): Promise<string[]> {
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  const found: string[] = [];
+  for await (const rel of glob.scan(appDir)) {
+    if (!isEligibleActionPath(rel)) continue;
+    // Skip the codegen output directory itself.
+    if (rel.startsWith("_generated/")) continue;
+    const abs = resolve(join(appDir, rel));
+    let src: string;
+    try {
+      src = await Bun.file(abs).text();
+    } catch {
+      continue;
+    }
+    if (!SERVER_DIRECTIVE_RE.test(src)) continue;
+    // Normalise Windows separators to POSIX for the registry key.
+    found.push(rel.split("\\").join("/"));
+  }
+  return found.sort();
+}
+
+// ── Generators ─────────────────────────────────────────────────────────────
+
+const HEADER =
+  "// Generated by `bractjs codegen` — do not edit manually.\n" +
+  "// Static imports here let `bun build --compile` trace every route, layout,\n" +
+  "// and server-action module instead of relying on runtime fs scans.\n" +
+  "\n" +
+  "/* eslint-disable */\n";
+
+export interface RouteRegistryInput {
+  appDir: string;
+  routes: RouteFile[];
+  layoutRelPaths: string[]; // e.g. ["routes/blog/layout.tsx"]
+  hasRoot: boolean;         // true if appDir/root.tsx exists
+}
+
+export function generateRouteRegistry(input: RouteRegistryInput): string {
+  const { routes, layoutRelPaths, hasRoot } = input;
+
+  // ── Build the import statements ──
+  const imports: string[] = [];
+  const entries: string[] = [];
+
+  if (hasRoot) {
+    assertSafeFilePath("root.tsx");
+    const ident = pathToIdent("mod", "root_tsx");
+    imports.push(`import * as ${ident} from "../root.tsx";`);
+    entries.push(`  ${JSON.stringify("root.tsx")}: ${ident},`);
+  }
+
+  for (const rel of layoutRelPaths) {
+    assertSafeFilePath(rel);
+    const ident = pathToIdent("mod", rel);
+    imports.push(`import * as ${ident} from ${JSON.stringify("../" + rel)};`);
+    entries.push(`  ${JSON.stringify(rel)}: ${ident},`);
+  }
+
+  for (const r of routes) {
+    const rel = r.filePath.split("\\").join("/");
+    assertSafeFilePath(rel);
+    const ident = pathToIdent("mod", rel);
+    imports.push(`import * as ${ident} from ${JSON.stringify("../" + rel)};`);
+    entries.push(`  ${JSON.stringify(rel)}: ${ident},`);
+  }
+
+  // ── routeFiles array literal (mirrors scanRoutes output shape) ──
+  const routeFilesLines: string[] = [];
+  for (const r of routes) {
+    const rel = r.filePath.split("\\").join("/");
+    assertSafeFilePath(rel);
+    const segments = JSON.stringify(r.segments);
+    routeFilesLines.push(
+      `  { filePath: ${JSON.stringify(rel)}, urlPattern: ${JSON.stringify(r.urlPattern)}, segments: ${segments} },`,
+    );
+  }
+
+  return [
+    HEADER,
+    `import type { RouteFile, ModuleRegistry } from "@bractjs/bractjs";`,
+    "",
+    imports.join("\n"),
+    "",
+    "// Modules keyed by appDir-relative path. The framework looks up route,",
+    "// layout, and root modules here at request time instead of doing a",
+    "// dynamic `import(absPath)` call that would fail in a compiled binary.",
+    "//",
+    "// `ModuleRegistry` is intentionally `Record<string, RouteModule | Record<string, unknown>>`",
+    "// — strict `RouteModule` typing would reject route files whose exports",
+    "// (e.g. an ErrorBoundary typed for `{ error: Error }` instead of `{ error: unknown }`)",
+    "// diverge slightly from the framework signature. Runtime behaviour is unchanged.",
+    "export const moduleRegistry: ModuleRegistry = {",
+    entries.join("\n"),
+    "};",
+    "",
+    "export const routeFiles: RouteFile[] = [",
+    routeFilesLines.join("\n"),
+    "];",
+    "",
+  ].join("\n");
+}
+
+export interface ActionRegistryInput {
+  appDir: string;
+  actionRelPaths: string[];
+}
+
+export function generateActionRegistry(input: ActionRegistryInput): string {
+  const { actionRelPaths } = input;
+
+  const imports: string[] = [];
+  const entries: string[] = [];
+
+  for (const rel of actionRelPaths) {
+    assertSafeFilePath(rel);
+    const ident = pathToIdent("act", rel);
+    imports.push(`import * as ${ident} from ${JSON.stringify("../" + rel)};`);
+    entries.push(`  { relPath: ${JSON.stringify(rel)}, mod: ${ident} as Record<string, unknown> },`);
+  }
+
+  return [
+    HEADER,
+    imports.join("\n"),
+    "",
+    "// Server-action modules, statically imported so `bun build --compile`",
+    "// traces them. The framework iterates this list and registers each",
+    "// exported function under SHA-256(relPath + \"#\" + name) — identical to",
+    "// the ID the client proxy plugin embeds in the bundled JS.",
+    "export const actionModules: Array<{ relPath: string; mod: Record<string, unknown> }> = [",
+    entries.join("\n"),
+    "];",
+    "",
+  ].join("\n");
+}
+
+// ── Manifest codegen ───────────────────────────────────────────────────────
+
+/**
+ * Shape produced by `src/build/manifest.ts` (`RouteManifest`). Re-typed here
+ * so the codegen module stays decoupled from the build pipeline.
+ */
+interface DiskManifest {
+  version?: number;
+  mode?: string;
+  clientEntry: string;
+  rootChunk?: string;
+  routes: Record<string, { chunk: string; pattern: string }>;
+}
+
+/**
+ * Convert the disk-format manifest (RouteManifest) into a TypeScript module
+ * exporting a `ServerManifest` constant. This decouples the compiled-binary
+ * server entry from the disk manifest — at startup it imports the constant
+ * instead of reading `build/route-manifest.json`.
+ */
+export function generateManifestModule(disk: DiskManifest): string {
+  // Mirror the RouteManifest → ServerManifest projection in serve.ts so the
+  // compiled binary sees the same shape `buildFetchHandler` would have built.
+  const projectedRoutes: Record<string, { file: string; chunk: string }> = {};
+  for (const [pat, entry] of Object.entries(disk.routes ?? {})) {
+    projectedRoutes[pat] = { file: entry.chunk, chunk: entry.chunk };
+  }
+  const projected = {
+    clientEntry: disk.clientEntry,
+    rootChunk: disk.rootChunk,
+    routes: projectedRoutes,
+  };
+  // JSON.stringify is safe for embedding — all strings get properly escaped.
+  // No template literals or backtick interpolation can leak through.
+  return [
+    HEADER,
+    `import type { ServerManifest } from "@bractjs/bractjs";`,
+    "",
+    "// Snapshot of build/route-manifest.json, frozen into the binary so the",
+    "// server never needs to read it from disk at startup.",
+    `export const manifest: ServerManifest = ${JSON.stringify(projected, null, 2)};`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Read `<buildDir>/route-manifest.json` and write
+ * `<appDir>/_generated/manifest.ts`. Must run AFTER the client `Bun.build()`
+ * step — chunk filenames are content-hashed and not known until then.
+ */
+export async function writeManifestModule(
+  appDir: string,
+  buildDir: string,
+): Promise<string> {
+  const absAppDir = resolve(appDir);
+  const absBuildDir = resolve(buildDir);
+  const src = join(absBuildDir, "route-manifest.json");
+  const file = Bun.file(src);
+  if (!(await file.exists())) {
+    throw new Error(
+      `[bractjs] manifest codegen: ${src} not found. Run the client build before manifest codegen.`,
+    );
+  }
+  const disk = (await file.json()) as DiskManifest;
+  const out = join(absAppDir, "_generated", "manifest.ts");
+  await Bun.write(out, generateManifestModule(disk));
+  return out;
+}
+
+// ── Driver ─────────────────────────────────────────────────────────────────
+
+export interface CodegenResult {
+  routesPath: string;
+  actionsPath: string;
+}
+
+export async function writeModuleRegistries(appDir: string): Promise<CodegenResult> {
+  const absAppDir = resolve(appDir);
+  const routes = await scanRoutes(absAppDir);
+  const layoutRelPaths = await collectLayouts(absAppDir, routes);
+  const hasRoot =
+    (await Bun.file(resolve(join(absAppDir, "root.tsx"))).exists()) ||
+    (await Bun.file(resolve(join(absAppDir, "root.ts"))).exists());
+  const actionRelPaths = await collectActionFiles(absAppDir);
+
+  const routesSrc = generateRouteRegistry({ appDir: absAppDir, routes, layoutRelPaths, hasRoot });
+  const actionsSrc = generateActionRegistry({ appDir: absAppDir, actionRelPaths });
+
+  const outDir = resolve(join(absAppDir, "_generated"));
+  const routesPath = join(outDir, "routes.ts");
+  const actionsPath = join(outDir, "actions.ts");
+
+  await Bun.write(routesPath, routesSrc);
+  await Bun.write(actionsPath, actionsSrc);
+
+  return { routesPath, actionsPath };
+}

package/src/dev/hmr-module-handler.ts

@@ -1,7 +1,7 @@
 import { resolve, join, sep } from "node:path";
 import { realpath } from "node:fs/promises";
 import { serverOnlyPlugin } from "../build/env-plugin.ts";
-import { useServerProxyPlugin } from "../build/directives.ts";
+import { createUseServerProxyPlugin } from "../build/directives.ts";
 
 /**
  * Dev-only HTTP handler for /_hmr/module?file=routes/about.tsx
@@ -55,7 +55,7 @@ export async function handleHmrModuleRequest(
     target: "browser",
     minify: false,
     sourcemap: "inline",
-    plugins: [serverOnlyPlugin, useServerProxyPlugin],
+    plugins: [serverOnlyPlugin, createUseServerProxyPlugin(rootDir)],
   });
 
   if (!result.success || result.outputs.length === 0) {

package/src/dev/rebuilder.ts

@@ -1,5 +1,5 @@
 import type { BractJSConfig } from "../server/serve.ts";
-import { useServerProxyPlugin } from "../build/directives.ts";
+import { createUseServerProxyPlugin } from "../build/directives.ts";
 import { scanRoutes } from "../server/scanner.ts";
 import { generateManifest, writeManifest } from "../build/manifest.ts";
 import { mkdir, rename, rm } from "node:fs/promises";
@@ -48,7 +48,7 @@ export async function rebuildClient(
       // structure. publicPath + ../ traversals produce wrong absolute URLs.
       minify: false,
       sourcemap: "inline",
-      plugins: [useServerProxyPlugin, ...(config?.plugins ?? [])],
+      plugins: [createUseServerProxyPlugin(appDir), ...(config?.plugins ?? [])],
     });
   } finally {
     await rm(shimPath, { force: true });

package/src/index.ts

@@ -14,7 +14,36 @@ export { BunAdapter } from "./server/adapter.ts";
 export { createCloudflareAdapter, makeCloudflareHandler } from "./adapters/cloudflare.ts";
 
 // Build plugins
+//
+// These plugins are REQUIRED when users compose their own `Bun.build` call
+// (e.g. native `bun build --compile` or a custom client bundle step). Missing
+// any of them breaks security or runtime behaviour:
+//
+// - `useClientStubPlugin` (server bundle): replaces "use client" modules with
+//   null stubs. Without it, the server binary crashes when React tries to
+//   call browser-only hooks/APIs.
+// - `createUseServerProxyPlugin(appDir)` (client bundle): replaces
+//   "use server" exports with fetch proxies. Without it, server-action
+//   bodies — including DB queries and secrets — ship inside the browser JS.
+// - `serverOnlyPlugin` (client bundle): hard-fails imports of `*.server.ts`
+//   files so server-only code can never be tree-walked into the client bundle.
+// - `clientEnvPlugin(allowedKeys, env)` (client bundle): allowlists which
+//   `process.env.*` references survive into the browser bundle.
+// - `cssModulesPlugin` (client bundle): handles `*.module.css` imports.
 export { cssModulesPlugin, transformCssModule } from "./build/plugins/css-modules.ts";
+export { useClientStubPlugin, createUseServerProxyPlugin, useServerProxyPlugin } from "./build/directives.ts";
+export { serverOnlyPlugin, clientEnvPlugin } from "./build/env-plugin.ts";
+
+// Module-registry codegen (drives `bun build --compile` workflow)
+export {
+  writeModuleRegistries,
+  writeManifestModule,
+  generateRouteRegistry,
+  generateActionRegistry,
+  generateManifestModule,
+} from "./codegen/module-registry.ts";
+export type { CodegenResult } from "./codegen/module-registry.ts";
+export type { ModuleRegistry } from "./server/layout.ts";
 
 // Client RPC
 export { createClient } from "./client/rpc.ts";
@@ -34,6 +63,7 @@ export type {
   RouteModule,
   RouteDefinition,
 } from "./shared/route-types.ts";
+export type { RouteFile, Segment } from "./server/scanner.ts";
 
 export { BractJSError, HttpError, isRedirect, isHttpError, isBractJSError } from "./shared/errors.ts";
 export { Deferred, defer, isDeferred } from "./shared/deferred.ts";

package/src/server/action-registry.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
 
 // Anchored at start-of-file. Allow whitespace and line/block comments before
 // the "use server" string literal. This prevents false matches from a "use
@@ -6,8 +6,12 @@ import { join } from "node:path";
 const SERVER_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use server["']/;
 const registry = new Map<string, (...args: unknown[]) => Promise<unknown>>();
 
-async function computeId(filePath: string, name: string): Promise<string> {
-  const raw = new TextEncoder().encode(filePath + "#" + name);
+/**
+ * Hash key for an action — must use the same string the client-side proxy
+ * plugin hashes (`pathKey + "#" + name`). Mismatch → `/_action?id=...` 404.
+ */
+async function computeId(pathKey: string, name: string): Promise<string> {
+  const raw = new TextEncoder().encode(pathKey + "#" + name);
   const buf = await crypto.subtle.digest("SHA-256", raw);
   return Array.from(new Uint8Array(buf))
     .map((b) => b.toString(16).padStart(2, "0"))
@@ -15,6 +19,18 @@ async function computeId(filePath: string, name: string): Promise<string> {
     .slice(0, 16);
 }
 
+/**
+ * Convert an absolute file path to the appDir-relative key used for hashing.
+ * Matches `pathKeyForAction` in `src/build/directives.ts`. Files outside
+ * appDir keep their absolute path so external imports stay hashable but
+ * distinct from in-tree files.
+ */
+function pathKeyForAction(absPath: string, appDir: string): string {
+  const absAppDir = isAbsolute(appDir) ? appDir : resolve(appDir);
+  const rel = relative(absAppDir, absPath);
+  return rel.startsWith("..") ? absPath : rel;
+}
+
 export function resolveAction(id: string): ((...args: unknown[]) => Promise<unknown>) | null {
   return registry.get(id) ?? null;
 }
@@ -47,7 +63,28 @@ export async function loadServerActions(appDir: string): Promise<void> {
 
     for (const [name, val] of Object.entries(mod)) {
       if (typeof val !== "function") continue;
-      const id = await computeId(filePath, name);
+      const id = await computeId(pathKeyForAction(filePath, appDir), name);
+      registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
+    }
+  }
+}
+
+/**
+ * Registry-driven counterpart to `loadServerActions`. Skips the filesystem
+ * scan and dynamic imports — every entry was already statically imported by
+ * `_generated/actions.ts`, so we just iterate and register.
+ *
+ * Each entry's `relPath` MUST be appDir-relative (matches what
+ * `createUseServerProxyPlugin(appDir)` hashed during the client build).
+ * Mismatched relPaths produce silent `/_action?id=...` 404s.
+ */
+export async function loadServerActionsFromRegistry(
+  entries: Array<{ relPath: string; mod: Record<string, unknown> }>,
+): Promise<void> {
+  for (const { relPath, mod } of entries) {
+    for (const [name, val] of Object.entries(mod)) {
+      if (typeof val !== "function") continue;
+      const id = await computeId(relPath, name);
       registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
     }
   }

package/src/server/layout.ts

@@ -14,6 +14,14 @@ export interface ResolvedRoute extends RouteFile {
   layoutFiles: string[];
 }
 
+/**
+ * Pre-loaded module map keyed by appDir-relative path (e.g. "root.tsx",
+ * "routes/blog/layout.tsx"). When `resolveRouteChain` is called with a
+ * registry, all module lookups go through the registry instead of dynamic
+ * `import(absPath)` — this is what makes `bun build --compile` viable.
+ */
+export type ModuleRegistry = Record<string, RouteModule | Record<string, unknown>>;
+
 // ── Helpers ────────────────────────────────────────────────────────────────
 
 /** Derive the ancestor directory segments from a route's urlPattern. */
@@ -55,6 +63,31 @@ export async function resolveLayoutChain(
   return { ...routeFile, layoutFiles };
 }
 
+/**
+ * Registry-driven equivalent of `resolveLayoutChain`. Skips all filesystem
+ * checks — returns the appDir-relative keys that exist in the registry, in
+ * the same root-first, outermost-to-innermost order. Required for compiled
+ * binaries where `Bun.file().exists()` against the original app paths is
+ * unreliable.
+ */
+export function resolveLayoutChainFromRegistry(
+  routeFile: RouteFile,
+  registry: ModuleRegistry,
+): ResolvedRoute {
+  const layoutFiles: string[] = [];
+  if (registry["root.tsx"]) layoutFiles.push("root.tsx");
+  else if (registry["root.ts"]) layoutFiles.push("root.ts");
+
+  for (const dir of layoutDirs(routeFile.urlPattern)) {
+    const tsxKey = `routes/${dir}/layout.tsx`;
+    const tsKey = `routes/${dir}/layout.ts`;
+    if (registry[tsxKey]) layoutFiles.push(tsxKey);
+    else if (registry[tsKey]) layoutFiles.push(tsKey);
+  }
+
+  return { ...routeFile, layoutFiles };
+}
+
 // ── importRouteModule ──────────────────────────────────────────────────────
 
 export async function importRouteModule(filePath: string): Promise<RouteModule> {
@@ -69,12 +102,52 @@ export async function importRouteModule(filePath: string): Promise<RouteModule>
   };
 }
 
+/**
+ * Project a registry entry (raw `import * as ns` namespace) into the
+ * subset shape `RouteModule` requires. Mirrors `importRouteModule` but
+ * skips the dynamic `import()` because the module is already loaded.
+ */
+function pickRouteModule(mod: Record<string, unknown> | RouteModule | undefined): RouteModule {
+  if (!mod) return {};
+  const m = mod as Record<string, unknown>;
+  return {
+    loader: m.loader as RouteModule["loader"],
+    action: m.action as RouteModule["action"],
+    meta: m.meta as RouteModule["meta"],
+    handle: m.handle as RouteModule["handle"],
+    ErrorBoundary: m.ErrorBoundary as RouteModule["ErrorBoundary"],
+    default: m.default as RouteModule["default"],
+  };
+}
+
 // ── resolveRouteChain ──────────────────────────────────────────────────────
 
+/**
+ * Build the route + layout chain for a matched route.
+ *
+ * Two modes:
+ * - Registry mode (production / compiled binary): when `registry` is provided,
+ *   no filesystem checks and no dynamic imports run. Every module lookup is a
+ *   `Record` access keyed by appDir-relative path.
+ * - Dev mode (no registry): existing filesystem-probe + `import(absPath)`
+ *   path, used by `bractjs dev` so edits to layouts/routes don't require a
+ *   codegen rerun.
+ */
 export async function resolveRouteChain(
   routeFile: RouteFile,
-  appDir: string
+  appDir: string,
+  registry?: ModuleRegistry,
 ): Promise<LayoutChain> {
+  if (registry) {
+    const resolved = resolveLayoutChainFromRegistry(routeFile, registry);
+    const [rootKey, ...layoutKeys] = resolved.layoutFiles;
+    const rootMod = rootKey ? pickRouteModule(registry[rootKey]) : {};
+    const layoutMods = layoutKeys.map((k) => pickRouteModule(registry[k]));
+    const routeKey = routeFile.filePath.split("\\").join("/");
+    const routeMod = pickRouteModule(registry[routeKey]);
+    return { root: rootMod, layouts: layoutMods, route: routeMod };
+  }
+
   const resolved = await resolveLayoutChain(routeFile, appDir);
 
   const [rootMod, ...layoutMods] = await Promise.all(

package/src/server/lifecycle.ts

@@ -1,9 +1,23 @@
+export type OnErrorHook = (err: unknown, request?: Request) => Promise<void> | void;
+
 export interface LifecycleHooks {
   onStart?: () => Promise<void> | void;
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error: loader failures, action throws, and uncaught process exceptions. Redirects and HttpErrors are intentional control flow and are NOT reported here. Use this to send errors to Sentry, Datadog, etc. The request is undefined for process-level exceptions. */
+  onError?: OnErrorHook;
 }
 
 /** Type-safe helper for declaring server lifecycle hooks in app/lifecycle.ts. */
 export function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks {
   return hooks;
 }
+
+/** Safely invokes the onError hook. Errors thrown inside the hook are caught and logged so they never mask the original error or alter the response. */
+export async function fireOnError(hook: OnErrorHook | undefined, err: unknown, request?: Request): Promise<void> {
+  if (!hook) return;
+  try {
+    await hook(err, request);
+  } catch (hookErr) {
+    console.error("[bractjs] onError hook threw:", hookErr);
+  }
+}

package/src/server/loader.ts

@@ -3,6 +3,7 @@ import type { LayoutChain } from "./layout.ts";
 import { isRedirect, isHttpError } from "../shared/errors.ts";
 import { isExplicitDev } from "./env.ts";
 import type { ContextFactory } from "./context.ts";
+import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -18,7 +19,8 @@ export interface LoaderResults {
 
 export async function safeRun<T>(
   fn: ((args: LoaderArgs) => Promise<T> | T) | undefined,
-  args: LoaderArgs
+  args: LoaderArgs,
+  onError?: OnErrorHook,
 ): Promise<T | { __error: unknown } | null> {
   if (!fn) return null;
 
@@ -35,6 +37,7 @@ export async function safeRun<T>(
     // surface structured user-facing errors should throw an HttpError, not
     // a custom Error subclass.
     console.error("[bractjs] loader error:", err);
+    await fireOnError(onError, err, args.request);
     const safe = isExplicitDev()
       ? {
           message: err instanceof Error ? err.message : String(err),
@@ -74,20 +77,22 @@ export async function runBeforeLoad(
 
 export async function runLoaders(
   chain: LayoutChain,
-  args: LoaderArgs
+  args: LoaderArgs,
+  onError?: OnErrorHook,
 ): Promise<LoaderResults> {
   const layoutLoaders = chain.layouts.map((mod) =>
-    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args)
+    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError)
   );
 
   const [root, ...layoutResults] = await Promise.all([
-    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args),
+    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
     ...layoutLoaders,
   ]);
 
   const route = await safeRun(
     chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined,
-    args
+    args,
+    onError,
   );
 
   return { root, layouts: layoutResults, route };