@nifrajs/web 0.1.0-alpha.1

package/dist/vite.js

@@ -0,0 +1,144 @@
+/**
+ * `@nifrajs/web/vite` — a **dev-only** server with true HMR, backed by Vite in middleware mode. nifra's
+ * production pipeline stays Bun-native (`@nifrajs/web/build` → `Bun.build`); this is purely for the dev
+ * loop. Bun's own HMR is dev-server-only and DCE's `import.meta.hot` under `Bun.build` (nifra's bundler),
+ * so HMR comes from Vite + the framework's official Vite plugin (React Fast Refresh, Vue/Svelte/Solid
+ * HMR) — which you inject via `plugins` (the same structural-injection idiom as the Bun/codec plugins).
+ *
+ * Flow: Vite serves + HMR-swaps the client modules (nifra's codegen'd entry + the route files); nifra
+ * still **SSRs** each request, and the rendered HTML is run through `vite.transformIndexHtml` so Vite
+ * injects its HMR client + the framework's refresh preamble. Node `http` (not `Bun.serve`) because
+ * Vite's `middlewares` are Connect-style — it runs fine under Bun.
+ */
+import { writeFileSync } from "node:fs";
+import { createServer as createHttpServer, } from "node:http";
+import { relative, resolve as resolvePath } from "node:path";
+import { renderDevErrorOverlay } from "./dev-error.js";
+import { discoverRoutes } from "./fs.js";
+import { generateClientEntry } from "./index.js";
+// The codegen'd client entry is written here (at the Vite root) so Vite serves + HMRs it.
+const DEV_ENTRY = ".nifra-vite-entry.tsx";
+const readNodeBody = async (req) => {
+    if (req.method === "GET" || req.method === "HEAD")
+        return undefined;
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+};
+/** Build a Web `Request` from a Node `IncomingMessage` (+ already-read body) for nifra's `app.fetch`. */
+function toWebRequest(req, body) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (typeof value === "string")
+            headers.set(key, value);
+        else if (Array.isArray(value))
+            for (const v of value)
+                headers.append(key, v);
+    }
+    const url = `http://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+    // Assemble init via an `unknown`-typed `body` slot: a Buffer is a valid request body at runtime
+    // (Bun/undici), but the named `BodyInit` type only exists under the DOM lib (the root program is
+    // DOM-free). `ConstructorParameters<typeof Request>[1]` derives the init type from whichever lib is
+    // active, so this type-checks in both the bun and DOM tsconfig programs.
+    const init = {
+        method: req.method ?? "GET",
+        headers,
+    };
+    if (body !== undefined)
+        init.body = body;
+    return new Request(url, init);
+}
+/**
+ * Start the Vite-backed dev server: Vite serves/HMRs the client; nifra SSRs each request and Vite
+ * injects its HMR client + the framework refresh preamble via `transformIndexHtml`.
+ */
+export async function createViteDevServer(options) {
+    const root = resolvePath(options.root ?? process.cwd());
+    const routesDir = resolvePath(options.routesDir);
+    const port = options.port ?? 3000;
+    // Codegen the client entry with Vite-servable, root-relative specifiers (e.g. `/routes/index.tsx`).
+    const manifest = discoverRoutes(routesDir);
+    const toUrl = (file) => `/${relative(root, `${routesDir}/${file}`)}`;
+    writeFileSync(resolvePath(root, DEV_ENTRY), generateClientEntry(manifest, { clientModule: options.clientModule, resolve: toUrl }));
+    const entryUrl = `/${DEV_ENTRY}`;
+    // Create our HTTP server FIRST, then hand it to Vite as the HMR WebSocket host (`hmr.server`). In
+    // middleware mode Vite would otherwise open a *separate* ws port (24678) — fragile: it conflicts
+    // across restarts ("Port undefined is already in use" → the client never connects). Sharing one
+    // port means HMR rides the same origin as the app, robust across restarts. The handler closes over
+    // `vite`, which is assigned just below before the server starts listening.
+    let vite;
+    let version = 0;
+    let app;
+    const server = createHttpServer((req, res) => {
+        vite.middlewares(req, res, () => {
+            // Not a Vite asset → nifra SSR. (`next` runs after Vite declines, so the body is still readable.)
+            void (async () => {
+                try {
+                    const body = await readNodeBody(req);
+                    const nifraRes = await app.fetch(toWebRequest(req, body));
+                    const contentType = nifraRes.headers.get("content-type") ?? "";
+                    res.statusCode = nifraRes.status;
+                    if (!contentType.includes("text/html")) {
+                        // Data / redirect / asset response — pass through untouched.
+                        for (const [key, value] of nifraRes.headers)
+                            res.setHeader(key, value);
+                        res.end(Buffer.from(await nifraRes.arrayBuffer()));
+                        return;
+                    }
+                    // Inject Vite's HMR client + the framework's refresh preamble into the SSR'd HTML.
+                    const html = await vite.transformIndexHtml(req.url ?? "/", await nifraRes.text());
+                    res.setHeader("content-type", "text/html; charset=utf-8");
+                    res.end(html);
+                }
+                catch (err) {
+                    // Source-map the stack first (Vite maps the bundled frames back to your `.ts`), then render
+                    // the readable dev overlay instead of a bare text dump. Dev-only — production maps to `_error`.
+                    if (err instanceof Error)
+                        vite.ssrFixStacktrace(err);
+                    res.statusCode = 500;
+                    res.setHeader("content-type", "text/html; charset=utf-8");
+                    res.end(renderDevErrorOverlay(err, { method: req.method ?? "GET", url: req.url ?? "/" }));
+                }
+            })();
+        });
+    });
+    // `conditions: ["bun"]` makes Vite resolve nifra's workspace packages (`@nifrajs/web-react/client`, …) to
+    // their TS **source** — so the dev server needs no prior `dist` build of the adapter packages.
+    const usePolling = options.poll ?? process.env.CHOKIDAR_USEPOLLING === "1";
+    const { createServer } = (await import("vite"));
+    vite = await createServer({
+        root,
+        appType: "custom",
+        server: {
+            middlewareMode: true,
+            hmr: { server },
+            // Explicit watch config; poll when native fs events aren't delivered (containers/sandboxes).
+            watch: usePolling ? { usePolling: true, interval: 80 } : {},
+        },
+        plugins: [...(options.plugins ?? [])],
+        resolve: {
+            conditions: [...(options.conditions ?? []), "bun", "module", "browser", "development"],
+        },
+        ...(options.define ? { define: options.define } : {}),
+    });
+    app = await options.createApp(entryUrl, `v=${version}`);
+    // Keep server-render fresh on edits (Vite already HMRs the client live; this is for a hard reload).
+    vite.watcher.on("change", () => {
+        version += 1;
+        Promise.resolve(options.createApp(entryUrl, `v=${version}`))
+            .then((next) => {
+            app = next;
+        })
+            .catch((err) => console.error("[nifra/web/vite] app re-create failed:", err));
+    });
+    await new Promise((done) => server.listen(port, done));
+    return {
+        port,
+        stop: async () => {
+            server.close();
+            await vite.close();
+        },
+    };
+}
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite.js","sourceRoot":"","sources":["../src/vite.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@nifrajs/web",
+  "version": "0.1.0-alpha.1",
+  "description": "Framework-agnostic SSR core for nifra — the render seam + HTML document orchestration.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "preact",
+    "file-routing",
+    "islands",
+    "streaming-ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fs": {
+      "bun": "./src/fs.ts",
+      "types": "./dist/fs.d.ts",
+      "default": "./dist/fs.js"
+    },
+    "./client": {
+      "bun": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./islands": {
+      "bun": "./src/islands.ts",
+      "types": "./dist/islands.d.ts",
+      "default": "./dist/islands.js"
+    },
+    "./build": {
+      "bun": "./src/build.ts",
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    },
+    "./fonts": {
+      "bun": "./src/fonts-google.ts",
+      "types": "./dist/fonts-google.d.ts",
+      "default": "./dist/fonts-google.js"
+    },
+    "./dev": {
+      "bun": "./src/dev.ts",
+      "types": "./dist/dev.d.ts",
+      "default": "./dist/dev.js"
+    },
+    "./vite": {
+      "bun": "./src/vite.ts",
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./plugins/kit": {
+      "bun": "./src/plugins/kit.ts",
+      "types": "./dist/plugins/kit.d.ts",
+      "default": "./dist/plugins/kit.js"
+    },
+    "./plugins/css-modules": {
+      "bun": "./src/plugins/css-modules.ts",
+      "types": "./dist/plugins/css-modules.d.ts",
+      "default": "./dist/plugins/css-modules.js"
+    },
+    "./plugins/scss": {
+      "bun": "./src/plugins/scss.ts",
+      "types": "./dist/plugins/scss.d.ts",
+      "default": "./dist/plugins/scss.js"
+    },
+    "./css-modules": {
+      "types": "./css-modules.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "css-modules.d.ts"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nifrajs/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "sass": "^1.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sass": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "sass": "^1.77.0",
+    "vite": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/web"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/build.ts

@@ -0,0 +1,375 @@
+/**
+ * `@nifrajs/web/build` — the production build (Bun-only, build-time). `buildClient` codegens + bundles
+ * the client entry (content-hashed, code-split); `buildServer` codegens the static-import server
+ * manifest + bundles a self-contained **worker** for the disk-less edge (Cloudflare Workers). Both
+ * are Bun-specific and never on the request path (own subpath, like `@nifrajs/web/fs`); the *output*
+ * runs on any runtime.
+ */
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname, relative, resolve as resolvePath } from "node:path"
+import type { BunPlugin } from "bun"
+import { discoverRoutes } from "./fs.ts"
+import { generateClientEntry, generateServerManifest } from "./index.ts"
+
+// Build-time SSG: prerender opted-in static + dynamic routes to `index.html` (+ static `_data.json`),
+// run after `buildClient`.
+export {
+  type CloudflarePagesRoutes,
+  type CloudflarePagesRoutesOptions,
+  cloudflarePagesRoutes,
+  dataFileFor,
+  htmlFileFor,
+  type PrerenderApp,
+  type PrerenderEntry,
+  type PrerenderOptions,
+  type PrerenderResult,
+  prerenderRoutes,
+} from "./prerender.ts"
+
+export interface BuildClientOptions {
+  /** The `routes/` directory to discover (absolute path). */
+  readonly routesDir: string
+  /** Output directory for the bundle + `manifest.json` (absolute path). */
+  readonly outDir: string
+  /** The adapter's client runtime (exports `mountRouter`), e.g. `"@nifrajs/web-solid/client"`. */
+  readonly clientModule: string
+  /** Route/layout file → import specifier (default: `${routesDir}/${file}`). */
+  readonly resolve?: (file: string) => string
+  /** Adapter build plugins (e.g. `solidBunPlugin("dom")`). */
+  readonly plugins?: readonly BunPlugin[]
+  /** `Bun.build` export conditions (e.g. `["bun", "solid", "browser"]`). */
+  readonly conditions?: readonly string[]
+  /** Compile-time replacements (e.g. `{ "process.env.NODE_ENV": '"production"' }`). */
+  readonly define?: Readonly<Record<string, string>>
+  /** Minify the output (default `true`). */
+  readonly minify?: boolean
+  /** URL prefix the assets are served under (default `"/assets/"`); also Bun's chunk `publicPath`. */
+  readonly publicPath?: string
+}
+
+/** The built asset map — the server reads `entry` for the client script + serves `assets`. */
+export interface BuildManifest {
+  /** URL of the client entry module (content-hashed). */
+  readonly entry: string
+  /** URLs of every emitted asset (entry + chunks) — for serving + preloading. */
+  readonly assets: readonly string[]
+  /** `routeId → [layout chunk URLs…, own chunk URL]` — the chunks a route needs, for `createWebApp`'s
+   * `routePreload` (`<link rel="modulepreload">` the matched route alongside the entry). Each route +
+   * layout is also a build entrypoint, so it gets a named chunk the bootstrap's lazy import dedupes to. */
+  readonly routes: Readonly<Record<string, readonly string[]>>
+  /** The app's bundled, content-hashed stylesheet(s) — the bootstrap's **aggregate** CSS (every
+   * `import './x.css'` reachable from the app). The complete stylesheet regardless of which file
+   * imported the CSS; the always-safe fallback `createWebApp` links when a route has no per-route entry
+   * in {@link routeStyles}. Omitted when the app imports no CSS. */
+  readonly css?: readonly string[]
+  /** `routeId → [chain CSS URLs]` — only the stylesheets the matched route's layout chain + own file
+   * actually use (Bun emits a per-entrypoint CSS bundle per route/layout, with shared-component CSS
+   * inlined into each consumer). `createWebApp` links these instead of the aggregate, so a page ships
+   * only its own CSS. A route is omitted (→ aggregate fallback) when its `[name]` collides with another
+   * route's basename (ambiguous CSS↔route) or the build emitted orphan shared-chunk CSS — correctness
+   * over minimality. Absent entirely when the app imports no CSS. */
+  readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+}
+
+/** The slice of Bun's build metafile nifra reads: per JS output, its source `entryPoint` + the
+ * `cssBundle` Bun emitted for that entry. Used to map each route file → its stylesheet (collision-safe,
+ * keyed by source path). Not yet in `@types/bun`; shape per the Bun bundler docs. */
+interface BunMetafile {
+  readonly outputs: Readonly<
+    Record<string, { readonly entryPoint?: string; readonly cssBundle?: string }>
+  >
+}
+
+const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1)
+/** `[name]` Bun derives for an entrypoint: basename without extension (`users/[id].tsx` → `[id]`). */
+const entryName = (file: string): string => {
+  const base = basename(file)
+  const dot = base.lastIndexOf(".")
+  return dot === -1 ? base : base.slice(0, dot)
+}
+
+/**
+ * Build the client bundle for a file-routed app. Writes the hashed assets + `manifest.json` to
+ * `outDir` and returns the manifest. Throws (with the bundler logs) on build failure — never
+ * silently ships a broken bundle.
+ */
+export async function buildClient(options: BuildClientOptions): Promise<BuildManifest> {
+  const { routesDir, outDir, clientModule } = options
+  const resolve = options.resolve ?? ((file: string) => `${routesDir}/${file}`)
+  const publicPath = options.publicPath ?? "/assets/"
+  mkdirSync(outDir, { recursive: true })
+
+  const routeManifest = discoverRoutes(routesDir)
+  // The bootstrap's filename is `_velo`-namespaced (not `entry.ts`) so its `[name]` can't collide with
+  // a user route named `entry.tsx` when the CSS mapping below excludes the bootstrap's aggregate CSS.
+  const entryFile = `${outDir}/_nifra-entry.ts`
+  writeFileSync(entryFile, generateClientEntry(routeManifest, { clientModule, resolve }))
+
+  // Every unique route/layout/`_404` file (sorted, stable), as ADDITIONAL entrypoints — Bun emits a
+  // named chunk per file that the bootstrap's lazy `import()` dedupes to (verified), so the manifest
+  // can map each route to its chunk URLs for matched-route preload. `resolve(file)` is the same
+  // specifier the bootstrap imports, so the entrypoint + lazy import are the same module (dedup).
+  const routeFiles = [
+    ...new Set([
+      ...routeManifest.routes.map((r) => r.file),
+      ...Object.values(routeManifest.layouts).map((l) => l.file),
+      ...(routeManifest.notFound ? [routeManifest.notFound.file] : []),
+    ]),
+  ].sort()
+
+  // `metafile: true` asks Bun for the input/output graph — specifically `outputs[js].entryPoint`
+  // (the source file) + `outputs[js].cssBundle` (that entry's emitted stylesheet). It's the robust
+  // entry→CSS link for per-route splitting: keyed by the unique source path, so it survives
+  // same-basename collisions (`index.tsx` + `blog/index.tsx`) that a filename match can't. Not yet in
+  // `@types/bun`'s `BuildConfig`, so spread it in (spread props skip the excess-property check).
+  const buildExtras = { metafile: true }
+  const result = await Bun.build({
+    entrypoints: [entryFile, ...routeFiles.map(resolve)],
+    outdir: outDir,
+    target: "browser",
+    naming: "[name]-[hash].[ext]",
+    publicPath,
+    splitting: true, // one chunk per lazily-imported route; shared deps deduped into shared chunks
+    // `import "./x.css"` in a route/component → bundled, minified, content-hashed `.css` asset (Bun
+    // strips the import from the JS; CSS bundling is on by default since Bun 1.2). Mapped to routes
+    // below — both the aggregate and per-route — via the metafile, for `<link>` injection.
+    ...buildExtras,
+    minify: options.minify ?? true,
+    plugins: [...(options.plugins ?? [])],
+    ...(options.conditions ? { conditions: [...options.conditions] } : {}),
+    ...(options.define ? { define: { ...options.define } } : {}),
+  })
+  if (!result.success) {
+    throw new Error(
+      `[nifra/web] client build failed:\n${result.logs.map((l) => String(l)).join("\n")}`,
+    )
+  }
+
+  const toUrl = (path: string): string => `${publicPath}${basename(path)}`
+  // Entry-point outputs come back in entrypoint order: [bootstrap, ...routeFiles]. Map each route file
+  // to its chunk URL by that order (guarded against drift), then a route's chunks = its layout chain +
+  // own file.
+  const entryPoints = result.outputs.filter((o) => o.kind === "entry-point")
+  const bootstrap = entryPoints[0]
+  if (bootstrap === undefined) throw new Error("[nifra/web] build produced no entry-point output")
+  if (entryPoints.length !== routeFiles.length + 1) {
+    throw new Error(
+      `[nifra/web] expected ${routeFiles.length + 1} entry-point outputs (bootstrap + ${routeFiles.length} routes), got ${entryPoints.length}`,
+    )
+  }
+  const fileToChunk = new Map<string, string>()
+  routeFiles.forEach((file, i) => {
+    const out = entryPoints[i + 1] // in range — length checked above
+    if (out !== undefined) fileToChunk.set(file, toUrl(out.path))
+  })
+  const chunksFor = (chainFiles: readonly string[]): string[] =>
+    chainFiles.map((f) => fileToChunk.get(f)).filter((u): u is string => u !== undefined)
+  const routes: Record<string, string[]> = {}
+  for (const route of routeManifest.routes) {
+    routes[route.id] = chunksFor([
+      ...route.layoutIds.map((id) => routeManifest.layouts[id]?.file ?? ""),
+      route.file,
+    ])
+  }
+  if (routeManifest.notFound) routes._404 = chunksFor([routeManifest.notFound.file])
+
+  // CSS — aggregate: an `import "./x.css"` anywhere → a content-hashed `.css` asset (Bun strips the
+  // import from the JS). The bootstrap lazily imports every route, so its **aggregate** stylesheet is
+  // the whole app's CSS — the always-safe fallback `createWebApp` links when a route has no per-route
+  // entry below. Fallback to all CSS assets if Bun emitted no distinct aggregate.
+  const bootstrapName = entryName(entryFile) // `_nifra-entry`
+  const cssNameOf = (path: string): string => {
+    const base = basename(path)
+    return base.slice(0, base.lastIndexOf("-")) // strip `-${hash}.css`
+  }
+  const cssAssets = result.outputs.filter((o) => o.kind === "asset" && o.path.endsWith(".css"))
+  const aggregate = cssAssets
+    .filter((o) => cssNameOf(o.path) === bootstrapName)
+    .map((o) => toUrl(o.path))
+  const css: readonly string[] =
+    aggregate.length > 0 ? aggregate : cssAssets.map((o) => toUrl(o.path))
+
+  // CSS — per-route: each route/layout file is its own entrypoint, so the build metafile records its
+  // `cssBundle` — exactly the CSS that file's subtree uses (shared-component CSS is inlined into each
+  // consumer; verified). Keyed by the metafile's unique source `entryPoint`, so it survives
+  // same-basename collisions (`index.tsx` + `blog/index.tsx`) that a filename match can't. A page then
+  // links only its layout chain + own CSS (deduped); an empty array means the page needs no CSS at all.
+  // Absent (→ aggregate fallback) only if Bun emits no metafile/cssBundle — never silently incomplete.
+  const meta = (result as unknown as { metafile?: BunMetafile }).metafile
+  const cwd = process.cwd()
+  const cssByEntry = new Map<string, string>()
+  for (const out of Object.values(meta?.outputs ?? {})) {
+    if (out.entryPoint !== undefined && out.cssBundle !== undefined) {
+      cssByEntry.set(resolvePath(cwd, out.entryPoint), toUrl(out.cssBundle))
+    }
+  }
+  const stylesFor = (chainFiles: readonly string[]): readonly string[] => {
+    const urls = chainFiles
+      .map((f) => (f ? cssByEntry.get(resolvePath(resolve(f))) : undefined))
+      .filter((u): u is string => u !== undefined)
+    return [...new Set(urls)]
+  }
+  const routeStyles: Record<string, readonly string[]> = {}
+  if (css.length > 0 && cssByEntry.size > 0) {
+    for (const route of routeManifest.routes) {
+      routeStyles[route.id] = stylesFor([
+        ...route.layoutIds.map((id) => routeManifest.layouts[id]?.file ?? ""),
+        route.file,
+      ])
+    }
+    if (routeManifest.notFound) routeStyles._404 = stylesFor([routeManifest.notFound.file])
+  }
+
+  const manifest: BuildManifest = {
+    entry: toUrl(bootstrap.path),
+    assets: result.outputs.map((o) => toUrl(o.path)),
+    routes,
+    ...(css.length > 0 ? { css } : {}),
+    ...(Object.keys(routeStyles).length > 0 ? { routeStyles } : {}),
+  }
+  writeFileSync(`${outDir}/manifest.json`, JSON.stringify(manifest, null, 2))
+  return manifest
+}
+
+export interface BuildServerOptions {
+  /** The `routes/` directory to discover (absolute path). */
+  readonly routesDir: string
+  /** The worker entry module (absolute path) — your `worker.ts`. It imports `{ manifest, clientEntry }`
+   * from the generated `./server-manifest`, builds `createWebApp`, and `export default toFetchHandler(app)`. */
+  readonly serverEntry: string
+  /** Output directory for the bundled worker (absolute path). */
+  readonly outDir: string
+  /** The content-hashed client entry URL (from `buildClient`'s manifest) — **baked** into the generated
+   * server manifest, since a disk-less worker can't read `manifest.json` at runtime. */
+  readonly clientEntry: string
+  /** Route/layout file → import specifier in the generated manifest (default: a relative path from the
+   * manifest's location — written next to `serverEntry` — to `routesDir`). */
+  readonly resolve?: (file: string) => string
+  /** Filename for the generated server-manifest module, written next to `serverEntry` (default
+   * `"server-manifest.ts"`); your `serverEntry` imports it as `./server-manifest`. */
+  readonly manifestFile?: string
+  /** Adapter build plugins (e.g. `solidBunPlugin("ssr")` — Solid routes need their SSR transform at
+   * build time; React's JSX is Bun-native and needs none). */
+  readonly plugins?: readonly BunPlugin[]
+  /** `Bun.build` resolution conditions (default `["workerd", "edge-light", "browser"]`) — selects each
+   * dependency's edge build. */
+  readonly conditions?: readonly string[]
+  /** Compile-time replacements (default `{ "process.env.NODE_ENV": '"production"' }` → production
+   * React/Solid on the edge). Pass an explicit object to override (e.g. `{}` to opt out). */
+  readonly define?: Readonly<Record<string, string>>
+  /** Minify the output (default `true`). */
+  readonly minify?: boolean
+  /** `Bun.build` target (default `"browser"` — the right shape for edge runtimes: Cloudflare Workers,
+   * Vercel Edge, Deno, Deno Deploy). Use `"node"` for a `@nifrajs/node` server (so `node:*` built-ins
+   * stay external), or `"bun"` for a Bun server. The default `conditions` + the edge resolve shims
+   * only apply to the `"browser"` target; `"node"`/`"bun"` resolve their own renderer builds via the
+   * matching condition. */
+  readonly target?: "browser" | "node" | "bun"
+  /** **Lazy/code-split routes** (default `false`): emit `() => import(route)` loaders + bundle with
+   * `splitting`, so each route is its own chunk loaded on first request (smaller cold-start parse)
+   * instead of all parsed at boot. The output becomes the worker entry **+ chunk files** in `outDir`
+   * — on Cloudflare, ship them with wrangler's `no_bundle` + `find_additional_modules` + an ESModule
+   * `rule` (Node/Deno import the chunks natively). Eager (one self-contained file) stays the default. */
+  readonly lazy?: boolean
+}
+
+/** The built worker bundle — point your `wrangler.toml`'s `main` at `worker`. */
+export interface ServerBuild {
+  /** Path to the bundled, self-contained worker entry. */
+  readonly worker: string
+  /** Paths of every emitted output (entry + any code-split chunks) — what to ship to the platform. */
+  readonly outputs: readonly string[]
+}
+
+/**
+ * react-dom's `exports["./server"]` maps the `bun` condition to a Bun-API server build that crashes
+ * on workerd, and `Bun.build` always applies the `bun` condition (it wins over `workerd`/`edge-light`),
+ * so conditions alone can't select the edge build. This shim pins `react-dom/server` to its edge build
+ * (`server.edge.js`, which exports `renderToReadableStream`). A no-op when nothing imports react-dom
+ * (e.g. a Solid worker) — the resolver only runs on a match.
+ */
+const reactDomEdgePlugin = (from: string): BunPlugin => ({
+  name: "nifra-react-dom-edge",
+  setup(build) {
+    build.onResolve({ filter: /^react-dom\/server$/ }, () => ({
+      path: Bun.resolveSync("react-dom/server.edge", from),
+    }))
+  },
+})
+
+/**
+ * `solid-js/web` selects its **server** runtime (`renderToStream`) via the `worker` condition, but
+ * `Bun.build` 1.3.14 **segfaults** when the `worker` condition is active (https://bun.report). And
+ * without `worker`, `browser` (which precedes the other server conditions in solid's exports map)
+ * wins → the *dom* runtime, which can't SSR. So this shim pins `solid-js/web` straight to its server
+ * build, sidestepping the crashing condition. Lazy (resolved on match) + a no-op when nothing imports
+ * `solid-js/web` (e.g. a React worker). Drop it (and use the `worker` condition) once Bun is fixed.
+ */
+const solidWebServerPlugin = (from: string): BunPlugin => ({
+  name: "nifra-solid-web-server",
+  setup(build) {
+    build.onResolve({ filter: /^solid-js\/web$/ }, () => {
+      // solid's `worker`/`node`/`deno` conditions all map to ./web/dist/server.js (its server build).
+      const pkg = Bun.resolveSync("solid-js/package.json", from)
+      return { path: pkg.replace(/package\.json$/, "web/dist/server.js") }
+    })
+  },
+})
+
+/**
+ * Build a self-contained **worker bundle** for a file-routed app on a disk-less edge (Cloudflare
+ * Workers / workerd). Discovers routes (build-time fs), codegens the static-import server manifest
+ * (`generateServerManifest`, written next to `serverEntry`), then bundles `serverEntry` with
+ * `Bun.build` using **edge conditions** + the adapter's SSR plugins. The output imports no `node:fs`
+ * and does no dynamic-path import, so it runs on workerd: point `wrangler.toml`'s `main` at it and
+ * serve the client assets via Workers Assets. Throws (with the bundler logs) on failure — never
+ * silently ships a broken worker.
+ */
+export async function buildServer(options: BuildServerOptions): Promise<ServerBuild> {
+  const { routesDir, serverEntry, outDir, clientEntry } = options
+  const entryDir = dirname(serverEntry)
+  const manifestFile = options.manifestFile ?? "server-manifest.ts"
+  // Default: import routes relative from the generated manifest (next to serverEntry) to routesDir.
+  const rel = relative(entryDir, routesDir).replaceAll("\\", "/")
+  const resolve = options.resolve ?? ((file: string) => `./${rel}/${file}`)
+  mkdirSync(outDir, { recursive: true })
+
+  const lazy = options.lazy ?? false
+  const target = options.target ?? "browser"
+  // Edge (browser) target: Bun's `bun` condition contaminates react-dom's server build + the `worker`
+  // condition segfaults Bun.build on solid, so force the edge/server builds via shims. The `node`/`bun`
+  // targets resolve those correctly via their own condition, so the shims (and edge conditions) don't
+  // apply — defaults become `[target]` (e.g. react-dom → server.node.js under `node`).
+  const edge = target === "browser"
+  const conditions = options.conditions ?? (edge ? ["workerd", "edge-light", "browser"] : [target])
+  const manifest = discoverRoutes(routesDir)
+  writeFileSync(
+    `${entryDir}/${manifestFile}`,
+    generateServerManifest(manifest, { resolve, clientEntry, lazy }),
+  )
+
+  const result = await Bun.build({
+    entrypoints: [serverEntry],
+    outdir: outDir,
+    target,
+    conditions: [...conditions],
+    define: { ...(options.define ?? { "process.env.NODE_ENV": '"production"' }) },
+    minify: options.minify ?? true,
+    // Lazy → one chunk per route (loaded on first request); eager → a single self-contained file.
+    splitting: lazy,
+    plugins: [
+      ...(edge ? [reactDomEdgePlugin(entryDir), solidWebServerPlugin(entryDir)] : []),
+      ...(options.plugins ?? []),
+    ],
+  })
+  if (!result.success) {
+    throw new Error(
+      `[nifra/web] server build failed:\n${result.logs.map((l) => String(l)).join("\n")}`,
+    )
+  }
+  const entryOutput = result.outputs.find((o) => o.kind === "entry-point")
+  if (entryOutput === undefined) {
+    throw new Error("[nifra/web] server build produced no entry-point output")
+  }
+  return { worker: entryOutput.path, outputs: result.outputs.map((o) => o.path) }
+}