@bractjs/bractjs 0.1.0

package/templates/new-app/bractjs.config.ts

@@ -0,0 +1,14 @@
+import type { BractJSConfig } from "bractjs";
+
+const config: BractJSConfig = {
+  port: 3000,
+  appDir: "./app",
+  publicDir: "./public",
+  buildDir: "./build",
+  manifest: { clientEntry: "", routes: {} }, // populated by `bractjs build`
+  minify: true,
+  sourcemap: "external",
+  clientEnv: [],
+};
+
+export default config;

package/templates/new-app/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{APP_NAME}}",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "bractjs dev",
+    "build": "bractjs build",
+    "start": "bractjs start"
+  },
+  "dependencies": {
+    "bractjs": "file:{{BRACT_PATH}}",
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "@types/react-dom": "^19"
+  }
+}

package/types/config.d.ts

@@ -0,0 +1,25 @@
+export interface BractJSConfig {
+  /** TCP port to listen on. Default: 3000. */
+  port: number;
+  /** Absolute or relative path to the app directory (contains routes/, root.tsx). */
+  appDir: string;
+  /** Path to the public static assets directory. */
+  publicDir: string;
+  /** Pre-built server manifest (production). Built by runBuild(). */
+  manifest: ServerManifest;
+  /** Directory where build output is written. Default: "./build". */
+  buildDir?: string;
+  /** Source map strategy passed to Bun.build(). Default: "external". */
+  sourcemap?: "none" | "linked" | "inline" | "external";
+  /** Minify client bundles. Default: true in production. */
+  minify?: boolean;
+  /** process.env keys allowed to be inlined into client bundles. */
+  clientEnv?: string[];
+}
+
+export interface ServerManifest {
+  /** Hashed path to the main client entry bundle. */
+  clientEntry: string;
+  /** Map of URL pattern → route asset info. */
+  routes: Record<string, { file?: string; chunk?: string }>;
+}

package/types/index.d.ts

@@ -0,0 +1,109 @@
+import type { ReactNode, Context } from "react";
+
+// ── Route types ───────────────────────────────────────────────────────────
+export type {
+  LoaderArgs, ActionArgs, MetaDescriptor, MetaArgs,
+  LoaderFunction, ActionFunction, MetaFunction, RouteModule,
+} from "./route.d.ts";
+
+// ── Config + Server ───────────────────────────────────────────────────────
+export type { BractJSConfig, ServerManifest } from "./config.d.ts";
+import type { MetaDescriptor } from "./route.d.ts";
+import type { BractJSConfig, ServerManifest } from "./config.d.ts";
+
+export interface RenderOptions {
+  shell: ReactNode;
+  loaderData: Record<string, unknown>;
+  actionData: unknown;
+  params: Record<string, string>;
+  pathname: string;
+  manifest: ServerManifest;
+  meta: MetaDescriptor[];
+  status?: number;
+}
+
+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;
+export declare function json<T>(data: T, init?: ResponseInit): Response;
+export declare function error(message: string, status?: number): Response;
+
+// ── Errors ────────────────────────────────────────────────────────────────
+export declare class BractJSError extends Error { readonly status: number; }
+export declare class HttpError extends BractJSError {
+  constructor(status: number, message?: string);
+}
+export declare function isRedirect(value: unknown): value is Response;
+export declare function isHttpError(value: unknown): value is HttpError;
+export declare function isBractJSError(value: unknown): value is BractJSError;
+
+// ── Deferred ──────────────────────────────────────────────────────────────
+export declare class Deferred<T> { readonly promise: Promise<T>; }
+export declare function defer<T>(data: Record<string, T | Promise<T>>): unknown;
+export declare function isDeferred(value: unknown): boolean;
+
+// ── Context ───────────────────────────────────────────────────────────────
+export interface RouteManifest {
+  clientEntry: string;
+  routes: Record<string, { file?: string; chunk?: string }>;
+}
+export interface BractJSContextValue {
+  loaderData: Record<string, unknown>;
+  actionData: unknown;
+  params: Record<string, string>;
+  pathname: string;
+  manifest: RouteManifest;
+}
+export declare const BractJSContext: Context<BractJSContextValue>;
+export declare function BractJSProvider(props: { value: BractJSContextValue; children: ReactNode }): ReactNode;
+export declare function useBractJSContext(): BractJSContextValue;
+
+// ── Session ───────────────────────────────────────────────────────────────
+export type { SessionData, Session, CommitOptions, SessionStorage, CookieSessionOptions } from "./session.d.ts";
+import type { SessionStorage, CookieSessionOptions } from "./session.d.ts";
+export declare function createCookieSession(options: CookieSessionOptions): SessionStorage;
+
+// ── Middleware ────────────────────────────────────────────────────────────
+export type { MiddlewareContext, MiddlewareFn } from "./middleware.d.ts";
+import type { MiddlewareFn, MiddlewareContext } from "./middleware.d.ts";
+
+export declare class MiddlewarePipeline {
+  use(fn: MiddlewareFn): this;
+  run(ctx: MiddlewareContext, handler: () => Promise<Response>): Promise<Response>;
+}
+export declare const pipeline: MiddlewarePipeline;
+
+export interface CorsOptions { origin: string | string[]; methods?: string[]; }
+export interface SessionStorageLike { getSession(cookie?: string | null): Promise<{ get(key: string): unknown }>; }
+export interface AuthGuardOptions { session: SessionStorageLike; required?: boolean; }
+export declare function requestLogger(): MiddlewareFn;
+export declare function cors(options: CorsOptions): MiddlewareFn;
+export declare function authGuard(options: AuthGuardOptions): MiddlewareFn;
+
+// ── Client components ─────────────────────────────────────────────────────
+export declare function Scripts(): null;
+export declare function LiveReload(): ReactNode;
+export declare function Outlet(): ReactNode;
+
+export interface LinkProps { to: string; prefetch?: "hover" | "none"; children?: ReactNode; className?: string; [key: string]: unknown; }
+export declare function Link(props: LinkProps): ReactNode;
+
+export interface FormProps { method?: "post" | "put" | "delete"; action?: string; children?: ReactNode; [key: string]: unknown; }
+export declare function Form(props: FormProps): ReactNode;
+
+export interface AwaitProps<T> { resolve: Promise<T>; fallback: ReactNode; children: (data: T) => ReactNode; }
+export declare function Await<T>(props: AwaitProps<T>): ReactNode;
+
+// ── Client hooks ──────────────────────────────────────────────────────────
+export declare function useLoaderData<T = unknown>(): T;
+export declare function useActionData<T = unknown>(): T | null;
+export declare function useParams(): Record<string, string>;
+export type NavigationState = "idle" | "loading" | "submitting";
+export declare function useNavigation(): { state: NavigationState };
+export interface FetcherResult {
+  data: unknown;
+  state: NavigationState;
+  load(path: string): Promise<void>;
+  submit(path: string, opts: { method: string; body: FormData | Record<string, string> }): Promise<void>;
+}
+export declare function useFetcher(): FetcherResult;

