@k2b/ssr 0.12.0-rc.0

package/src/adapter/utils.ts

@@ -0,0 +1,190 @@
+/**
+ * Shared utilities for SSR adapters - path helpers, asset responses,
+ * SSE live reload, and security utilities.
+ */
+import { dirname, join, resolve } from "path";
+import type { SsrConfig } from "../index";
+
+/**
+ * Normalize a public app base path.
+ * - undefined, "", "/" => ""
+ * - "/docs/" => "/docs"
+ * - values without leading slash are rejected
+ */
+export const normalizeBasePath = (input?: string): string => {
+  const value = input?.trim() ?? "";
+  if (!value || value === "/") return "";
+  if (!value.startsWith("/")) {
+    throw new Error(`[ssr] basePath must start with "/" or be empty. Received: ${JSON.stringify(input)}`);
+  }
+  return value.replace(/\/+$/, "");
+};
+
+/**
+ * Public HTTP path prefix used for SSR assets/endpoints.
+ */
+export const toSsrPath = (basePath: string): string =>
+  basePath ? `${basePath}/_ssr` : "/_ssr";
+
+/**
+ * Get the _ssr directory path based on dev/prod mode.
+ * Dev: uses config.rootDir (fallback process.cwd())
+ * Prod: uses dirname(Bun.main) (next to compiled binary)
+ */
+export const getSsrDir = (config: SsrConfig): string =>
+  join(config.dev ? config.rootDir ?? process.cwd() : dirname(Bun.main), "_ssr");
+
+const HASHED_CHUNK = /^chunk-[a-z0-9]+\.js$/i;
+const ASSET_FILE = /^[a-z0-9._-]+\.js(?:\.map)?$/i;
+
+/**
+ * Stable entry names can change during development. Content-hashed chunks
+ * cannot, so the browser may retain them across page navigations.
+ */
+export const getCacheHeaders = (dev: boolean, filename = "") =>
+  !dev || HASHED_CHUNK.test(filename) ? "public, max-age=31536000, immutable" : "no-cache";
+
+const matchesEtag = (header: string, etag: string): boolean => {
+  const normalized = etag.replace(/^W\//, "");
+  return header.split(",").some((candidate) => {
+    const value = candidate.trim();
+    return value === "*" || value.replace(/^W\//, "") === normalized;
+  });
+};
+
+const isNotModified = (request: Request, etag: string, lastModified: number): boolean => {
+  const ifNoneMatch = request.headers.get("If-None-Match");
+  if (ifNoneMatch) return matchesEtag(ifNoneMatch, etag);
+
+  const ifModifiedSince = request.headers.get("If-Modified-Since");
+  if (!ifModifiedSince) return false;
+  const since = Date.parse(ifModifiedSince);
+  return Number.isFinite(since) && Math.floor(lastModified / 1000) <= Math.floor(since / 1000);
+};
+
+/**
+ * Serves generated island assets without eagerly buffering their contents.
+ * Dev validators make stable entries cheap to revalidate while preserving
+ * immediate rebuild visibility.
+ */
+export const createAssetResponse = async (
+  request: Request,
+  directory: string,
+  filename: string,
+  dev: boolean,
+): Promise<Response> => {
+  if (!ASSET_FILE.test(filename)) return notFound();
+  const path = safePath(directory, filename);
+  if (!path) return notFound();
+
+  const contentType = filename.endsWith(".map")
+    ? "application/json; charset=utf-8"
+    : "application/javascript";
+  const file = Bun.file(path, { type: contentType });
+  if (!(await file.exists())) return notFound();
+
+  const cacheControl = getCacheHeaders(dev, filename);
+  if (!dev) {
+    return new Response(file, {
+      headers: { "Content-Type": contentType, "Cache-Control": cacheControl },
+    });
+  }
+
+  const lastModified = file.lastModified;
+  const etag = `W/"${file.size.toString(16)}-${Math.trunc(lastModified).toString(16)}"`;
+  const validatorHeaders = {
+    "Cache-Control": cacheControl,
+    ETag: etag,
+    "Last-Modified": new Date(lastModified).toUTCString(),
+  };
+
+  if (isNotModified(request, etag, lastModified)) {
+    return new Response(null, { status: 304, headers: validatorHeaders });
+  }
+
+  return new Response(file, {
+    headers: { "Content-Type": contentType, ...validatorHeaders },
+  });
+};
+
+/**
+ * SSE headers for live reload
+ */
+export const SSE_HEADERS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "no-cache",
+  Connection: "keep-alive",
+} as const;
+
+const reloadId = crypto.randomUUID();
+const reloadConnected = new TextEncoder().encode(`: connected\ndata: ${reloadId}\n\n`);
+const reloadPing = new TextEncoder().encode(": ping\n\n");
+
+export const getReloadId = (): string => reloadId;
+
+export const createPingResponse = (): Response =>
+  new Response("ok", { headers: { "X-SSR-Reload-ID": reloadId } });
+
+/**
+ * Creates a Server-Sent Events stream for live reload
+ */
+export const createReloadStream = (signal?: AbortSignal): ReadableStream<Uint8Array> => {
+  let interval: ReturnType<typeof setInterval> | undefined;
+  let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+  const handleAbort = () => {
+    stopHeartbeat();
+    try {
+      streamController?.close();
+    } catch {
+      // The consumer may already have canceled the stream.
+    }
+  };
+  const stopHeartbeat = () => {
+    if (interval === undefined) return;
+    clearInterval(interval);
+    interval = undefined;
+    signal?.removeEventListener("abort", handleAbort);
+  };
+
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      streamController = controller;
+      if (signal?.aborted) {
+        controller.close();
+        return;
+      }
+
+      signal?.addEventListener("abort", handleAbort, { once: true });
+      controller.enqueue(reloadConnected);
+      interval = setInterval(() => {
+        try {
+          controller.enqueue(reloadPing);
+        } catch {
+          stopHeartbeat();
+        }
+      }, 5000);
+    },
+    cancel: stopHeartbeat,
+  });
+};
+
+/**
+ * Creates a Response for the SSE reload endpoint
+ */
+export const createReloadResponse = (signal?: AbortSignal): Response =>
+  new Response(createReloadStream(signal), { headers: SSE_HEADERS });
+
+/**
+ * 404 Response
+ */
+export const notFound = (): Response =>
+  new Response("Not found", { status: 404 });
+
+/**
+ * Safely join paths, preventing path traversal attacks.
+ * Returns null if the resulting path escapes the base directory.
+ */
+export const safePath = (base: string, filename: string): string | null => {
+  const resolved = resolve(base, filename);
+  return resolved.startsWith(resolve(base) + "/") ? resolved : null;
+};

