@k2b/ssr 0.13.1 → 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
@@ -334,8 +334,9 @@ createConfig({
 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
 
@@ -360,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.13.1",
+  "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/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
 // ============================================================================
@@ -156,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