@k2b/ssr 0.12.0 → 0.14.0

package/README.md

@@ -55,7 +55,7 @@ SPA routing.
 - Monorepo support via `rootDir`
 - Public path mounting via `basePath` for microfrontends
 - Stable file-path-based island IDs (collision-safe across workspace packages)
-- Production chunk cache busting (`/_ssr/*.js?v=<buildTimestamp>`)
+- Production module cache busting (`/_ssr/<buildTimestamp>/*.js`)
 - Linked development source maps and validator-aware asset delivery
 - Stale generated island assets removed after successful builds
 - Visibility-aware development reload with cross-tab SSE coordination
@@ -309,6 +309,7 @@ createConfig({
   dev?: boolean;         // default: false
   verbose?: boolean;     // default: !dev
   rootDir?: string;      // default: process.cwd()
+  componentRoots?: readonly string[]; // explicit island/client discovery directories
   basePath?: string;     // default: "", example: "/docs"
   external?: string[];   // passed to Bun.build for island bundle
   devSourcemap?: "none" | "linked" | "inline"; // default: "linked"
@@ -319,10 +320,23 @@ createConfig({
 ### Notes
 
 - `rootDir` is important in monorepos where server entrypoint and island files live in different packages.
+- `componentRoots` replaces the discovery scan with explicit directories. Relative paths resolve against `rootDir`; absolute paths support installed framework packages. Omit it to scan `rootDir`, or pass `[]` to scan nothing. Missing directories fail the build. Symlinks and overlapping roots are deduplicated by canonical path; nested `node_modules` and `.git` directories are skipped. Select an installed package directory explicitly to scan its components.
+- Solid core, web, and store imports use the app's dependency and the selected build mode consistently, including components imported from installed packages.
+- `rootDir` still controls component IDs and the development asset directory. All selected components share one browser build. Ordinary component libraries with browser/SSR exports (such as `@k2b/ui`) are resolved through imports and do not need discovery roots. Do not scan their examples or test fixtures.
+
+```ts
+createConfig({
+  rootDir: workspaceRoot,
+  componentRoots: ["packages/my-app/src", frameworkSourceDir],
+});
+```
+
+Use the same configuration in development and production. Files outside `rootDir` retain the existing canonical absolute-path ID fallback; moving an external package can change its IDs. SSR wrappers and browser assets must come from the same build.
 - `basePath` moves SSR assets and dev endpoints under that prefix, e.g. `/docs/_ssr`.
 - Development builds emit linked source maps by default. Use `"inline"` only when a tool requires embedded maps, or `"none"` to disable them.
-- In production, hydration imports include a build timestamp query (`?v=...`) for cache busting.
-- All adapters stream island assets from `Bun.file`. Production assets and content-hashed development chunks are immutable; stable development entries and source maps use validators for inexpensive freshness checks.
+- In production, all modules share a build timestamp directory (`/_ssr/<version>/<id>.js`). Relative lazy imports inherit that directory, so each module has one URL. Files stay flat on disk; adapters serve only the current build version.
+- All adapters stream island assets from `Bun.file`. Production assets under the versioned path and content-hashed development chunks are immutable; stable development entries and source maps use validators for inexpensive freshness checks.
+- Production adapters serve adjacent `.br` or `.gz` files when accepted by the request, preserving the original MIME type and varying caches by `Accept-Encoding`. Generate these siblings in the application build; the adapter does not compress responses at runtime. Development always serves the original file to avoid stale compressed copies.
 
 ## Microfrontend mount example
 
@@ -347,6 +361,12 @@ With this setup, hydration chunks and dev endpoints are served from `/docs/_ssr/
 
 ## Build for production
 
+Set the environment before starting Bun so both the build configuration and bundled code use production mode:
+
+```bash
+NODE_ENV=production bun scripts/build.ts
+```
+
 ```ts
 // scripts/build.ts
 import { plugin } from "./config";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ssr",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",
@@ -37,7 +37,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "1.4.2",
     "elysia": "^1.4.29",
     "file-type": "^21.3.1",
     "hono": "^4.12.30",

package/src/adapter/bun.ts

@@ -5,6 +5,7 @@
 import type { SsrConfig } from "../index";
 import {
   createAssetResponse,
+  getAssetPrefix,
   createPingResponse,
   getSsrDir,
   createReloadResponse,
@@ -30,6 +31,7 @@ type Routes = Record<string, RouteHandler>;
 export const routes = (config: SsrConfig): Routes => {
   const { dev, ssrPath } = config;
   const ssrDir = getSsrDir(config);
+  const assetPath = ssrPath + getAssetPrefix(dev);
 
   const devRoutes: Routes = dev
     ? {
@@ -39,13 +41,13 @@ export const routes = (config: SsrConfig): Routes => {
     : {};
 
   const serveAsset: RouteHandler = (req) => {
-    const filename = new URL(req.url).pathname.split("/").pop()!;
+    const filename = new URL(req.url).pathname.slice(assetPath.length + 1);
     return createAssetResponse(req, ssrDir, filename, dev);
   };
 
   return {
     ...devRoutes,
-    [`${ssrPath}/*.js`]: serveAsset,
-    [`${ssrPath}/*.js.map`]: serveAsset,
+    [`${assetPath}/*.js`]: serveAsset,
+    [`${assetPath}/*.js.map`]: serveAsset,
   };
 };

package/src/adapter/elysia.ts

@@ -6,6 +6,7 @@ import { Elysia } from "elysia";
 import type { SsrConfig } from "../index";
 import {
   createAssetResponse,
+  getAssetPrefix,
   createPingResponse,
   getSsrDir,
   createReloadResponse,
@@ -27,13 +28,14 @@ import {
 export const routes = (config: SsrConfig) => {
   const { dev, ssrPath } = config;
   const ssrDir = getSsrDir(config);
+  const assetPath = ssrPath + getAssetPrefix(dev);
 
   return new Elysia({ name: "ssr" })
     .get(`${ssrPath}/_reload`, ({ request }) =>
       dev ? createReloadResponse(request.signal) : notFound(),
     )
     .get(`${ssrPath}/_ping`, () => (dev ? createPingResponse() : notFound()))
-    .get(`${ssrPath}/*`, ({ request, params }) =>
+    .get(`${assetPath}/*`, ({ request, params }) =>
       createAssetResponse(request, ssrDir, params["*"], dev),
     );
 };

package/src/adapter/hono.ts

@@ -6,7 +6,7 @@ import { Hono } from "hono";
 import { createFactory } from "hono/factory";
 import type { Context, Env, Handler, MiddlewareHandler, TypedResponse } from "hono";
 import type { SsrConfig, HtmlFn, RenderFn } from "../index";
-import { createAssetResponse, createPingResponse, getSsrDir, createReloadResponse } from "./utils";
+import { createAssetResponse, getAssetPrefix, createPingResponse, getSsrDir, createReloadResponse } from "./utils";
 
 // ============================================================================
 // Types
@@ -183,8 +183,9 @@ export const routes = (config: SsrConfig) => {
     return createAssetResponse(c.req.raw, ssrDir, filename, dev);
   };
 
-  app.get("/:filename{.+\\.js$}", serveAsset);
-  app.get("/:filename{.+\\.js\\.map$}", serveAsset);
+  const prefix = getAssetPrefix(dev);
+  app.get(`${prefix}/:filename{.+\\.js$}`, serveAsset);
+  app.get(`${prefix}/:filename{.+\\.js\\.map$}`, serveAsset);
 
   return app;
 };

package/src/adapter/utils.ts

@@ -3,6 +3,7 @@
  * SSE live reload, and security utilities.
  */
 import { dirname, join, resolve } from "path";
+import { statSync } from "fs";
 import type { SsrConfig } from "../index";
 
 /**
@@ -34,9 +35,36 @@ export const toSsrPath = (basePath: string): string =>
 export const getSsrDir = (config: SsrConfig): string =>
   join(config.dev ? config.rootDir ?? process.cwd() : dirname(Bun.main), "_ssr");
 
+// Keep one version for this server process, including when Bun.main has no mtime.
+const buildVersion = (() => {
+  try {
+    return String(Math.floor(statSync(Bun.main).mtimeMs));
+  } catch {
+    return String(Date.now());
+  }
+})();
+
+/** Relative imports inherit a versioned directory, unlike a query string. */
+export const getAssetPrefix = (dev: boolean): string => dev ? "" : `/${buildVersion}`;
+
 const HASHED_CHUNK = /^chunk-[a-z0-9]+\.js$/i;
 const ASSET_FILE = /^[a-z0-9._-]+\.js(?:\.map)?$/i;
 
+const acceptedEncodings = (header: string | null): Array<"br" | "gzip" | "identity"> => {
+  const qualities = new Map<string, number>();
+  for (const part of header?.split(",") ?? []) {
+    const [name, ...parameters] = part.trim().toLowerCase().split(";");
+    if (!name) continue;
+    const q = parameters.map((parameter) => parameter.trim()).find((parameter) => parameter.startsWith("q="));
+    const quality = q === undefined ? 1 : Number(q.slice(2));
+    qualities.set(name, Number.isFinite(quality) && quality >= 0 && quality <= 1 ? quality : 0);
+  }
+  const quality = (encoding: string) => qualities.get(encoding) ??
+    (encoding === "identity" ? (qualities.get("*") === 0 ? 0 : 1) : qualities.get("*") ?? 0);
+  return (["br", "gzip", "identity"] as const).filter((encoding) => quality(encoding) > 0)
+    .sort((left, right) => quality(right) - quality(left));
+};
+
 /**
  * Stable entry names can change during development. Content-hashed chunks
  * cannot, so the browser may retain them across page navigations.
@@ -85,9 +113,19 @@ export const createAssetResponse = async (
 
   const cacheControl = getCacheHeaders(dev, filename);
   if (!dev) {
-    return new Response(file, {
-      headers: { "Content-Type": contentType, "Cache-Control": cacheControl },
-    });
+    for (const encoding of acceptedEncodings(request.headers.get("Accept-Encoding"))) {
+      const selected = encoding === "identity" ? file : Bun.file(`${path}${encoding === "br" ? ".br" : ".gz"}`);
+      if (!(await selected.exists())) continue;
+      const headers = new Headers({
+        "Content-Type": contentType,
+        "Content-Length": String(selected.size),
+        "Cache-Control": cacheControl,
+        Vary: "Accept-Encoding",
+      });
+      if (encoding !== "identity") headers.set("Content-Encoding", encoding);
+      return new Response(request.method === "HEAD" ? null : selected, { headers });
+    }
+    return new Response(null, { status: 406, headers: { Vary: "Accept-Encoding" } });
   }
 
   const lastModified = file.lastModified;
@@ -102,7 +140,7 @@ export const createAssetResponse = async (
     return new Response(null, { status: 304, headers: validatorHeaders });
   }
 
-  return new Response(file, {
+  return new Response(request.method === "HEAD" ? null : file, {
     headers: { "Content-Type": contentType, ...validatorHeaders },
   });
 };

package/src/build.ts

@@ -2,11 +2,12 @@
  * 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 { join, relative, resolve } from "path";
 import { Glob } from "bun";
-import { unlink } from "fs/promises";
+import { readdir, stat, unlink } from "fs/promises";
+import { existsSync } from "fs";
 import { transform } from "./transform";
-import { ISLAND_ID_LENGTH, islandIdFromFile, toStableKey } from "./island-id";
+import { ISLAND_ID_LENGTH, canonicalFilePath, islandIdFromFile, toStableKey } from "./island-id";
 
 type ComponentType = "island" | "client";
 
@@ -89,34 +90,48 @@ export const buildIslands = async (options: {
   pattern: string;
   outdir: string;
   cwd: string;
+  componentRoots?: readonly string[];
   verbose: boolean;
   dev?: boolean;
   devSourcemap?: DevSourcemap;
   external?: string[];
 }): Promise<void> => {
-  const { pattern, outdir, cwd, verbose, dev = false, devSourcemap = "linked", external } = options;
+  const { pattern, outdir, cwd, componentRoots, verbose, dev = false, devSourcemap = "linked", external } = options;
   const resolvedCwd = resolve(cwd);
 
   const totalStart = performance.now();
 
-  const files: string[] = [];
+  const files = new Set<string>();
 
   const scanStart = performance.now();
-  for await (const file of new Glob(pattern).scan({
-    cwd: resolvedCwd,
-    absolute: true,
-  })) {
-    files.push(file);
+  const visited = new Set<string>();
+  const matcher = new Glob(pattern);
+  const scan = async (directory: string, scanRoot: string): Promise<void> => {
+    const canonical = canonicalFilePath(directory);
+    if (visited.has(canonical)) return;
+    visited.add(canonical);
+    for (const entry of await readdir(canonical, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const path = join(canonical, entry.name);
+      const info = entry.isSymbolicLink() ? await stat(path) : entry;
+      if (info.isDirectory()) await scan(path, scanRoot);
+      else if (info.isFile() && matcher.match(relative(scanRoot, path))) files.add(canonicalFilePath(path));
+    }
+  };
+  for (const root of componentRoots ?? [resolvedCwd]) {
+    const scanRoot = canonicalFilePath(resolve(resolvedCwd, root));
+    await scan(scanRoot, scanRoot);
   }
-  if (verbose) console.log(`Scan: found ${files.length} file(s) in ${fmt(performance.now() - scanStart)}`);
+  if (verbose) console.log(`Scan: found ${files.size} file(s) in ${fmt(performance.now() - scanStart)}`);
 
-  if (!files.length) {
+  if (!files.size) {
+    if (existsSync(outdir)) await removeStaleBuildAssets(outdir, []);
     if (verbose) console.log("No island/client files found.");
     return;
   }
 
   // Build component metadata
-  const components = files.map((componentPath) => {
+  const components = [...files].map((componentPath) => {
     const id = islandIdFromFile(componentPath, resolvedCwd);
     const key = toStableKey(componentPath, resolvedCwd);
     const type = getComponentType(componentPath);
@@ -153,6 +168,7 @@ export const buildIslands = async (options: {
     outdir,
     naming: { entry: "[name].js", chunk: "chunk-[hash].js" },
     target: "browser",
+    conditions: ["browser", dev ? "development" : "production"],
     external,
     minify: !dev,
     splitting: true,
@@ -161,6 +177,15 @@ export const buildIslands = async (options: {
       {
         name: "solid-islands",
         setup(build) {
+          // Core, DOM and store must use the app's Solid copy and the same mode.
+          // Explicit exported entries avoid mixing a production core with
+          // development store/web modules from the host process conditions.
+          build.onResolve({ filter: /^solid-js(?:\/(?:web|store))?$/ }, (args) => {
+            const module = args.path === "solid-js" ? "solid" : args.path.slice("solid-js/".length);
+            const entry = `${args.path}/dist/${dev ? "dev" : module}.js`;
+            return { path: Bun.resolveSync(entry, resolvedCwd) };
+          });
+
           // Resolve component IDs as virtual entrypoints
           build.onResolve({ filter: new RegExp(`^[a-f0-9]{${ISLAND_ID_LENGTH}}$`) }, (args) => ({
             path: args.path,
@@ -220,7 +245,7 @@ export const buildIslands = async (options: {
     }
   }
   console.log(
-    `Built ${files.length} component(s) to ${outdir}/ in ${fmt(performance.now() - totalStart)}${verbose ? " (total)" : ""}`,
+    `Built ${files.size} component(s) to ${outdir}/ in ${fmt(performance.now() - totalStart)}${verbose ? " (total)" : ""}`,
   );
 
   if (!result.success) {

package/src/index.ts

@@ -7,12 +7,11 @@
 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";
+import { getAssetPrefix, getReloadId, normalizeBasePath, toSsrPath } from "./adapter/utils";
 // @ts-ignore - Bun text import
 import devClientCode from "./adapter/client.js" with { type: "text" };
 
@@ -23,19 +22,6 @@ import devClientCode from "./adapter/client.js" with { type: "text" };
 /** 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
 // ============================================================================
@@ -47,6 +33,8 @@ export type SsrOptions<T extends object = object> = {
   verbose?: boolean;
   /** Project root for island discovery and dev _ssr assets (default: process.cwd()) */
   rootDir?: string;
+  /** Discovery roots relative to rootDir (absolute paths allowed). Replaces the default rootDir scan. */
+  componentRoots?: readonly 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) */
@@ -121,6 +109,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
     devSourcemap = "linked",
     template,
     rootDir: rootDirOption,
+    componentRoots,
     basePath: basePathOption,
   } = options;
   const rootDir = resolve(rootDirOption ?? process.cwd());
@@ -153,13 +142,11 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
     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 hydrationScript = `<script type="module">const p=${JSON.stringify(ssrPath + getAssetPrefix(dev))};document.querySelectorAll('solid-island,solid-client').forEach(e=>import(p+'/'+e.dataset.id+'.js'));</script>`;
   const devConfigScript = `<script>globalThis.__SSR_CONFIG=${JSON.stringify({ ssrPath, reloadId: getReloadId() })}</script>`;
 
   // HTML renderer
@@ -208,6 +195,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
             pattern: COMPONENT_PATTERN,
             outdir: islandsOutdir,
             cwd: rootDir,
+            componentRoots,
             verbose: verbose ?? !dev,
             dev,
             devSourcemap,