@bractjs/bractjs 0.1.20 → 0.1.22

package/README.md

@@ -507,6 +507,67 @@ All fields are optional. BractJS works with zero configuration.
 | `bractjs start` | Serve the production build |
 | `bractjs codegen [app] [out]` | Generate typed route types into `app/route-types.gen.ts` |
 
+The CLI is a thin convenience layer. Every command delegates to a public programmatic API — you can call the same functions directly from your own scripts without the CLI.
+
+---
+
+## Programmatic API
+
+All three runtime operations are importable, so BractJS can be embedded in existing servers or custom build scripts without the CLI.
+
+### `createDevServer(options?)`
+
+```ts
+import { createDevServer } from "@bractjs/bractjs";
+
+const dev = await createDevServer({
+  port: 3000,    // HTTP port (default: config.port ?? 3000)
+  hmrPort: 3001, // HMR WebSocket port (default: 3001)
+  config: { appDir: "./app", clientEnv: ["PUBLIC_API_URL"] },
+  skipUserConfig: false, // set true to skip loading bractjs.config.ts from cwd
+});
+
+// Later — stops the HTTP server and HMR WebSocket server
+dev.stop();
+```
+
+### `runBuild(config?)`
+
+```ts
+import { runBuild } from "@bractjs/bractjs";
+
+await runBuild({
+  appDir: "./app",
+  buildDir: "./dist",
+  minify: true,
+  sourcemap: "external",
+  clientEnv: ["PUBLIC_API_URL"],
+});
+```
+
+`runBuild` only accepts build-relevant fields (`appDir`, `buildDir`, `sourcemap`, `minify`, `clientEnv`, `plugins`). Server-only fields like `port`, `manifest`, and `publicDir` are not accepted — this makes it safe to call from a build script without constructing a full server config.
+
+### `loadUserConfig()`
+
+```ts
+import { loadUserConfig } from "@bractjs/bractjs";
+
+const cfg = await loadUserConfig();
+// Reads bractjs.config.ts (or .js) from process.cwd()
+// Returns {} if no config file exists
+```
+
+### `createServer(config?)` (production)
+
+Already exported. Starts the production HTTP server directly:
+
+```ts
+import { createServer } from "@bractjs/bractjs";
+import lifecycle from "./app/lifecycle.ts";
+
+createServer({ port: 3000, buildDir: "./build", ...lifecycle });
+```
+
 ---
 
 ## App Directory Structure
@@ -602,7 +663,7 @@ bractjs/
 
 ## Status
 
-**v0.1.0 complete.** All core phases shipped:
+**v0.1.21.** All core phases shipped:
 
 - File-based routing with trie matcher and layout chains
 - Streaming SSR (`renderToReadableStream`) with `defer()` and `<Await>`
@@ -611,12 +672,10 @@ bractjs/
 - Cookie sessions with HMAC-SHA256 and secret rotation
 - Middleware pipeline with `requestLogger`, `cors`, `authGuard`
 - Production build with content-hashed assets and code splitting
-
-Post-v0.1.0 features also shipped:
-
 - `<Image>` with on-demand ImageMagick optimization and LRU cache
 - Typed routes codegen (`AppRoutes`, `RouteParams<T>`, `TypedLoaderArgs<T>`, `routes` builder)
 - `"use server"` / `"use client"` directive system with `/_action` endpoint
+- **Programmatic API** — `createDevServer`, `runBuild`, `loadUserConfig` importable without the CLI
 
 Remaining on the roadmap: Edge runtime (Cloudflare Workers), CSS modules, i18n routing, streaming `useFetcher()`.
 

package/bin/cli.ts

