@k2b/ssr 0.14.0 → 0.15.0

package/README.md

@@ -59,6 +59,7 @@ SPA routing.
 - 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,6 +400,7 @@ 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, 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/ssr",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",

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

@@ -15,6 +15,8 @@ import { getAssetPrefix, getReloadId, normalizeBasePath, toSsrPath } from "./ada
 // @ts-ignore - Bun text import
 import devClientCode from "./adapter/client.js" with { type: "text" };
 
+export type { IslandErrorProps } from "./mount";
+
 // ============================================================================
 // Constants
 // ============================================================================
@@ -41,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: {
@@ -107,6 +111,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
     verbose,
     external,
     devSourcemap = "linked",
+    errorFallback,
     template,
     rootDir: rootDirOption,
     componentRoots,
@@ -200,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,