hadars 0.3.1 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 A minimal server-side rendering framework for React built on [rspack](https://rspack.dev). Runs on Bun, Node.js, and Deno.
 
+**[hadars.xyz](https://hadars.xyz)** — docs & website
+
 ## Why hadars?
 
 hadars is an alternative to Next.js for apps that just need SSR.
@@ -19,30 +21,30 @@ Bring your own router (or none), keep your components as plain React, and get SS
 ## Benchmarks
 
 <!-- BENCHMARK_START -->
-> Last run: 2026-03-25 · 120s · 100 connections · Bun runtime
-> hadars is **8.9x faster** in requests/sec
+> Last run: 2026-04-02 · 120s · 100 connections · Bun runtime
+> hadars is **9.3x faster** in requests/sec
 
 **Throughput** (autocannon, 120s)
 
 | Metric | hadars | Next.js |
 |---|---:|---:|
-| Requests/sec | **151** | 17 |
-| Latency median | **642 ms** | 2747 ms |
-| Latency p99 | **959 ms** | 4019 ms |
-| Throughput | **43.05** MB/s | 9.5 MB/s |
-| Peak RSS | 950.3 MB | **478.5 MB** |
-| Avg RSS | 763.3 MB | **426.4 MB** |
-| Build time | 0.7 s | 6.0 s |
+| Requests/sec | **158** | 17 |
+| Latency median | **634 ms** | 2754 ms |
+| Latency p99 | **1031 ms** | 4140 ms |
+| Throughput | **44.97** MB/s | 9.67 MB/s |
+| Peak RSS | 1001.1 MB | **477.2 MB** |
+| Avg RSS | 778.8 MB | **426.8 MB** |
+| Build time | 0.6 s | 6.0 s |
 
 **Page load** (Playwright · Chromium headless · median)
 
 | Metric | hadars | Next.js |
 |---|---:|---:|
-| TTFB | **19 ms** | 42 ms |
-| FCP | **96 ms** | 136 ms |
-| DOMContentLoaded | **39 ms** | 127 ms |
-| Load | **122 ms** | 173 ms |
-| Peak RSS | 476.8 MB | **289.5 MB** |
+| TTFB | **17 ms** | 45 ms |
+| FCP | **92 ms** | 140 ms |
+| DOMContentLoaded | **37 ms** | 127 ms |
+| Load | **118 ms** | 172 ms |
+| Peak RSS | 479.5 MB | **295.5 MB** |
 <!-- BENCHMARK_END -->
 
 ## Quick start
@@ -146,16 +148,28 @@ Fetch async data inside a component during SSR. The framework's render loop awai
 import { useServerData } from 'hadars';
 
 const UserCard = ({ userId }: { userId: string }) => {
-    const user = useServerData(['user', userId], () => db.getUser(userId));
+    const user = useServerData(() => db.getUser(userId));
     if (!user) return null; // undefined while pending on the first SSR pass
     return <p>{user.name}</p>;
 };
 ```
 
-- **`key`** - string or string array; must be stable and unique within the page
+The cache key is derived automatically from the call-site's position in the component tree via `useId()` — no manual key is needed.
+
 - **Server (SSR)** - calls `fn()`, awaits the result across render iterations, returns `undefined` until resolved
 - **Client (hydration)** - reads the pre-resolved value from the hydration cache serialised by the server; `fn()` is never called in the browser
-- **Client (navigation)** - when a component mounts during client-side navigation and its key is not in the cache, hadars fires a single `GET <current-url>` with `Accept: application/json`; all `useServerData` calls within the same render are batched into one request and suspended via React Suspense until the server returns the JSON data map
+- **Client (navigation)** - when a component mounts during client-side navigation and its data is not in the cache, hadars fires a single `GET <current-url>` with `Accept: application/json`; all `useServerData` calls within the same render are batched into one request and suspended via React Suspense until the server returns the JSON data map
+
+### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cache` | `boolean` | `true` | When `false`, the cached value is evicted when the component unmounts so the next mount fetches fresh data from the server. Safe with React Strict Mode. |
+
+```tsx
+// Uptime changes every request — evict on unmount so re-mounting always fetches fresh
+const uptime = useServerData(() => process.uptime(), { cache: false });
+```
 
 ## Data lifecycle hooks
 
@@ -190,6 +204,7 @@ const UserCard = ({ userId }: { userId: string }) => {
 | `paths` | `function` | - | Returns URL list to pre-render with `hadars export static`; receives `HadarsStaticContext` |
 | `sources` | `array` | - | Gatsby-compatible source plugins; hadars infers a GraphQL schema from their nodes |
 | `graphql` | `function` | - | Custom GraphQL executor passed to `paths()` and `getInitProps()` as `ctx.graphql` |
+| `onError` | `function` | - | Called on every SSR render error; use to forward to Sentry, Datadog, etc. |
 
 ### moduleRules example
 
@@ -225,6 +240,24 @@ const config: HadarsOptions = {
 export default config;
 ```
 
+### Error monitoring example
+
+```ts
+import * as Sentry from '@sentry/node';
+import type { HadarsOptions } from 'hadars';
+
+const config: HadarsOptions = {
+    entry: 'src/App.tsx',
+    onError: (err, req) => Sentry.captureException(err, {
+        extra: { url: req.url, method: req.method },
+    }),
+};
+
+export default config;
+```
+
+`onError` is called on every SSR render error in `dev()`, `run()`, Lambda, and Cloudflare adapters. The handler may be async — hadars fires it without awaiting so it never delays the error response to the browser.
+
 ## Static Export
 
 > **Experimental.** Static export and Gatsby-compatible source plugins are new features. The API — including config shape, context object, and schema inference behaviour — may change in future releases without a major version bump.

package/dist/{chunk-2KJRDPCN.js → chunk-2J2L2H3H.js}

@@ -1,7 +1,7 @@
 import {
   renderPreflight,
   renderToString
-} from "./chunk-LY5MTHFV.js";
+} from "./chunk-TV37IMRB.js";
 import {
   createElement
 } from "./chunk-OS3V4CPN.js";
@@ -230,18 +230,18 @@ var makePrecontentHtmlGetter = (htmlFilePromise) => {
   let preHead = null;
   let postHead = null;
   let postContent = null;
+  const primed = htmlFilePromise.then((html) => {
+    const headEnd = html.indexOf(HEAD_MARKER);
+    const contentStart = html.indexOf(BODY_MARKER);
+    preHead = html.slice(0, headEnd);
+    postHead = html.slice(headEnd + HEAD_MARKER.length, contentStart);
+    postContent = html.slice(contentStart + BODY_MARKER.length);
+  });
   return (headHtml) => {
     if (preHead !== null) {
       return [preHead + headHtml + postHead, postContent];
     }
-    return htmlFilePromise.then((html) => {
-      const headEnd = html.indexOf(HEAD_MARKER);
-      const contentStart = html.indexOf(BODY_MARKER);
-      preHead = html.slice(0, headEnd);
-      postHead = html.slice(headEnd + HEAD_MARKER.length, contentStart);
-      postContent = html.slice(contentStart + BODY_MARKER.length);
-      return [preHead + headHtml + postHead, postContent];
-    });
+    return primed.then(() => [preHead + headHtml + postHead, postContent]);
   };
 };
 async function transformStream(data, stream) {

package/dist/{chunk-LY5MTHFV.js → chunk-TV37IMRB.js}

@@ -115,7 +115,16 @@ function componentCalledUseId() {
 function snapshotContext() {
   const st = s();
   const ctx = st.currentTreeContext;
-  return { tree: { id: ctx.id, overflow: ctx.overflow }, localId: st.localIdCounter, treeDepth: _treeDepth };
+  const depth = _treeDepth;
+  return {
+    tree: { id: ctx.id, overflow: ctx.overflow },
+    localId: st.localIdCounter,
+    treeDepth: depth,
+    // Snapshot the live stack so that popTreeContext reads correct saved values
+    // even if another concurrent render's resetRenderState stomped the arrays.
+    idStack: _treeIdStack.slice(0, depth),
+    ovStack: _treeOvStack.slice(0, depth)
+  };
 }
 function restoreContext(snap) {
   const st = s();
@@ -124,6 +133,10 @@ function restoreContext(snap) {
   ctx.overflow = snap.tree.overflow;
   st.localIdCounter = snap.localId;
   _treeDepth = snap.treeDepth;
+  for (let i = 0; i < snap.treeDepth; i++) {
+    _treeIdStack[i] = snap.idStack[i];
+    _treeOvStack[i] = snap.ovStack[i];
+  }
 }
 function getTreeId() {
   const { id, overflow } = s().currentTreeContext;
@@ -269,6 +282,14 @@ function restoreDispatcher(prev) {
 }
 
 // src/slim-react/render.ts
+function captureRenderCtx() {
+  return { m: captureMap(), u: captureUnsuspend(), t: snapshotContext() };
+}
+function restoreRenderCtx(ctx) {
+  swapContextMap(ctx.m);
+  restoreUnsuspend(ctx.u);
+  restoreContext(ctx.t);
+}
 var VOID_ELEMENTS = /* @__PURE__ */ new Set([
   "area",
   "base",
@@ -712,11 +733,9 @@ function renderComponent(type, props, writer, isSvg, _suspenseRetries = 0) {
       if (e && typeof e.then === "function") {
         if (_suspenseRetries + 1 >= MAX_COMPONENT_SUSPENSE_RETRIES) throw SUSPENSE_RETRY_LIMIT;
         patchPromiseStatus(e);
-        const m = captureMap();
-        const u = captureUnsuspend();
+        const rctx = captureRenderCtx();
         return e.then(() => {
-          swapContextMap(m);
-          restoreUnsuspend(u);
+          restoreRenderCtx(rctx);
           return renderComponent(type, props, writer, isSvg, _suspenseRetries + 1);
         });
       }
@@ -753,17 +772,14 @@ function renderComponent(type, props, writer, isSvg, _suspenseRetries = 0) {
     };
     const r2 = renderChildren(props.children, writer, isSvg);
     if (r2 && typeof r2.then === "function") {
-      const m = captureMap();
-      const u = captureUnsuspend();
+      const rctx = captureRenderCtx();
       return r2.then(
         () => {
-          swapContextMap(m);
-          restoreUnsuspend(u);
+          restoreRenderCtx(rctx);
           finish();
         },
         (e) => {
-          swapContextMap(m);
-          restoreUnsuspend(u);
+          restoreRenderCtx(rctx);
           finish();
           throw e;
         }
@@ -792,11 +808,9 @@ function renderComponent(type, props, writer, isSvg, _suspenseRetries = 0) {
     if (e && typeof e.then === "function") {
       if (_suspenseRetries + 1 >= MAX_COMPONENT_SUSPENSE_RETRIES) throw SUSPENSE_RETRY_LIMIT;
       patchPromiseStatus(e);
-      const m = captureMap();
-      const u = captureUnsuspend();
+      const rctx = captureRenderCtx();
       return e.then(() => {
-        swapContextMap(m);
-        restoreUnsuspend(u);
+        restoreRenderCtx(rctx);
         return renderComponent(type, props, writer, isSvg, _suspenseRetries + 1);
       });
     }
@@ -808,30 +822,25 @@ function renderComponent(type, props, writer, isSvg, _suspenseRetries = 0) {
     savedIdTree = pushTreeContext(1, 0);
   }
   if (result instanceof Promise) {
-    const m = captureMap();
-    const u = captureUnsuspend();
+    const rctx = captureRenderCtx();
     return result.then((resolved) => {
-      swapContextMap(m);
-      restoreUnsuspend(u);
+      restoreRenderCtx(rctx);
       let asyncSavedIdTree;
       if (componentCalledUseId()) {
         asyncSavedIdTree = pushTreeContext(1, 0);
       }
       const r2 = renderNode(resolved, writer, isSvg);
       if (r2 && typeof r2.then === "function") {
-        const m2 = captureMap();
-        const u2 = captureUnsuspend();
+        const rctx2 = captureRenderCtx();
         return r2.then(
           () => {
-            swapContextMap(m2);
-            restoreUnsuspend(u2);
+            restoreRenderCtx(rctx2);
             if (asyncSavedIdTree !== void 0) popTreeContext(asyncSavedIdTree);
             popComponentScope(savedScope);
             if (isProvider) popContextValue(ctx, prevCtxValue);
           },
           (e) => {
-            swapContextMap(m2);
-            restoreUnsuspend(u2);
+            restoreRenderCtx(rctx2);
             if (asyncSavedIdTree !== void 0) popTreeContext(asyncSavedIdTree);
             popComponentScope(savedScope);
             if (isProvider) popContextValue(ctx, prevCtxValue);
@@ -843,8 +852,7 @@ function renderComponent(type, props, writer, isSvg, _suspenseRetries = 0) {
       popComponentScope(savedScope);
       if (isProvider) popContextValue(ctx, prevCtxValue);
     }, (e) => {
-      swapContextMap(m);
-      restoreUnsuspend(u);
+      restoreRenderCtx(rctx);
       popComponentScope(savedScope);
       if (isProvider) popContextValue(ctx, prevCtxValue);
       throw e;
@@ -852,19 +860,16 @@ function renderComponent(type, props, writer, isSvg, _suspenseRetries = 0) {
   }
   const r = renderNode(result, writer, isSvg);
   if (r && typeof r.then === "function") {
-    const m = captureMap();
-    const u = captureUnsuspend();
+    const rctx = captureRenderCtx();
     return r.then(
       () => {
-        swapContextMap(m);
-        restoreUnsuspend(u);
+        restoreRenderCtx(rctx);
         if (savedIdTree !== void 0) popTreeContext(savedIdTree);
         popComponentScope(savedScope);
         if (isProvider) popContextValue(ctx, prevCtxValue);
       },
       (e) => {
-        swapContextMap(m);
-        restoreUnsuspend(u);
+        restoreRenderCtx(rctx);
         if (savedIdTree !== void 0) popTreeContext(savedIdTree);
         popComponentScope(savedScope);
         if (isProvider) popContextValue(ctx, prevCtxValue);
@@ -889,11 +894,9 @@ function renderChildArrayFrom(children, startIndex, writer, isSvg) {
     const savedTree = pushTreeContext(totalChildren, i);
     const r = renderNode(child, writer, isSvg);
     if (r && typeof r.then === "function") {
-      const m = captureMap();
-      const u = captureUnsuspend();
+      const rctx = captureRenderCtx();
       return r.then(() => {
-        swapContextMap(m);
-        restoreUnsuspend(u);
+        restoreRenderCtx(rctx);
         popTreeContext(savedTree);
         return renderChildArrayFrom(children, i + 1, writer, isSvg);
       });
@@ -917,11 +920,9 @@ async function renderSuspense(props, writer, isSvg = false) {
   try {
     const r = renderNode(children, buffer, isSvg);
     if (r && typeof r.then === "function") {
-      const m = captureMap();
-      const u = captureUnsuspend();
+      const rctx = captureRenderCtx();
       await r;
-      swapContextMap(m);
-      restoreUnsuspend(u);
+      restoreRenderCtx(rctx);
     }
     writer.write("<!--$-->");
     buffer.flushTo(writer);
@@ -935,11 +936,9 @@ async function renderSuspense(props, writer, isSvg = false) {
       if (fallback) {
         const r = renderNode(fallback, writer, isSvg);
         if (r && typeof r.then === "function") {
-          const m = captureMap();
-          const u = captureUnsuspend();
+          const rctx = captureRenderCtx();
           await r;
-          swapContextMap(m);
-          restoreUnsuspend(u);
+          restoreRenderCtx(rctx);
         }
       }
       writer.write("<!--/$-->");
@@ -976,9 +975,9 @@ function renderToStream(element, options) {
       try {
         const r = renderNode(element, writer);
         if (r && typeof r.then === "function") {
-          const m = captureMap();
+          const rctx = captureRenderCtx();
           await r;
-          swapContextMap(m);
+          restoreRenderCtx(rctx);
         }
         writer.flush();
         controller.close();
@@ -1005,9 +1004,9 @@ async function renderPreflight(element, options) {
     NULL_WRITER.lastWasText = false;
     const r = renderNode(element, NULL_WRITER);
     if (r && typeof r.then === "function") {
-      const m = captureMap();
+      const rctx = captureRenderCtx();
       await r;
-      swapContextMap(m);
+      restoreRenderCtx(rctx);
     }
   } finally {
     swapContextMap(prev);
@@ -1032,9 +1031,9 @@ async function renderToString(element, options) {
     resetRenderState(idPrefix);
     const r = renderNode(element, writer);
     if (r && typeof r.then === "function") {
-      const m = captureMap();
+      const rctx = captureRenderCtx();
       await r;
-      swapContextMap(m);
+      restoreRenderCtx(rctx);
     }
     return output;
   } finally {