@bractjs/bractjs 0.1.27 → 0.1.29

package/src/build/bundler.ts

@@ -19,6 +19,8 @@ export interface BuildConfig {
   minify?: boolean;
   clientEnv?: string[];
   plugins?: BunPlugin[];
+  /** SPA mode: when `false`, the build also emits the static document shell. */
+  ssr?: boolean;
 }
 
 export async function runBuild(config: BuildConfig): Promise<void> {
@@ -30,6 +32,16 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   const routeFilePaths = routes.map((r) => join(appDir, r.filePath));
   const rootFilePath = join(appDir, "root.tsx");
 
+  // Static route-module lint: surface empty routes and miscased exports at
+  // build time (no execution — just source analysis).
+  const { lintRouteModuleSource } = await import("./route-lint.ts");
+  for (const r of routes) {
+    const src = await Bun.file(join(appDir, r.filePath)).text().catch(() => "");
+    for (const warning of lintRouteModuleSource(src, r.filePath)) {
+      console.warn(`[bract] ${warning}`);
+    }
+  }
+
   // ── 1. Clean stale artefacts ────────────────────────────────────────────
   const buildDir = config.buildDir ?? "build";
   await Promise.all([
@@ -140,5 +152,26 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   // ── 5. Write manifest ──────────────────────────────────────────────────
   const manifest = generateManifest({ clientEntry, rootChunk, routeChunks, mode: "production" });
   await writeManifest(manifest, "build");
+
+  // ── 6. SPA shell (ssr: false) ───────────────────────────────────────────
+  // Emit the static document shell every document GET will serve in SPA mode.
+  if (config.ssr === false) {
+    const { renderSpaShell } = await import("../server/spa.ts");
+    const { installUseClientServerStub } = await import("../server/use-client-runtime.ts");
+    // root.tsx is imported from source here — "use client" components inside
+    // it must null-render exactly as they do on the running server.
+    installUseClientServerStub(appDir);
+    const serverManifest = {
+      clientEntry,
+      rootChunk,
+      routes: Object.fromEntries(
+        Object.entries(manifest.routes).map(([pat, e]) => [pat, { file: e.chunk, chunk: e.chunk }]),
+      ),
+    };
+    const html = await renderSpaShell(appDir, serverManifest);
+    await Bun.write(join(buildDir, "client", "__spa.html"), html);
+    console.log("[bract] SPA shell → build/client/__spa.html");
+  }
+
   console.log("[bract] build complete →", Object.keys(manifest.routes).length, "routes");
 }

package/src/build/prerender.ts

@@ -0,0 +1,88 @@
+import { join } from "node:path";
+import { buildFetchHandler } from "../server/serve.ts";
+import type { ServerManifest } from "../server/render.ts";
+
+export interface PrerenderOptions {
+  /** Concrete paths to prerender (or a function resolving them, e.g. from a DB). */
+  prerender: string[] | (() => string[] | Promise<string[]>);
+  appDir?: string;
+  publicDir?: string;
+  buildDir?: string;
+  /** Override the manifest instead of loading `<buildDir>/route-manifest.json`. */
+  manifest?: ServerManifest;
+}
+
+export interface PrerenderResult {
+  written: string[];
+}
+
+/**
+ * Where a path's prerendered files live under `<buildDir>/client/_prerender`.
+ * Throws on anything that isn't a clean absolute path — these strings come
+ * from user config but become filesystem writes.
+ */
+export function prerenderPaths(path: string): { html: string; data: string } {
+  if (!path.startsWith("/")) {
+    throw new Error(`[bractjs] prerender: paths must start with "/", got ${JSON.stringify(path)}`);
+  }
+  if (path.includes(":") || path.includes("[") || path.includes("*")) {
+    throw new Error(
+      `[bractjs] prerender: ${JSON.stringify(path)} looks like a route PATTERN — ` +
+        `expand dynamic routes to concrete paths (e.g. "/blog/intro", not "/blog/:slug").`,
+    );
+  }
+  const segments = path.split("/").filter(Boolean);
+  if (segments.some((s) => s === ".." || s === ".")) {
+    throw new Error(`[bractjs] prerender: refusing path with dot segments: ${JSON.stringify(path)}`);
+  }
+  const dir = segments.join("/");
+  return {
+    html: dir === "" ? "index.html" : `${dir}/index.html`,
+    data: dir === "" ? "_data.json" : `${dir}/_data.json`,
+  };
+}
+
+/**
+ * Build-time prerendering (SSG): run the production fetch handler in-process
+ * against each configured path and write the HTML document plus its `/_data`
+ * payload (used by client navigations INTO a prerendered page) under
+ * `<buildDir>/client/_prerender/`. The production server serves these before
+ * falling back to dynamic SSR — query-carrying requests stay dynamic.
+ *
+ * Loaders run for real at build time: anything they need (DB, env) must be
+ * available to the build.
+ */
+export async function runPrerender(options: PrerenderOptions): Promise<PrerenderResult> {
+  const buildDir = options.buildDir ?? "./build";
+  const paths = typeof options.prerender === "function" ? await options.prerender() : options.prerender;
+
+  const handler = buildFetchHandler({
+    appDir: options.appDir ?? "./app",
+    publicDir: options.publicDir,
+    buildDir,
+    manifest: options.manifest,
+  });
+
+  const written: string[] = [];
+  for (const path of paths) {
+    const out = prerenderPaths(path);
+
+    const htmlRes = await handler(new Request("http://prerender.local" + path));
+    if (htmlRes.status !== 200) {
+      throw new Error(`[bractjs] prerender: GET ${path} returned ${htmlRes.status}`);
+    }
+    const htmlFile = join(buildDir, "client", "_prerender", out.html);
+    await Bun.write(htmlFile, await htmlRes.text());
+    written.push(htmlFile);
+
+    const dataRes = await handler(
+      new Request("http://prerender.local/_data?path=" + encodeURIComponent(path)),
+    );
+    if (dataRes.status === 200) {
+      const dataFile = join(buildDir, "client", "_prerender", out.data);
+      await Bun.write(dataFile, await dataRes.text());
+      written.push(dataFile);
+    }
+  }
+  return { written };
+}

package/src/build/route-lint.ts

@@ -0,0 +1,49 @@
+import { extractExports } from "./directives.ts";
+
+// The canonical route-module export names. A route file exporting a near-miss
+// (wrong case) of one of these is almost always a mistake — the framework's
+// projection is case-sensitive, so `Loader` is silently ignored.
+export const ROUTE_EXPORT_NAMES = [
+  "default", "loader", "action", "clientLoader", "clientAction", "meta", "headers",
+  "middleware", "beforeLoad", "shouldRevalidate", "searchSchema", "ssr", "Fallback",
+  "handle", "ErrorBoundary", "config", "loaderDeps", "context",
+] as const;
+
+const CANONICAL_LOWER = new Map(ROUTE_EXPORT_NAMES.map((n) => [n.toLowerCase(), n]));
+const CANONICAL_SET = new Set<string>(ROUTE_EXPORT_NAMES);
+
+/** A route is "renderable or does work" if it has any of these. */
+const MEANINGFUL = ["default", "loader", "action", "beforeLoad"];
+
+/**
+ * Static lint of a route module's SOURCE (no execution). Returns human-readable
+ * warning strings. Used by the dev rebuilder and the production build to catch
+ * two common, silent mistakes: a route that renders nothing, and an export
+ * whose casing doesn't match a framework export (so it's ignored).
+ */
+export function lintRouteModuleSource(src: string, filePath: string): string[] {
+  const warnings: string[] = [];
+  const names = extractExports(src);
+  // extractExports misses anonymous `export default () => …` / `export default function() {}`.
+  const hasAnonDefault = /^export\s+default\b/m.test(src) && !names.includes("default");
+  const exportSet = new Set(names);
+  if (hasAnonDefault) exportSet.add("default");
+
+  if (!MEANINGFUL.some((n) => exportSet.has(n))) {
+    warnings.push(
+      `${filePath}: route has no default/loader/action/beforeLoad export — it renders an empty page.`,
+    );
+  }
+
+  for (const name of exportSet) {
+    if (CANONICAL_SET.has(name)) continue;
+    const canonical = CANONICAL_LOWER.get(name.toLowerCase());
+    if (canonical && canonical !== name) {
+      warnings.push(
+        `${filePath}: export "${name}" looks like "${canonical}" — route exports are case-sensitive, so "${name}" is ignored.`,
+      );
+    }
+  }
+
+  return warnings;
+}