@k2b/ssr 0.13.1 → 0.15.0

package/README.md

@@ -55,10 +55,11 @@ 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
+- Default error boundary per island/client instance with a retry fallback
 
 ## Install
 
@@ -233,9 +234,9 @@ export default function Tabs() {
 
 `Link` renders a real `<a href>` during SSR. Enhanced clicks only run in the
 browser for same-origin, left-click navigation without modifier keys. Without
-`onNavigate`, `Link` calls `navigate()` directly and only updates browser
-history. With `onNavigate`, the island owns data loading and state updates, then
-calls `nav.push()`, `nav.replaceWith()`, or `nav.fallback()`.
+`onNavigate`, the anchor keeps native document navigation and ignores `replace`
+and `scroll`. With `onNavigate`, the island owns data loading and state updates,
+then calls `nav.push()`, `nav.replaceWith()`, or `nav.fallback()`.
 
 Use `listenPopState()` whenever `nav.push()` represents client state. Browser
 Back/Forward changes history but cannot infer how an island maps the URL back to
@@ -246,7 +247,7 @@ Navigation behavior:
 
 - reactive anchor props remain reactive after `Link` renders
 - same-document hash links retain native target scrolling unless `onNavigate`
-  or `scroll` explicitly takes ownership
+  explicitly takes ownership
 - relative URLs follow `document.baseURI`
 - cross-origin `navigate()` calls use full document navigation
 - replace navigation preserves existing `history.state` unless `state` is set
@@ -263,6 +264,72 @@ Available exports:
 Use `data-scroll-preserve="stable-key"` on scroll containers that should keep
 their scroll position across enhanced navigation.
 
+## Error handling in islands
+
+Every island and client component instance is mounted inside its own error
+boundary. No setup is needed. If a component throws while it mounts, while its
+props are deserialized, or later in a reactive update, only that instance is
+replaced with a fallback. Other instances and other islands keep working, also
+when they are updated by the same signal write.
+
+The default fallback is plain, unstyled markup:
+
+```html
+<div role="alert" data-ssr-error>
+  This part of the page could not be displayed. <button type="button">Try again</button>
+</div>
+```
+
+**Try again** remounts the component with fresh state from the same
+`data-props`. Style the fallback through `[data-ssr-error]`.
+
+Each caught error dispatches a bubbling, cancelable `ssr:island-error` event on
+the `<solid-island>` or `<solid-client>` element. Its `detail` contains
+`error`, the component `id`, and `reset()`. Unless a listener calls
+`preventDefault()`, the error is then passed to `reportError()`, so it appears in
+the console and in the window `error` event like an uncaught error. Call
+`preventDefault()` only when you report the error yourself; the fallback is
+still shown.
+
+```ts
+addEventListener("ssr:island-error", (event) => {
+  if (!(event instanceof CustomEvent)) return;
+  const { error, id } = event.detail;
+  myReporter.capture(error, { island: id });
+  event.preventDefault();
+});
+```
+
+To replace the default fallback, for example to localize it, set
+`errorFallback` to a module whose default export receives `{ error, reset }`:
+
+```tsx
+// src/IslandError.tsx
+import type { IslandErrorProps } from "@k2b/ssr";
+
+export default function IslandError(props: IslandErrorProps) {
+  return (
+    <p role="alert" class="island-error">
+      Dieser Bereich konnte nicht angezeigt werden.
+      <button type="button" onClick={props.reset}>Erneut versuchen</button>
+    </p>
+  );
+}
+```
+
+```ts
+createConfig({ errorFallback: "./src/IslandError.tsx" });
+```
+
+The option is optional and only changes presentation. If the custom fallback
+throws, the default fallback is shown and its error is reported too.
+
+Error boundaries inside your components are closer to the error and still take
+precedence. Errors thrown directly in event handlers or in async code outside a
+Solid computation stay ordinary uncaught browser errors. Errors in reactive
+updates no longer propagate to the code that wrote the signal; that code now
+sees the island fallback instead.
+
 ## Rendering API
 
 `html()` and Hono `ssr()` handlers expect a synchronous render function:
@@ -313,6 +380,7 @@ createConfig({
   basePath?: string;     // default: "", example: "/docs"
   external?: string[];   // passed to Bun.build for island bundle
   devSourcemap?: "none" | "linked" | "inline"; // default: "linked"
+  errorFallback?: string; // optional island error fallback module, relative to rootDir
   template?: ({ body, scripts, ...custom }) => string | Promise<string>;
 })
 ```
@@ -332,10 +400,12 @@ 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.
+- `errorFallback` replaces the presentation of the default island error boundary. Islands are protected without it; see [Error handling in islands](#error-handling-in-islands).
 - `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 +430,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.15.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

@@ -95,8 +95,9 @@ export const buildIslands = async (options: {
   dev?: boolean;
   devSourcemap?: DevSourcemap;
   external?: string[];
+  errorFallback?: string;
 }): Promise<void> => {
-  const { pattern, outdir, cwd, componentRoots, verbose, dev = false, devSourcemap = "linked", external } = options;
+  const { pattern, outdir, cwd, componentRoots, verbose, dev = false, devSourcemap = "linked", external, errorFallback } = options;
   const resolvedCwd = resolve(cwd);
 
   const totalStart = performance.now();
@@ -200,7 +201,7 @@ export const buildIslands = async (options: {
             }
 
             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)})`,
+              contents: `import{mount}from${JSON.stringify(join(import.meta.dir, "mount.ts"))};import C from${JSON.stringify(component.path)};${errorFallback ? `import F from${JSON.stringify(errorFallback)};` : ""}mount(C,${JSON.stringify(component.selector)}${errorFallback ? ",F" : ""})`,
               loader: "js",
             };
           });

package/src/index.ts

@@ -7,15 +7,16 @@
 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" };
 
+export type { IslandErrorProps } from "./mount";
+
 // ============================================================================
 // Constants
 // ============================================================================
@@ -23,19 +24,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
 // ============================================================================
@@ -55,6 +43,8 @@ export type SsrOptions<T extends object = object> = {
   external?: string[];
   /** Development island sourcemaps (default: "linked") */
   devSourcemap?: DevSourcemap;
+  /** Path relative to rootDir (or absolute) to a default-exported Solid component receiving IslandErrorProps. */
+  errorFallback?: string;
   /** HTML template function (optional, has default) */
   template?: (
     ctx: {
@@ -121,6 +111,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
     verbose,
     external,
     devSourcemap = "linked",
+    errorFallback,
     template,
     rootDir: rootDirOption,
     componentRoots,
@@ -156,13 +147,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
@@ -216,6 +205,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
             dev,
             devSourcemap,
             external,
+            errorFallback: errorFallback ? resolve(rootDir, errorFallback) : undefined,
           });
         };
 

package/src/mount.ts

@@ -0,0 +1,68 @@
+import type { Component } from "solid-js";
+import { createComponent, ErrorBoundary, render } from "solid-js/web";
+import { deserialize } from "seroval";
+
+/** Props received by a configured island error fallback component. */
+export type IslandErrorProps = {
+  error: unknown;
+  reset: () => void;
+};
+
+const defaultFallback = (reset: () => void): HTMLDivElement => {
+  const alert = document.createElement("div");
+  alert.setAttribute("role", "alert");
+  alert.setAttribute("data-ssr-error", "");
+  alert.append("This part of the page could not be displayed. ");
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = "Try again";
+  button.addEventListener("click", reset);
+  alert.append(button);
+  return alert;
+};
+
+const report = (element: HTMLElement, error: unknown, reset: () => void): void => {
+  const event = new CustomEvent("ssr:island-error", {
+    bubbles: true,
+    cancelable: true,
+    detail: { error, id: element.dataset.id, reset },
+  });
+  if (element.dispatchEvent(event)) globalThis.reportError(error);
+};
+
+/** Mount each island/client instance in its own error boundary. */
+export const mount = <Props extends object>(
+  Component: Component<Props>,
+  selector: string,
+  Fallback?: Component<IslandErrorProps>,
+): void => {
+  document.querySelectorAll<HTMLElement>(selector).forEach((element) => {
+    const mountElement = (): void => {
+      try {
+        element.innerHTML = "";
+        render(() => createComponent(ErrorBoundary, {
+          fallback: (error: unknown, reset: () => void) => {
+            report(element, error, reset);
+            if (!Fallback) return defaultFallback(reset);
+            return createComponent(ErrorBoundary, {
+              fallback: (fallbackError: unknown) => {
+                globalThis.reportError(fallbackError);
+                return defaultFallback(reset);
+              },
+              get children() {
+                return createComponent(Fallback, { error, reset });
+              },
+            });
+          },
+          get children() {
+            return createComponent(Component, deserialize<Props>(element.dataset.props || "{}"));
+          },
+        }), element);
+      } catch (error) {
+        report(element, error, mountElement);
+        element.replaceChildren(defaultFallback(mountElement));
+      }
+    };
+    mountElement();
+  });
+};

package/src/nav.ts

@@ -50,9 +50,12 @@ export type LinkNavigateEvent = {
 
 export type LinkProps = Omit<AnchorProps, "href" | "onClick"> & {
   href: string;
+  /** Default history mode for enhanced clicks. Ignored without `onNavigate`. */
   replace?: boolean;
+  /** Default scroll mode for enhanced clicks. Ignored without `onNavigate`. */
   scroll?: NavigationScrollMode;
   onClick?: JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>;
+  /** Enables enhanced same-origin clicks. Without it, `Link` is a native anchor. */
   onNavigate?: (event: LinkNavigateEvent) => void | Promise<void>;
 };
 
@@ -200,11 +203,6 @@ const shouldEnhanceClick = (event: MouseEvent, anchor: HTMLAnchorElement): boole
   return url.origin === window.location.origin;
 };
 
-const isSameDocumentHash = (url: URL): boolean => {
-  const current = new URL(window.location.href);
-  return url.hash.length > 0 && url.pathname === current.pathname && url.search === current.search;
-};
-
 const callUserClick = (handler: LinkProps["onClick"], event: MouseEvent, anchor: HTMLAnchorElement): void => {
   if (!handler) return;
   const typedEvent = event as MouseEvent & { currentTarget: HTMLAnchorElement; target: Element };
@@ -227,30 +225,23 @@ export function Link(props: LinkProps) {
 
   const handleClick: JSX.EventHandler<HTMLAnchorElement, MouseEvent> = (event) => {
     callUserClick(local.onClick, event, event.currentTarget);
+    const onNavigate = local.onNavigate;
+    if (!onNavigate) return;
     if (!shouldEnhanceClick(event, event.currentTarget)) return;
 
     const href = local.href;
     const url = new URL(event.currentTarget.href);
 
-    // Preserve native target scrolling unless the application explicitly owns
-    // this hash navigation through onNavigate or a scroll option.
-    if (!local.onNavigate && local.scroll === undefined && isSameDocumentHash(url)) return;
-
     const scroll = local.scroll ?? "top";
     const replace = Boolean(local.replace);
     const scrollSnapshot = captureScroll();
 
     event.preventDefault();
 
-    if (!local.onNavigate) {
-      navigate(url.href, { replace, scroll, scrollSnapshot });
-      return;
-    }
-
     let navigationOutcome: "none" | "history" | "document" = "none";
     const runNavigation = async () => {
       try {
-        await local.onNavigate!({
+        await onNavigate({
           event,
           href,
           url,