package/src/build.ts

@@ -0,0 +1,230 @@
+/**
+ * Island bundler - discovers *.island.tsx and *.client.tsx files,
+ * transforms them for the browser, and outputs chunks to _ssr directory.
+ */
+import { relative, resolve } from "path";
+import { Glob } from "bun";
+import { unlink } from "fs/promises";
+import { transform } from "./transform";
+import { ISLAND_ID_LENGTH, islandIdFromFile, toStableKey } from "./island-id";
+
+type ComponentType = "island" | "client";
+
+export type DevSourcemap = "none" | "linked" | "inline";
+
+const getComponentType = (path: string): ComponentType => (path.includes(".client.") ? "client" : "island");
+
+const getSelector = (type: ComponentType, id: string) =>
+  type === "island" ? `solid-island[data-id="${id}"]` : `solid-client[data-id="${id}"]`;
+
+const fmt = (ms: number) => (ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${Math.round(ms)}ms`);
+const GENERATED_ASSET = /^(?:[a-f0-9]{12}|chunk-[a-z0-9]+)\.js(?:\.map)?$/i;
+
+const removeStaleBuildAssets = async (outdir: string, outputs: readonly Bun.BuildArtifact[]): Promise<number> => {
+  const current = new Set(outputs.map((output) => resolve(output.path)));
+  let removed = 0;
+
+  for await (const file of new Glob("*.js*").scan({ cwd: outdir, absolute: true })) {
+    const filename = file.slice(file.lastIndexOf("/") + 1);
+    if (!GENERATED_ASSET.test(filename) || current.has(resolve(file))) continue;
+    await unlink(file);
+    removed += 1;
+  }
+
+  return removed;
+};
+
+/**
+ * Workaround for Bun bundler bug: duplicate export statements in shared chunks
+ * when splitting=true. We only run this in production because rewriting chunk
+ * source in dev can affect evaluation order in cyclic-sensitive modules.
+ */
+export const dedupeSharedChunkExports = async (outdir: string, verbose: boolean): Promise<number> => {
+  let fixedChunks = 0;
+  const chunkGlob = new Glob("chunk-*.js");
+  for await (const chunkFile of chunkGlob.scan({ cwd: outdir, absolute: true })) {
+    const src = await Bun.file(chunkFile).text();
+    // Collect all export blocks and deduplicate.
+    const exportRegex = /^export\s*\{[^}]*\}\s*;?\s*$/gm;
+    const exportBlocks = [...src.matchAll(exportRegex)].map((m) => m[0]);
+    if (exportBlocks.length > 1) {
+      // Parse all exported names from all blocks.
+      const seenNames = new Set<string>();
+      const uniqueBlocks: string[] = [];
+      for (const block of exportBlocks) {
+        const names =
+          block
+            .match(/\{([^}]*)\}/)?.[1]
+            ?.split(",")
+            .map((n) => n.trim())
+            .filter(Boolean) ?? [];
+        const newNames = names.filter((n) => !seenNames.has(n));
+        if (newNames.length > 0) {
+          uniqueBlocks.push(`export { ${newNames.join(", ")} };`);
+          newNames.forEach((n) => seenNames.add(n));
+        }
+      }
+      // Replace all export blocks with deduplicated ones.
+      let fixed = src;
+      for (const block of exportBlocks) {
+        fixed = fixed.replace(block, "");
+      }
+      // Append single combined export before any debugId comment.
+      const debugIdIdx = fixed.lastIndexOf("//# debugId=");
+      const combined = uniqueBlocks.join("\n") + "\n";
+      if (debugIdIdx !== -1) {
+        fixed = fixed.slice(0, debugIdIdx) + combined + fixed.slice(debugIdIdx);
+      } else {
+        fixed = fixed.trimEnd() + "\n" + combined;
+      }
+      await Bun.write(chunkFile, fixed);
+      fixedChunks += 1;
+      if (verbose) console.log(`  Fixed duplicate exports in ${chunkFile.split("/").pop()}`);
+    }
+  }
+  return fixedChunks;
+};
+
+export const buildIslands = async (options: {
+  pattern: string;
+  outdir: string;
+  cwd: string;
+  verbose: boolean;
+  dev?: boolean;
+  devSourcemap?: DevSourcemap;
+  external?: string[];
+}): Promise<void> => {
+  const { pattern, outdir, cwd, verbose, dev = false, devSourcemap = "linked", external } = options;
+  const resolvedCwd = resolve(cwd);
+
+  const totalStart = performance.now();
+
+  const files: string[] = [];
+
+  const scanStart = performance.now();
+  for await (const file of new Glob(pattern).scan({
+    cwd: resolvedCwd,
+    absolute: true,
+  })) {
+    files.push(file);
+  }
+  if (verbose) console.log(`Scan: found ${files.length} file(s) in ${fmt(performance.now() - scanStart)}`);
+
+  if (!files.length) {
+    if (verbose) console.log("No island/client files found.");
+    return;
+  }
+
+  // Build component metadata
+  const components = files.map((componentPath) => {
+    const id = islandIdFromFile(componentPath, resolvedCwd);
+    const key = toStableKey(componentPath, resolvedCwd);
+    const type = getComponentType(componentPath);
+    const selector = getSelector(type, id);
+    return { path: componentPath, id, key, type, selector };
+  });
+
+  // Detect hash collisions and fail fast with actionable diagnostics
+  const idMap = new Map<string, typeof components>();
+  for (const c of components) {
+    if (!idMap.has(c.id)) {
+      idMap.set(c.id, []);
+    }
+    idMap.get(c.id)!.push(c);
+  }
+
+  const collisions = [...idMap.entries()].filter(([, items]) => items.length > 1);
+  if (collisions.length > 0) {
+    const details = collisions
+      .map(([id, items]) => {
+        const list = items.map((item) => `    - ${item.key} (${relative(resolvedCwd, item.path)})`).join("\n");
+        return `  ID ${id}:\n${list}`;
+      })
+      .join("\n");
+    throw new Error(`[ssr] Island ID collision detected. Rename files or adjust roots.\n${details}`);
+  }
+
+  // Build all islands together with code splitting
+  // This ensures Solid is only bundled once as a shared chunk
+  const transformTimings = verbose ? new Map<string, number>() : undefined;
+  const bundleStart = performance.now();
+  const result = await Bun.build({
+    entrypoints: components.map((c) => c.id),
+    outdir,
+    naming: { entry: "[name].js", chunk: "chunk-[hash].js" },
+    target: "browser",
+    external,
+    minify: !dev,
+    splitting: true,
+    sourcemap: dev ? devSourcemap : "none",
+    plugins: [
+      {
+        name: "solid-islands",
+        setup(build) {
+          // Resolve component IDs as virtual entrypoints
+          build.onResolve({ filter: new RegExp(`^[a-f0-9]{${ISLAND_ID_LENGTH}}$`) }, (args) => ({
+            path: args.path,
+            namespace: "island",
+          }));
+
+          // Generate hydration code for each component
+          build.onLoad({ filter: /.*/, namespace: "island" }, (args) => {
+            const component = components.find((c) => c.id === args.path);
+            if (!component) {
+              return { contents: "", loader: "js" };
+            }
+
+            return {
+              contents: `import{render,createComponent}from"solid-js/web";import{deserialize}from"seroval";import C from"${component.path}";document.querySelectorAll('${component.selector}').forEach(e=>{e.innerHTML="";render(()=>createComponent(C,deserialize(e.dataset.props||"{}")),e)})`,
+              loader: "js",
+            };
+          });
+
+          // Transform TSX/JSX with Solid DOM mode
+          build.onLoad({ filter: /\.(tsx|jsx)$/ }, async ({ path }) => {
+            const t0 = performance.now();
+            // Import with ? suffix to register file with bun --watch
+            // Issue: https://github.com/oven-sh/bun/issues/4689
+            const contents = await import(`${path}?`, {
+              with: { type: "text" },
+            });
+            const result = {
+              contents: await transform(contents.default, path, "dom"),
+              loader: "js" as const,
+            };
+            transformTimings?.set(path, performance.now() - t0);
+            return result;
+          });
+        },
+      },
+    ],
+  });
+
+  if (result.success) {
+    const removed = await removeStaleBuildAssets(outdir, result.outputs);
+    if (verbose && removed > 0) console.log(`Removed ${removed} stale build asset(s).`);
+
+    if (!dev) {
+      await dedupeSharedChunkExports(outdir, verbose);
+    } else if (verbose) {
+      console.log("Skipped shared-chunk export rewrite in dev mode.");
+    }
+  }
+
+  if (verbose) {
+    console.log(`Bundle: ${fmt(performance.now() - bundleStart)}`);
+    for (const c of components) {
+      const rel = relative(resolvedCwd, c.path);
+      const t = transformTimings?.get(c.path);
+      console.log(`  ${rel} -> ${outdir}/${c.id}.js${t != null ? ` (transform: ${fmt(t)})` : ""}`);
+    }
+  }
+  console.log(
+    `Built ${files.length} component(s) to ${outdir}/ in ${fmt(performance.now() - totalStart)}${verbose ? " (total)" : ""}`,
+  );
+
+  if (!result.success) {
+    console.error("Build failed:");
+    result.logs.forEach((m) => console.error(`  ${m}`));
+  }
+};

package/src/index.ts

@@ -0,0 +1,246 @@
+/**
+ * Core SSR module - exports createConfig() which provides:
+ * - config: SSR configuration for adapters
+ * - plugin: Bun plugin for build/dev that transforms islands
+ * - html: Renders JSX to Response with hydration scripts
+ */
+import { renderToString } from "solid-js/web";
+import type { JSX } from "solid-js";
+import type { BunPlugin } from "bun";
+import { statSync } from "fs";
+import { transform } from "./transform";
+import { buildIslands, type DevSourcemap } from "./build";
+import { join, dirname, resolve } from "path";
+import { resolveIslandImport } from "./island-resolve";
+import { getReloadId, normalizeBasePath, toSsrPath } from "./adapter/utils";
+// @ts-ignore - Bun text import
+import devClientCode from "./adapter/client.js" with { type: "text" };
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Glob pattern for island/client component files */
+const COMPONENT_PATTERN = "**/*.{island,client}.tsx";
+
+/**
+ * Build version used for cache busting island script imports in production.
+ * Uses server entrypoint mtime as a stable per-build version value.
+ */
+const getBuildVersion = (dev: boolean): string => {
+  if (dev) return "";
+  try {
+    return String(Math.floor(statSync(Bun.main).mtimeMs));
+  } catch {
+    return String(Date.now());
+  }
+};
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type SsrOptions<T extends object = object> = {
+  /** Enable dev mode (default: false) */
+  dev?: boolean;
+  /** Enable verbose logging (default: true in prod, false in dev) */
+  verbose?: boolean;
+  /** Project root for island discovery and dev _ssr assets (default: process.cwd()) */
+  rootDir?: string;
+  /** Public app mount path for SSR assets and dev endpoints (default: "") */
+  basePath?: string;
+  /** Modules to exclude from the island bundle (passed to Bun.build) */
+  external?: string[];
+  /** Development island sourcemaps (default: "linked") */
+  devSourcemap?: DevSourcemap;
+  /** HTML template function (optional, has default) */
+  template?: (
+    ctx: {
+      body: string;
+      scripts: string;
+    } & T,
+  ) => string | Promise<string>;
+};
+
+export type SsrConfig = {
+  dev: boolean;
+  verbose?: boolean;
+  rootDir?: string;
+  basePath: string;
+  ssrPath: string;
+};
+
+export type RenderFn = () => JSX.Element;
+
+export type HtmlFn<T extends object> = (render: RenderFn, options?: T) => Promise<Response>;
+
+type PluginFn = () => BunPlugin;
+
+export type SsrResult<T extends object> = {
+  config: SsrConfig;
+  plugin: PluginFn;
+  html: HtmlFn<T>;
+};
+
+// ============================================================================
+// createConfig() - Create SSR configuration
+// ============================================================================
+
+/**
+ * Creates SSR configuration, html renderer, and build plugin.
+ *
+ * Components follow naming conventions:
+ * - `*.island.tsx` - SSR rendered + hydrated on client (interactive)
+ * - `*.client.tsx` - Client-only rendered (not SSR)
+ *
+ * @example
+ * ```ts
+ * // config.ts
+ * import { createConfig } from "@k2b/ssr";
+ *
+ * type PageOptions = { title?: string };
+ *
+ * export const { config, plugin, html } = createConfig<PageOptions>({
+ *   dev: process.env.NODE_ENV === "development",
+ *   template: ({ body, scripts, title }) => `
+ *     <!DOCTYPE html>
+ *     <html>
+ *       <head><title>${title ?? "App"}</title></head>
+ *       <body>${body}</body>
+ *       ${scripts}
+ *     </html>
+ *   `,
+ * });
+ * ```
+ */
+export const createConfig = <T extends object = object>(options: SsrOptions<T> = {}): SsrResult<T> => {
+  const {
+    dev = false,
+    verbose,
+    external,
+    devSourcemap = "linked",
+    template,
+    rootDir: rootDirOption,
+    basePath: basePathOption,
+  } = options;
+  const rootDir = resolve(rootDirOption ?? process.cwd());
+  const basePath = normalizeBasePath(basePathOption);
+  const ssrPath = toSsrPath(basePath);
+
+  // Default template if none provided
+  const htmlTemplate =
+    template ??
+    (({ body, scripts }) => `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+      </head>
+      <body>
+        ${body}
+        ${scripts}
+      </body>
+    </html>
+  `);
+
+  // Config object for routes adapters
+  const config: SsrConfig = {
+    dev,
+    verbose,
+    rootDir,
+    basePath,
+    ssrPath,
+  };
+
+  const buildVersion = getBuildVersion(dev);
+
+  const islandDisplayStyle =
+    "<style>solid-client,solid-island{display:contents}</style>";
+
+  // Hydration script - dynamically loads island/client bundles based on DOM
+  const hydrationScript = `<script type="module">const p=${JSON.stringify(ssrPath)};const v=${JSON.stringify(buildVersion)};document.querySelectorAll('solid-island,solid-client').forEach(e=>import(p+'/'+e.dataset.id+'.js'+(v?'?v='+v:'')));</script>`;
+  const devConfigScript = `<script>globalThis.__SSR_CONFIG=${JSON.stringify({ ssrPath, reloadId: getReloadId() })}</script>`;
+
+  // HTML renderer
+  const html: HtmlFn<T> = async (render, opts = {} as T) => {
+    if (render.constructor.name === "AsyncFunction") {
+      throw new Error("[ssr] html() expects a synchronous render function: html(() => <Page />)");
+    }
+
+    const body = renderToString(render);
+
+    // Framework-injected assets
+    let scripts = `${islandDisplayStyle}\n${hydrationScript}`;
+
+    // Add dev tools script in dev mode (inlined)
+    if (dev) {
+      scripts += `\n${devConfigScript}\n<script type="module">${devClientCode}</script>`;
+    }
+
+    const content = await htmlTemplate({
+      body,
+      scripts,
+      ...opts,
+    });
+
+    return new Response(content, {
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  };
+
+  // Build islands once per run
+  let islandsBuilt = false;
+
+  // Bun plugin for build/dev
+  const plugin: PluginFn = () => {
+    return {
+      name: "solid-ssr",
+      setup(build) {
+        // Determine output directory
+        const prodOutdir = build.config?.outdir;
+        const islandsOutdir = prodOutdir ? join(prodOutdir, "_ssr") : join(rootDir, "_ssr");
+
+        const ensureIslands = async () => {
+          if (islandsBuilt) return;
+          islandsBuilt = true;
+          await buildIslands({
+            pattern: COMPONENT_PATTERN,
+            outdir: islandsOutdir,
+            cwd: rootDir,
+            verbose: verbose ?? !dev,
+            dev,
+            devSourcemap,
+            external,
+          });
+        };
+
+        // Build islands on start (works for Bun.build)
+        build.onStart?.(ensureIslands);
+
+        // Handle .island and .client imports (without .tsx extension)
+        build.onResolve({ filter: /\.(island|client)$/ }, (args) => {
+          const resolveDir = args.resolveDir || (args.importer ? dirname(args.importer) : rootDir);
+          return {
+            path: resolveIslandImport(args.path, resolveDir, args.importer || undefined),
+          };
+        });
+
+        // Transform TSX/JSX files with Solid SSR
+        build.onLoad({ filter: /\.(tsx|jsx)$/ }, async ({ path }) => {
+          // Fallback for Bun.plugin (has no onStart)
+          await ensureIslands();
+          // Import with ? suffix to register file with bun --watch
+          // Issue: https://github.com/oven-sh/bun/issues/4689
+          const contents = await import(`${path}?`, { with: { type: "text" } });
+          return {
+            contents: await transform(contents.default, path, "ssr", dev, rootDir),
+            loader: "js",
+          };
+        });
+      },
+    };
+  };
+
+  return { config, plugin, html };
+};