@@ -67,7 +67,8 @@ switch (command) {
     // Ensure dev-only handlers gated by isExplicitDev() (e.g. /_hmr/module,
     // /_bractjs/devtools.js) are reachable when the user hasn't set NODE_ENV.
     if (!process.env.NODE_ENV) process.env.NODE_ENV = "development";
-    await import("../src/dev/server.ts");
+    const { createDevServer } = await import("../src/dev/server.ts");
+    await createDevServer();
     break;
 
   case "build": {
@@ -75,7 +76,9 @@ switch (command) {
     // server build (react-dom/server.bun production) instead of the dev one.
     if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
     const { runBuild } = await import("../src/build/bundler.ts");
-    await runBuild({ port: 3000, appDir: "./app", publicDir: "./public", buildDir: "./build", manifest: { clientEntry: "", routes: {} } });
+    const { loadUserConfig } = await import("../src/config/load.ts");
+    const userCfg = await loadUserConfig();
+    await runBuild({ appDir: "./app", buildDir: "./build", ...userCfg });
     break;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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/__tests__/.tmp-security-action/routes/_index.tsx

@@ -0,0 +1,2 @@
+"use server";
+export async function ping(...args) { return args; }

package/src/__tests__/programmatic-api.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Tests for the programmatic API: createDevServer, runBuild, loadUserConfig.
+ *
+ * Note: tests that start Bun.serve() (like integration.test.ts) are excluded
+ * here because the process.on("beforeExit") handler in createServer causes
+ * bun:test to exit before printing results — a known pre-existing issue.
+ * Behavioral coverage (HTTP response, HMR) lives in integration.test.ts.
+ */
+import { test, expect } from "bun:test";
+import { loadUserConfig } from "../config/load.ts";
+import { runBuild } from "../build/bundler.ts";
+import { createDevServer } from "../dev/server.ts";
+import type { BuildConfig } from "../build/bundler.ts";
+import type { DevServerOptions, DevServer } from "../dev/server.ts";
+
+// ── loadUserConfig ────────────────────────────────────────────────────────
+
+test("loadUserConfig is exported from config/load", () => {
+  expect(typeof loadUserConfig).toBe("function");
+});
+
+test("loadUserConfig returns an object when no bractjs.config.ts exists", async () => {
+  // Repo root has no bractjs.config.ts — must return a plain empty object.
+  const cfg = await loadUserConfig();
+  expect(typeof cfg).toBe("object");
+  expect(cfg).not.toBeNull();
+});
+
+// ── runBuild ──────────────────────────────────────────────────────────────
+
+test("runBuild is exported from build/bundler", () => {
+  expect(typeof runBuild).toBe("function");
+});
+
+test("runBuild signature does not require server-only fields (port/manifest/publicDir)", () => {
+  // Compile-time guard: if BuildConfig mistakenly included required server fields,
+  // this line would fail TypeScript type-checking.
+  const config: BuildConfig = { appDir: "./app", minify: false };
+  expect(typeof config).toBe("object");
+  // Ensure none of the server-only keys are present as required fields.
+  expect("port" in config).toBe(false);
+  expect("manifest" in config).toBe(false);
+  expect("publicDir" in config).toBe(false);
+});
+
+test("runBuild rejects with a defined error when appDir does not exist", async () => {
+  await expect(
+    runBuild({ appDir: "/definitely/does/not/exist/__bractjs_test__" }),
+  ).rejects.toBeDefined();
+});
+
+// ── createDevServer ───────────────────────────────────────────────────────
+
+test("createDevServer is exported from dev/server", () => {
+  expect(typeof createDevServer).toBe("function");
+});
+
+test("createDevServer accepts DevServerOptions shape without error at compile time", () => {
+  // Compile-time guard: verify the options interface has the expected fields.
+  const opts: DevServerOptions = {
+    port: 3997,
+    hmrPort: 3996,
+    skipUserConfig: true,
+    config: { appDir: "./app" },
+  };
+  expect(typeof opts).toBe("object");
+  expect(opts.port).toBe(3997);
+  expect(opts.hmrPort).toBe(3996);
+  expect(opts.skipUserConfig).toBe(true);
+});
+
+test("DevServer interface has a stop() method", () => {
+  // Compile-time guard: verify DevServer shape.
+  const stub: DevServer = { stop: () => {} };
+  expect(typeof stub.stop).toBe("function");
+});
+
+// ── Re-exports from src/index.ts ──────────────────────────────────────────
+
+test("createDevServer, runBuild, loadUserConfig are all re-exported from src/index.ts", async () => {
+  const mod = await import("../index.ts");
+  expect(typeof mod.createDevServer).toBe("function");
+  expect(typeof mod.runBuild).toBe("function");
+  expect(typeof mod.loadUserConfig).toBe("function");
+});

package/src/build/bundler.ts

@@ -1,6 +1,6 @@
 import { join, basename, extname, resolve } from "node:path";
 import { rename, rm } from "node:fs/promises";
-import type { BractJSConfig } from "../server/serve.ts";
+import type { BunPlugin } from "bun";
 import { scanRoutes } from "../server/scanner.ts";
 import { contentHash } from "./hash.ts";
 import { generateManifest, writeManifest } from "./manifest.ts";
@@ -10,7 +10,17 @@ import { writeRouteTypes } from "../codegen/route-codegen.ts";
 import { useClientStubPlugin, useServerProxyPlugin } from "./directives.ts";
 import { cssModulesPlugin } from "./plugins/css-modules.ts";
 
-export async function runBuild(config: BractJSConfig): Promise<void> {
+/** Subset of config fields relevant to the build pipeline. */
+export interface BuildConfig {
+  appDir?: string;
+  buildDir?: string;
+  sourcemap?: "none" | "linked" | "inline" | "external";
+  minify?: boolean;
+  clientEnv?: string[];
+  plugins?: BunPlugin[];
+}
+
+export async function runBuild(config: BuildConfig): Promise<void> {
   const appDir = config.appDir ?? "./app";
 
   // ── 0. Codegen — typed routes ───────────────────────────────────────────
@@ -54,7 +64,7 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
     minify: config.minify ?? true,
     sourcemap: config.sourcemap ?? "external",
     define: buildDefines(config),
-    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin],
+    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin, ...(config.plugins ?? [])],
   });
   if (!clientResult.success) throw new AggregateError(clientResult.logs, "Client build failed");
 

package/src/config/load.ts

@@ -0,0 +1,17 @@
+import { resolve } from "node:path";
+import type { BractJSConfig } from "../server/serve.ts";
+
+/**
+ * Load `bractjs.config.ts` (or `.js`) from the user's cwd if present.
+ * Returns an empty object when no file exists — callers fall back to defaults.
+ */
+export async function loadUserConfig(): Promise<Partial<BractJSConfig>> {
+  for (const name of ["bractjs.config.ts", "bractjs.config.js"]) {
+    const path = resolve(process.cwd(), name);
+    if (!(await Bun.file(path).exists())) continue;
+    const mod = await import(path);
+    const cfg = (mod.default ?? mod) as Partial<BractJSConfig>;
+    return cfg ?? {};
+  }
+  return {};
+}

package/src/dev/rebuilder.ts

@@ -48,7 +48,7 @@ export async function rebuildClient(
       // structure. publicPath + ../ traversals produce wrong absolute URLs.
       minify: false,
       sourcemap: "inline",
-      plugins: [useServerProxyPlugin],
+      plugins: [useServerProxyPlugin, ...(config?.plugins ?? [])],
     });
   } finally {
     await rm(shimPath, { force: true });

package/src/dev/server.ts

@@ -6,49 +6,89 @@ import { rebuildClient } from "./rebuilder.ts";
 import { filePathToPattern } from "../server/scanner.ts";
 import { basename, extname } from "node:path";
 import type { LifecycleHooks } from "../server/lifecycle.ts";
+import { loadUserConfig } from "../config/load.ts";
+import type { BractJSConfig } from "../server/serve.ts";
 
-// Must precede any user-code import so SSR-time isDevRuntime() checks
-// (e.g. inside <LiveReload>) observe the dev mode.
-setRuntimeMode("dev");
+export interface DevServerOptions {
+  /** HTTP port for the app server. Default: config.port ?? 3000. */
+  port?: number;
+  /** WebSocket port for HMR. Default: 3001. */
+  hmrPort?: number;
+  /** Merged over values from bractjs.config.ts. */
+  config?: Partial<BractJSConfig>;
+  /**
+   * Skip loading bractjs.config.ts from cwd.
+   * Useful when the caller supplies the full config via the `config` option.
+   */
+  skipUserConfig?: boolean;
+}
+
+export interface DevServer {
+  stop(): void;
+}
 
-const hmr = createHmrServer(3001);
+export async function createDevServer(options?: DevServerOptions): Promise<DevServer> {
+  // Must precede any user-code import so SSR-time isDevRuntime() checks
+  // (e.g. inside <LiveReload>) observe the dev mode.
+  setRuntimeMode("dev");
 
-// Build client bundle before the HTTP server starts accepting requests
-const { duration: initialMs } = await rebuildClient();
-console.log(`[bractjs] initial client build in ${initialMs}ms`);
+  const userConfig = options?.skipUserConfig ? {} : await loadUserConfig();
+  const merged: Partial<BractJSConfig> = { ...userConfig, ...options?.config };
 
-// Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
-let lifecycle: LifecycleHooks = {};
-try {
-  const lifecyclePath = `${process.cwd()}/app/lifecycle.ts`;
-  const mod = await import(lifecyclePath);
-  if (mod.default) lifecycle = mod.default;
-} catch {
-  // No lifecycle file — that's fine
-}
+  const hmrPort = options?.hmrPort ?? 3001;
+  const appPort = options?.port ?? merged.port ?? 3000;
 
-createServer({ port: 3000, ...lifecycle });
-
-watchApp("./app", async (file) => {
-  const { duration } = await rebuildClient();
-
-  // Route files (not layout): do a fine-grained module swap without full reload.
-  // Root, layouts, and other files: fall back to full page reload.
-  const isRoute =
-    file.startsWith("routes/") &&
-    !file.endsWith("layout.tsx") &&
-    !file.endsWith("layout.ts");
-
-  if (isRoute) {
-    const pattern = filePathToPattern(file);
-    // Chunk URL = same basename as route file; splitting build puts it in build/client/
-    const chunkUrl = `/build/client/${basename(file, extname(file))}.js`;
-    hmr.broadcast({ type: "hmr:route", pattern, chunkUrl, file, duration });
-    console.log(`✓ ${file} → module swap (pattern="${pattern}") in ${duration}ms`);
-  } else {
-    hmr.broadcast({ type: "hmr:reload", file, duration });
-    console.log(`✓ ${file} → full reload in ${duration}ms`);
+  const hmr = createHmrServer(hmrPort);
+
+  // Build client bundle before the HTTP server starts accepting requests
+  const { duration: initialMs } = await rebuildClient(merged);
+  console.log(`[bractjs] initial client build in ${initialMs}ms`);
+
+  // Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
+  let lifecycle: LifecycleHooks = {};
+  try {
+    const lifecyclePath = `${process.cwd()}/app/lifecycle.ts`;
+    const mod = await import(lifecyclePath);
+    if (mod.default) lifecycle = mod.default;
+  } catch {
+    // No lifecycle file — that's fine
   }
-});
 
-console.log("BractJS dev server on http://localhost:3000");
+  const srv = createServer({ port: appPort, ...merged, ...lifecycle });
+
+  watchApp(merged.appDir ?? "./app", async (file) => {
+    const { duration } = await rebuildClient(merged);
+
+    // Route files (not layout): do a fine-grained module swap without full reload.
+    // Root, layouts, and other files: fall back to full page reload.
+    const isRoute =
+      file.startsWith("routes/") &&
+      !file.endsWith("layout.tsx") &&
+      !file.endsWith("layout.ts");
+
+    if (isRoute) {
+      const pattern = filePathToPattern(file);
+      // Chunk URL = same basename as route file; splitting build puts it in build/client/
+      const chunkUrl = `/build/client/${basename(file, extname(file))}.js`;
+      hmr.broadcast({ type: "hmr:route", pattern, chunkUrl, file, duration });
+      console.log(`✓ ${file} → module swap (pattern="${pattern}") in ${duration}ms`);
+    } else {
+      hmr.broadcast({ type: "hmr:reload", file, duration });
+      console.log(`✓ ${file} → full reload in ${duration}ms`);
+    }
+  });
+
+  console.log(`BractJS dev server on http://localhost:${appPort}`);
+
+  return {
+    stop() {
+      srv.stop();
+      hmr.stop();
+    },
+  };
+}
+
+// Preserve direct-run behavior: bun run src/dev/server.ts
+if (import.meta.main) {
+  await createDevServer();
+}

package/src/index.ts

@@ -78,3 +78,10 @@ export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
 // i18n utilities (server-side)
 export { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "./server/i18n.ts";
 export type { I18nConfig } from "./server/serve.ts";
+
+// Programmatic API — importable alternatives to the CLI commands
+export { createDevServer } from "./dev/server.ts";
+export type { DevServerOptions, DevServer } from "./dev/server.ts";
+export { runBuild } from "./build/bundler.ts";
+export type { BuildConfig } from "./build/bundler.ts";
+export { loadUserConfig } from "./config/load.ts";

package/src/server/serve.ts

@@ -29,6 +29,8 @@ export interface BractJSConfig {
   sourcemap?: "none" | "linked" | "inline" | "external";
   minify?: boolean;
   clientEnv?: string[];
+  /** User Bun bundler plugins appended to the client build (e.g. bun-plugin-tailwind). */
+  plugins?: import("bun").BunPlugin[];
   buildDir?: string;
   /** Directory for transformed image cache. Defaults to .bract-image-cache */
   imageCacheDir?: string;

package/types/config.d.ts

@@ -1,3 +1,5 @@
+import type { BunPlugin } from "bun";
+
 export interface BractJSConfig {
   /** TCP port to listen on. Default: 3000. */
   port: number;
@@ -15,6 +17,8 @@ export interface BractJSConfig {
   minify?: boolean;
   /** process.env keys allowed to be inlined into client bundles. */
   clientEnv?: string[];
+  /** User Bun bundler plugins appended to the client build (e.g. bun-plugin-tailwind). */
+  plugins?: BunPlugin[];
   /** 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. */
@@ -27,3 +31,13 @@ export interface ServerManifest {
   /** Map of URL pattern → route asset info. */
   routes: Record<string, { file?: string; chunk?: string }>;
 }
+
+/** Subset of BractJSConfig used by the build pipeline. All fields optional. */
+export interface BuildConfig {
+  appDir?: string;
+  buildDir?: string;
+  sourcemap?: "none" | "linked" | "inline" | "external";
+  minify?: boolean;
+  clientEnv?: string[];
+  plugins?: import("bun").BunPlugin[];
+}

package/types/index.d.ts

@@ -7,7 +7,7 @@ export type {
 } from "./route.d.ts";
 
 // ── Config + Server ───────────────────────────────────────────────────────
-export type { BractJSConfig, ServerManifest } from "./config.d.ts";
+export type { BractJSConfig, ServerManifest, BuildConfig } from "./config.d.ts";
 import type { MetaDescriptor } from "./route.d.ts";
 import type { BractJSConfig, ServerManifest } from "./config.d.ts";
 
@@ -205,3 +205,19 @@ export declare function transformCssModule(filePath: string): Promise<{ map: Rec
 
 // ── buildFetchHandler (D1) ───────────────────────────────────────────────
 export declare function buildFetchHandler(config: Partial<import("./config.d.ts").BractJSConfig>): (request: Request) => Promise<Response>;
+
+// ── Programmatic API ─────────────────────────────────────────────────────
+export declare function runBuild(config: import("./config.d.ts").BuildConfig): Promise<void>;
+
+export interface DevServerOptions {
+  port?: number;
+  hmrPort?: number;
+  config?: Partial<BractJSConfig>;
+  skipUserConfig?: boolean;
+}
+export interface DevServer {
+  stop(): void;
+}
+export declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
+
+export declare function loadUserConfig(): Promise<Partial<BractJSConfig>>;