package/types/middleware.d.ts

@@ -0,0 +1,19 @@
+export interface MiddlewareContext {
+  request: Request;
+  params: Record<string, string>;
+  /** Arbitrary values threaded through the middleware chain into loaders. */
+  context: Record<string, unknown>;
+}
+
+export type MiddlewareFn = (
+  ctx: MiddlewareContext,
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
+export declare class MiddlewarePipeline {
+  use(fn: MiddlewareFn): this;
+  run(ctx: MiddlewareContext, handler: () => Promise<Response>): Promise<Response>;
+}
+
+/** Module-level singleton pipeline — register app-wide middleware here. */
+export declare const pipeline: MiddlewarePipeline;

package/types/route.d.ts

@@ -0,0 +1,41 @@
+import type { ComponentType } from "react";
+
+export interface LoaderArgs {
+  request: Request;
+  params: Record<string, string>;
+  context: Record<string, unknown>;
+}
+
+export interface ActionArgs extends LoaderArgs {
+  formData: FormData;
+}
+
+export type MetaDescriptor =
+  | { title: string }
+  | { name: string; content: string }
+  | { property: string; content: string }
+  | { [key: string]: string };
+
+export interface MetaArgs<T = unknown> {
+  loaderData: T;
+  params: Record<string, string>;
+}
+
+export type LoaderFunction<T = unknown> = (
+  args: LoaderArgs,
+) => Promise<T | Response> | T | Response;
+
+export type ActionFunction<T = unknown> = (
+  args: ActionArgs,
+) => Promise<T | Response> | T | Response;
+
+export type MetaFunction<T = unknown> = (args: MetaArgs<T>) => MetaDescriptor[];
+
+export interface RouteModule<TLoader = unknown, TAction = unknown> {
+  loader?: LoaderFunction<TLoader>;
+  action?: ActionFunction<TAction>;
+  meta?: MetaFunction<TLoader>;
+  handle?: Record<string, unknown>;
+  ErrorBoundary?: ComponentType<{ error: unknown }>;
+  default?: ComponentType;
+}

package/types/session.d.ts

@@ -0,0 +1,32 @@
+export type SessionData = Record<string, unknown>;
+
+export interface Session {
+  get(key: string): unknown;
+  set(key: string, val: unknown): void;
+  delete(key: string): void;
+  has(key: string): boolean;
+}
+
+export interface CommitOptions {
+  maxAge?: number;
+}
+
+export interface SessionStorage {
+  getSession(cookie?: string | null): Promise<Session>;
+  commitSession(session: Session, opts?: CommitOptions): Promise<string>;
+}
+
+export interface CookieSessionOptions {
+  /** Cookie name (e.g. "__session"). */
+  name: string;
+  /** One or more secrets for HMAC signing. Rotation: add new secret first. */
+  secrets: string[];
+  /** Max age in seconds. Omit for session cookie. */
+  maxAge?: number;
+  /** Set the Secure flag. Default: true. */
+  secure?: boolean;
+  /** SameSite policy. Default: "Lax". */
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+export declare function createCookieSession(options: CookieSessionOptions): SessionStorage;