alabjs 0.2.5 → 0.3.0-alpha.1

package/src/commands/build.ts

@@ -1,7 +1,10 @@
 import { build as viteBuild, type PluginOption } from "vite";
-import { resolve } from "node:path";
+import { resolve, relative, isAbsolute } from "node:path";
+import { pathToFileURL } from "node:url";
 import { spawn, execSync } from "node:child_process";
-import { existsSync, writeFileSync, readFileSync } from "node:fs";
+import { existsSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { loadUserConfig } from "../config.js";
+import type { FederationConfig } from "../config.js";
 import { preRenderPPRShell, findBuildLayoutFiles, PPR_CACHE_SUBDIR } from "../ssr/ppr.js";
 import type { RouteManifest } from "../router/manifest.js";
 
@@ -149,7 +152,10 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
         ...(visualizerPlugin ? [visualizerPlugin] : []),
       ],
       build: {
-        outDir: resolve(cwd, ".alabjs/dist"),
+        // Output client assets to .alabjs/dist/client/ so the production server's
+        // static handler (which serves from distDir/client/) can find them.
+        outDir: resolve(cwd, ".alabjs/dist/client"),
+        manifest: true,
         ssrManifest: true,
         rolldownOptions: {
           // In SSR mode, we don't use an index.html as the entry point.
@@ -167,9 +173,19 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
 
   await Promise.all(tasks);
 
-  // Write a stable build ID for skew protection (must run after Vite so the
-  // route-manifest.json is in place for the content-hash fallback path).
   const distDir = resolve(cwd, ".alabjs/dist");
+
+  // Scan the app/ directory with the Rust router, normalize paths, and write
+  // route-manifest.json. Must run before writeBuildId (hash) and buildPPRShells.
+  const manifest = await buildRouteManifest(cwd, distDir);
+
+  // Compile all app pages, layouts, and server functions to .alabjs/dist/server/.
+  // Must run after buildRouteManifest so we have the entry list, and before
+  // buildPPRShells which imports the compiled modules.
+  await buildSsrBundle(cwd, distDir, manifest);
+
+  // Write a stable build ID for skew protection (must run after the route
+  // manifest is in place for the content-hash fallback path).
   await writeBuildId(distDir, cwd);
   await buildPPRShells(distDir, cwd);
 
@@ -177,6 +193,12 @@ export async function build({ cwd, skipTypecheck = false, mode = "ssr", analyze
   // Output: .alabjs/dist/client/_alabjs/offline-sw.js (served at /_alabjs/offline-sw.js)
   await buildOfflineSw(cwd);
 
+  // Build federation vendor + exposed modules if configured.
+  const userConfig = await loadUserConfig(cwd);
+  if (userConfig.federation) {
+    await buildFederation(cwd, userConfig.federation);
+  }
+
   console.log("\n  alab  build complete → .alabjs/dist");
 }
 
@@ -234,57 +256,323 @@ async function buildPPRShells(distDir: string, cwd: string): Promise<void> {
   const pprCacheDir = resolve(cwd, PPR_CACHE_SUBDIR);
   let count = 0;
 
-  for (const route of pageRoutes) {
-    const modulePath = resolve(distDir, "server", route.file);
-    if (!existsSync(modulePath)) continue;
+  // Signal to useServerData that it must not make network calls — return
+  // empty placeholders instead so components can render their static shell.
+  process.env["ALAB_PPR_PRERENDER"] = "1";
 
-    // Dynamic import — module is compiled ESM, importable by Node directly.
-    const mod = await import(modulePath) as {
-      default?: unknown;
-      ppr?: unknown;
-      metadata?: Record<string, unknown>;
-    };
+  try {
+    for (const route of pageRoutes) {
+      // esbuild compiles .tsx/.ts → .js; use the compiled path.
+      const modulePath = resolve(distDir, "server", route.file.replace(/\.(tsx?)$/, ".js"));
+      if (!existsSync(modulePath)) continue;
+
+      // Dynamic import — on Windows absolute paths need a file:// URL.
+      const mod = await import(pathToFileURL(modulePath).href) as {
+        default?: unknown;
+        ppr?: unknown;
+        metadata?: Record<string, unknown>;
+      };
+
+      if (mod.ppr !== true) continue;
+      if (typeof mod.default !== "function") {
+        console.warn(`  alab  ppr: ${route.file} has no default export — skipping.`);
+        continue;
+      }
 
-    if (mod.ppr !== true) continue;
-    if (typeof mod.default !== "function") {
-      console.warn(`  alab  ppr: ${route.file} has no default export — skipping.`);
-      continue;
+      // Load layout modules (outermost → innermost).
+      const layoutPaths = findBuildLayoutFiles(route.file, distDir);
+      const layoutMods = await Promise.all(
+        layoutPaths.map((p) => import(pathToFileURL(resolve(distDir, "server", p)).href)),
+      );
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const layouts = layoutMods.map((m: any) => m.default).filter((c: unknown) => typeof c === "function");
+
+      try {
+        await preRenderPPRShell({
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          Page: mod.default as any,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          layouts: layouts as any[],
+          shellOpts: {
+            metadata: (mod.metadata as never) ?? {},
+            paramsJson: "{}",
+            searchParamsJson: "{}",
+            routeFile: route.file,
+            // PPR shells are static snapshots — client mounts via CSR (createRoot)
+            // rather than hydration to avoid mismatches with the pre-rendered HTML.
+            ssr: false,
+            layoutsJson: JSON.stringify(layoutPaths.map(p => p.replace(/\.js$/, ".tsx"))),
+          },
+          pprCacheDir,
+          routePath: route.path,
+        });
+        count++;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`  alab  ppr: failed to pre-render ${route.path}: ${msg}`);
+      }
     }
+  } finally {
+    delete process.env["ALAB_PPR_PRERENDER"];
+  }
 
-    // Load layout modules (outermost → innermost).
-    const layoutPaths = findBuildLayoutFiles(route.file, distDir);
-    const layoutMods = await Promise.all(
-      layoutPaths.map((p) => import(resolve(distDir, "server", p))),
-    );
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const layouts = layoutMods.map((m: any) => m.default).filter((c: unknown) => typeof c === "function");
+  if (count > 0) {
+    console.log(`  alab  ppr  → ${count} shell${count === 1 ? "" : "s"} written to ${PPR_CACHE_SUBDIR}`);
+  }
+}
+
+// ─── Federation build ─────────────────────────────────────────────────────────
+
+/**
+ * Build all federation artefacts after the main SSR bundle:
+ *  1. Vendor ESM chunks for shared React singletons (`/_alabjs/vendor/`)
+ *  2. Exposed component modules (`/_alabjs/remotes/<name>/<ExposedName>.js`)
+ *  3. `federation-config.json` in the dist root (read by `alab start`)
+ *  4. `federation-manifest.json` in the client dir (served at runtime)
+ */
+async function buildFederation(cwd: string, federation: FederationConfig): Promise<void> {
+  const { name, exposes = {}, remotes = {} } = federation;
+  const distClientAlab = resolve(cwd, ".alabjs/dist/client/_alabjs");
+
+  const hasExposes = Object.keys(exposes).length > 0;
+  const hasRemotes = Object.keys(remotes).length > 0;
+
+  if (hasRemotes || hasExposes) {
+    await buildFederationVendors(cwd, distClientAlab, federation.shared ?? []);
+  }
+
+  if (hasExposes) {
+    await buildFederationExposes(cwd, distClientAlab, name, exposes, federation.shared ?? []);
+  }
 
+  // Write federation config for the production server (import map generation).
+  writeFileSync(
+    resolve(cwd, ".alabjs/dist/federation-config.json"),
+    JSON.stringify(federation, null, 2),
+    "utf8",
+  );
+
+  console.log(
+    `  alab  federation → ${Object.keys(exposes).length} exposed, ${Object.keys(remotes).length} remote(s)`,
+  );
+}
+
+/** Build React + react-dom (and any user `shared` packages) as standalone ESM vendor files. */
+async function buildFederationVendors(
+  cwd: string,
+  distClientAlab: string,
+  extraShared: string[] = [],
+): Promise<void> {
+  const vendorDir = resolve(distClientAlab, "vendor");
+  mkdirSync(vendorDir, { recursive: true });
+
+  // Always vendor the React singleton packages.
+  const coreVendors: Array<{ specifier: string; output: string }> = [
+    { specifier: "react",             output: "react.js" },
+    { specifier: "react/jsx-runtime", output: "react-jsx-runtime.js" },
+    { specifier: "react-dom",         output: "react-dom.js" },
+    { specifier: "react-dom/client",  output: "react-dom-client.js" },
+  ];
+  // User-declared shared packages (e.g. "date-fns", "zustand").
+  const extraVendors: Array<{ specifier: string; output: string }> = extraShared.map((pkg) => ({
+    specifier: pkg,
+    output: `${pkg.replace(/\//g, "--")}.js`,
+  }));
+  const vendors = [...coreVendors, ...extraVendors];
+
+  for (const { specifier, output } of vendors) {
+    const virtualId = `\0alabjs-vendor:${specifier}`;
     try {
-      await preRenderPPRShell({
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        Page: mod.default as any,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        layouts: layouts as any[],
-        shellOpts: {
-          metadata: (mod.metadata as never) ?? {},
-          paramsJson: "{}",
-          searchParamsJson: "{}",
-          routeFile: route.file,
-          ssr: true,
+      await viteBuild({
+        root: cwd,
+        configFile: false,
+        plugins: [{
+          name: "alabjs-federation-vendor",
+          resolveId: (id: string) => id === virtualId ? id : null,
+          load: (id: string) =>
+            id === virtualId
+              ? `export * from "${specifier}"; export { default } from "${specifier}";`
+              : null,
+        }],
+        build: {
+          outDir: vendorDir,
+          emptyOutDir: false,
+          lib: {
+            entry: virtualId,
+            formats: ["es"],
+            fileName: () => output,
+          },
+          minify: true,
         },
-        pprCacheDir,
-        routePath: route.path,
+        logLevel: "warn",
       });
-      count++;
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      console.warn(`  alab  ppr: failed to pre-render ${route.path}: ${msg}`);
+      console.warn(`  alab  federation: failed to build vendor ${specifier}: ${String(err)}`);
     }
   }
+}
 
-  if (count > 0) {
-    console.log(`  alab  ppr  → ${count} shell${count === 1 ? "" : "s"} written to ${PPR_CACHE_SUBDIR}`);
+/** Build each exposed module as an externalized ESM chunk for remote consumption. */
+async function buildFederationExposes(
+  cwd: string,
+  distClientAlab: string,
+  appName: string,
+  exposes: Record<string, string>,
+  shared: string[],
+): Promise<void> {
+  const remotesDir = resolve(distClientAlab, `remotes/${appName}`);
+  mkdirSync(remotesDir, { recursive: true });
+
+  const external = [
+    "react",
+    "react/jsx-runtime",
+    "react-dom",
+    "react-dom/client",
+    ...shared,
+  ];
+
+  for (const [exposedName, entryRelPath] of Object.entries(exposes)) {
+    const entryAbs = resolve(cwd, entryRelPath.replace(/^\.\//, ""));
+    try {
+      await viteBuild({
+        root: cwd,
+        configFile: false,
+        build: {
+          outDir: remotesDir,
+          emptyOutDir: false,
+          lib: {
+            entry: entryAbs,
+            formats: ["es"],
+            fileName: () => `${exposedName}.js`,
+          },
+          minify: true,
+          rolldownOptions: { external },
+        },
+        logLevel: "warn",
+      });
+    } catch (err) {
+      console.warn(`  alab  federation: failed to build exposed "${exposedName}": ${String(err)}`);
+    }
+  }
+
+  // Manifest consumed by host apps discovering what this remote exposes.
+  const manifest = {
+    name: appName,
+    exposes: Object.fromEntries(
+      Object.keys(exposes).map((k) => [k, `/_alabjs/remotes/${appName}/${k}.js`]),
+    ),
+  };
+  writeFileSync(
+    resolve(distClientAlab, "federation-manifest.json"),
+    JSON.stringify(manifest, null, 2),
+    "utf8",
+  );
+}
+
+/**
+ * Scan `app/` with the Rust router napi, normalize absolute file paths to
+ * cwd-relative, and write `route-manifest.json` to `distDir`.
+ *
+ * Returns the in-memory manifest so callers can use it immediately without
+ * reading the file back from disk.
+ */
+async function buildRouteManifest(cwd: string, distDir: string): Promise<RouteManifest> {
+  const appDir = resolve(cwd, "app");
+  let manifest: RouteManifest = { routes: [] };
+
+  try {
+    type NapiRoutes = { buildRoutes(appDir: string): string };
+    const mod = await import("@alabjs/compiler") as unknown as { default?: NapiRoutes } & NapiRoutes;
+    const napi = (mod.default ?? mod) as NapiRoutes;
+    const json = napi.buildRoutes(appDir);
+    manifest = JSON.parse(json) as RouteManifest;
+
+    // The Rust scanner stores absolute paths; normalize to cwd-relative so the
+    // production server can construct `distDir/server/<file>` paths correctly.
+    for (const route of manifest.routes) {
+      if (isAbsolute(route.file)) {
+        route.file = relative(cwd, route.file);
+      }
+    }
+  } catch {
+    console.warn(
+      "  alab  warning: Rust compiler unavailable — route manifest will be empty.\n" +
+      "         Run `cargo build --release -p alab-napi && bash scripts/copy-napi-binary.sh`.",
+    );
   }
+
+  mkdirSync(distDir, { recursive: true });
+  writeFileSync(resolve(distDir, "route-manifest.json"), JSON.stringify(manifest, null, 2), "utf8");
+
+  const pages = manifest.routes.filter((r) => r.kind === "page").length;
+  const apis  = manifest.routes.filter((r) => r.kind === "api").length;
+  console.log(`  alab  routes → ${pages} page(s), ${apis} api route(s)`);
+
+  return manifest;
+}
+
+/**
+ * Compile all SSR route files to `distDir/server/` using esbuild's per-file
+ * transpilation mode.
+ *
+ * We use esbuild directly (bundled with Vite) rather than a second viteBuild
+ * call because:
+ *  1. Preserves directory structure via `outbase` without needing
+ *     `preserveModules` (which hangs with some Rolldown versions).
+ *  2. `packages: "external"` externalizes all npm specifiers while inlining
+ *     local relative imports — avoids Node ESM extensionless-import failures.
+ *  3. Much faster: no second Vite startup overhead.
+ */
+async function buildSsrBundle(cwd: string, distDir: string, manifest: RouteManifest): Promise<void> {
+  const entryFiles = manifest.routes.map((r) => resolve(cwd, r.file));
+
+  // Include top-level middleware.ts if present.
+  const middlewarePath = resolve(cwd, "middleware.ts");
+  if (existsSync(middlewarePath)) entryFiles.push(middlewarePath);
+
+  if (entryFiles.length === 0) return;
+
+  // Build the import.meta.env replacement object for esbuild.
+  // Node.js never defines import.meta.env (it's a Vite-only concept), so if
+  // we leave it undefined the compiled server modules throw at runtime on any
+  // reference to import.meta.env.*. We mirror exactly what Vite inlines for
+  // the client build: standard constants + ALAB_PUBLIC_* / VITE_* vars.
+  const publicEnv: Record<string, string> = {};
+  for (const [key, val] of Object.entries(process.env)) {
+    if (key.startsWith("ALAB_PUBLIC_") || key.startsWith("VITE_")) {
+      publicEnv[key] = val ?? "";
+    }
+  }
+  const metaEnv = {
+    PROD: true,
+    DEV: false,
+    SSR: true,
+    MODE: "production",
+    BASE_URL: "/",
+    ...publicEnv,
+  };
+
+  const { build: esbuild } = await import("esbuild");
+  await esbuild({
+    entryPoints: entryFiles,
+    outbase: cwd,      // preserve directory structure: app/page.tsx → server/app/page.js
+    outdir: resolve(distDir, "server"),
+    format: "esm",
+    platform: "node",
+    target: "node22",
+    bundle: true,      // bundle local imports (resolves extensionless paths)
+    packages: "external", // keep all npm specifiers (react, alabjs/*…) as-is
+    jsx: "automatic",
+    jsxImportSource: "react",
+    logLevel: "warning",
+    define: {
+      // Replace the entire import.meta.env expression so property accesses,
+      // destructuring, and optional-chaining all resolve correctly at runtime.
+      "import.meta.env": JSON.stringify(metaEnv),
+    },
+  });
+
+  console.log("  alab  SSR bundle → .alabjs/dist/server");
 }
 
 /** Compile the offline service worker to a standalone iife bundle. */
@@ -305,7 +593,10 @@ async function buildOfflineSw(cwd: string): Promise<void> {
           fileName: () => "offline-sw.js",
         },
         minify: true,
-        rolldownOptions: { output: { inlineDynamicImports: true } },
+        // Note: do NOT set rolldownOptions.output.inlineDynamicImports here.
+        // iife format sets codeSplitting:false which already implies
+        // inlineDynamicImports:true in Rolldown. Setting it explicitly
+        // produces a warning that can cause the build to stall in Rolldown/Vite 8+.
       },
     });
   } catch (err) {

package/src/commands/dev.ts

@@ -1,6 +1,7 @@
 import { createServer } from "vite";
 import { resolve, join } from "node:path";
-import { readdirSync } from "node:fs";
+import { readdirSync, existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { loadUserConfig, buildImportMap } from "../config.js";
 import { Writable } from "node:stream";
 import type { IncomingMessage } from "node:http";
 import {
@@ -63,6 +64,46 @@ async function readJsonBody(req: IncomingMessage): Promise<unknown> {
 export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions) {
   console.log("  alab  starting dev server...\n");
 
+  // Load optional alabjs.config.ts for federation and other user config.
+  const userConfig = await loadUserConfig(cwd);
+  // In dev: only inject remote scope mappings (react is already in Vite's module graph).
+  const importMapJson = userConfig.federation
+    ? buildImportMap(userConfig.federation, /* dev= */ true)
+    : null;
+
+  // If this app exposes federation modules, build them once at dev startup so
+  // the `/_alabjs/remotes/` endpoint can serve them immediately.
+  // No hot-reloading of exposed modules in dev — restart the dev server after changes.
+  if (userConfig.federation?.exposes && Object.keys(userConfig.federation.exposes).length > 0) {
+    const { name, exposes, shared = [] } = userConfig.federation;
+    const devRemotesDir = resolve(cwd, `.alabjs/dev-remotes/${name}`);
+    try {
+      const { mkdirSync } = await import("node:fs");
+      const { build: viteBuildDev } = await import("vite");
+      mkdirSync(devRemotesDir, { recursive: true });
+
+      const external = ["react", "react/jsx-runtime", "react-dom", "react-dom/client", ...shared];
+      for (const [exposedName, entryRelPath] of Object.entries(exposes)) {
+        const entryAbs = resolve(cwd, entryRelPath.replace(/^\.\//, ""));
+        await viteBuildDev({
+          root: cwd,
+          configFile: false,
+          build: {
+            outDir: devRemotesDir,
+            emptyOutDir: false,
+            lib: { entry: entryAbs, formats: ["es"], fileName: () => `${exposedName}.js` },
+            minify: false,
+            rolldownOptions: { external },
+          },
+          logLevel: "warn",
+        });
+      }
+      console.log(`  alab  federation dev → ${Object.keys(exposes).length} exposed module(s) built`);
+    } catch (err) {
+      console.warn(`  alab  federation: dev build of exposed modules failed: ${String(err)}`);
+    }
+  }
+
   // Per-session build ID for skew protection in dev.
   // A new ID is generated each time the dev server starts so that a browser
   // tab left open across a restart will hard-reload on the next navigation
@@ -130,6 +171,46 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
         }
       }
 
+      // ── /_alabjs/federation-manifest.json — expose what this app exposes ────────
+      if (pathname === "/_alabjs/federation-manifest.json") {
+        const fed = userConfig.federation;
+        if (!fed?.exposes || Object.keys(fed.exposes).length === 0) {
+          res.statusCode = 404;
+          res.setHeader("content-type", "application/json");
+          res.end(JSON.stringify({ error: "No federation exposes configured." }));
+          return;
+        }
+        const manifest = {
+          name: fed.name,
+          exposes: Object.fromEntries(
+            Object.keys(fed.exposes).map((k) => [k, `/_alabjs/remotes/${fed.name}/${k}.js`]),
+          ),
+        };
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.setHeader("access-control-allow-origin", "*");
+        res.setHeader("cache-control", "no-store");
+        res.end(JSON.stringify(manifest, null, 2));
+        return;
+      }
+
+      // ── /_alabjs/remotes/:name/:module.js — serve pre-built exposed modules ─────
+      if (pathname.startsWith("/_alabjs/remotes/")) {
+        const relPath = pathname.slice("/_alabjs/remotes/".length);
+        const filePath = resolve(cwd, ".alabjs/dev-remotes", relPath);
+        if (fsExistsSync(filePath)) {
+          res.statusCode = 200;
+          res.setHeader("content-type", "application/javascript; charset=utf-8");
+          res.setHeader("access-control-allow-origin", "*");
+          res.setHeader("cache-control", "no-store");
+          res.end(fsReadFileSync(filePath));
+          return;
+        }
+        res.statusCode = 404;
+        res.end("Not found");
+        return;
+      }
+
       // ── /_alabjs/__devtools — debug dump of routes + server functions ───────────
       if (pathname === "/_alabjs/__devtools") {
         const devRoutes = scanDevRoutes(appDir);
@@ -387,7 +468,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
                 onError(e) { fail(e); },
               });
             });
-            const shell = htmlShellBefore({ metadata: { title: "404 — Not Found" }, paramsJson: "{}", searchParamsJson: "{}", routeFile: "app/not-found.tsx", ssr: true });
+            const shell = htmlShellBefore({ metadata: { title: "404 — Not Found" }, paramsJson: "{}", searchParamsJson: "{}", routeFile: "app/not-found.tsx", ssr: true, ...(importMapJson ? { importMapJson } : {}) });
             const rawHtml = `${shell}${nfContent}${htmlShellAfter({})}`;
             const html = await vite.transformIndexHtml(pathname, rawHtml);
             res.statusCode = 404;
@@ -535,6 +616,7 @@ export async function dev({ cwd, port = 3000, host = "localhost" }: DevOptions)
         loadingFile,
         ssr: ssrEnabled,
         buildId: devBuildId,
+        ...(importMapJson ? { importMapJson } : {}),
       };
       const renderPageHtml = async (): Promise<string> => {
         let rawHtml: string;

package/src/commands/start.ts

@@ -8,7 +8,7 @@ interface StartOptions {
 }
 
 export async function start({ cwd, port = 3000 }: StartOptions) {
-  const manifestPath = resolve(cwd, ".alabjs/route-manifest.json");
+  const manifestPath = resolve(cwd, ".alabjs/dist/route-manifest.json");
 
   let manifest: RouteManifest;
   try {

package/src/components/Image.tsx

@@ -104,38 +104,5 @@ export function Image({
   });
 }
 
-/**
- * Generate a Base64 blur-up placeholder for an image in `public/`.
- *
- * Calls the Rust napi binding to resize the image to 8px wide and encode it
- * as a tiny WebP, then Base64-encodes it into a data URL ready for `blurDataURL`.
- *
- * Run this in a server function — it reads from disk and must not run in the browser.
- *
- * @param src - Path relative to `public/` (e.g. `"/hero.jpg"`)
- * @param publicDir - Absolute path to the `public/` directory
- */
-export async function generateBlurPlaceholder(
-  src: string,
-  publicDir: string,
-): Promise<string> {
-  const { readFile } = await import("node:fs/promises");
-  const { resolve } = await import("node:path");
-
-  const safeSrc = src.replace(/\.\./g, "").replace(/^\/+/, "");
-  const filePath = resolve(publicDir, safeSrc);
-
-  const input = await readFile(filePath);
-
-  let napi: { optimizeImage: (b: Buffer, q: number | null, w: number | null, h: null, fmt: string) => Promise<Buffer> };
-  try {
-    napi = (await import("@alabjs/compiler")) as typeof napi;
-  } catch {
-    // napi not built — return empty string (image still loads, just no blur effect)
-    return "";
-  }
-
-  const tiny = await napi.optimizeImage(input, 40, 8, null, "webp");
-  const b64 = Buffer.from(tiny).toString("base64");
-  return `data:image/webp;base64,${b64}`;
-}
+// generateBlurPlaceholder is server-only (uses node:fs/promises).
+// Import it from "alabjs/components/server" in your server functions.

package/src/components/ImageServer.ts

@@ -0,0 +1,43 @@
+/**
+ * Server-only image utilities.
+ *
+ * Import from "alabjs/components/server" — do NOT import from "alabjs/components"
+ * because this file uses Node.js built-ins (fs, path) and must never be bundled
+ * for the browser.
+ */
+
+/**
+ * Generate a Base64 blur-up placeholder for an image in `public/`.
+ *
+ * Calls the Rust napi binding to resize the image to 8px wide and encode it
+ * as a tiny WebP, then Base64-encodes it into a data URL ready for `blurDataURL`.
+ *
+ * Run this in a server function — it reads from disk and must not run in the browser.
+ *
+ * @param src - Path relative to `public/` (e.g. `"/hero.jpg"`)
+ * @param publicDir - Absolute path to the `public/` directory
+ */
+export async function generateBlurPlaceholder(
+  src: string,
+  publicDir: string,
+): Promise<string> {
+  const { readFile } = await import("node:fs/promises");
+  const { resolve } = await import("node:path");
+
+  const safeSrc = src.replace(/\.\./g, "").replace(/^\/+/, "");
+  const filePath = resolve(publicDir, safeSrc);
+
+  const input = await readFile(filePath);
+
+  let napi: { optimizeImage: (b: Buffer, q: number | null, w: number | null, h: null, fmt: string) => Promise<Buffer> };
+  try {
+    napi = (await import("@alabjs/compiler")) as typeof napi;
+  } catch {
+    // napi not built — return empty string (image still loads, just no blur effect)
+    return "";
+  }
+
+  const tiny = await napi.optimizeImage(input, 40, 8, null, "webp");
+  const b64 = Buffer.from(tiny).toString("base64");
+  return `data:image/webp;base64,${b64}`;
+}

package/src/components/index.ts

@@ -1,4 +1,4 @@
-export { Image, generateBlurPlaceholder } from "./Image.js";
+export { Image } from "./Image.js";
 export type { ImageProps } from "./Image.js";
 export { Link } from "./Link.js";
 export type { LinkProps } from "./Link.js";