hadars 0.1.17 → 0.1.18

package/dist/ssr-watch.js

@@ -171,25 +171,21 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
   const isServerBuild = Boolean(
     opts.output && typeof opts.output === "object" && (opts.output.library || String(opts.output.filename || "").includes("ssr"))
   );
+  const slimReactIndex = pathMod.resolve(packageDir, "slim-react", "index.js");
+  const slimReactJsx = pathMod.resolve(packageDir, "slim-react", "jsx-runtime.js");
   const resolveAliases = isServerBuild ? {
-    // force all react imports to resolve to this project's react
-    react: path.resolve(process.cwd(), "node_modules", "react"),
-    "react-dom": path.resolve(process.cwd(), "node_modules", "react-dom"),
-    // also map react/jsx-runtime to avoid duplicates when automatic runtime is used
-    "react/jsx-runtime": path.resolve(process.cwd(), "node_modules", "react", "jsx-runtime.js"),
-    "react/jsx-dev-runtime": path.resolve(process.cwd(), "node_modules", "react", "jsx-dev-runtime.js"),
-    // ensure emotion packages resolve to the project's node_modules so we don't pick up a browser-specific entry
+    // Route all React imports to slim-react for SSR.
+    react: slimReactIndex,
+    "react/jsx-runtime": slimReactJsx,
+    "react/jsx-dev-runtime": slimReactJsx,
+    // Keep emotion on the project's node_modules (server-safe entry).
     "@emotion/react": path.resolve(process.cwd(), "node_modules", "@emotion", "react"),
     "@emotion/server": path.resolve(process.cwd(), "node_modules", "@emotion", "server"),
     "@emotion/cache": path.resolve(process.cwd(), "node_modules", "@emotion", "cache"),
     "@emotion/styled": path.resolve(process.cwd(), "node_modules", "@emotion", "styled")
   } : void 0;
   const externals = isServerBuild ? [
-    "react",
-    "react-dom",
-    // keep common aliases external as well
-    "react/jsx-runtime",
-    "react/jsx-dev-runtime",
+    // react / react-dom are replaced by slim-react via alias above — not external.
     // emotion should be external on server builds to avoid client/browser code
     "@emotion/react",
     "@emotion/server",
@@ -244,8 +240,33 @@ var buildCompilerConfig = (entry2, opts, includeHotPlugin) => {
         template: opts.htmlTemplate ? pathMod.resolve(process.cwd(), opts.htmlTemplate) : clientScriptPath,
         scriptLoading: "module",
         filename: "out.html",
-        inject: "body"
+        inject: "head",
+        minify: opts.mode === "production"
       }),
+      // Add `async` to the emitted module script so DOMContentLoaded fires
+      // as soon as HTML is parsed — without waiting for the bundle to execute.
+      // `<script type="module" async>` is valid: it downloads in parallel and
+      // executes without blocking DOMContentLoaded, while retaining module
+      // semantics (strict mode, ES imports, etc.).
+      {
+        apply(compiler) {
+          compiler.hooks.emit.tapAsync("HadarsAsyncModuleScript", (compilation, cb) => {
+            const asset = compilation.assets["out.html"];
+            if (asset) {
+              const html = asset.source();
+              const updated = html.replace(
+                /(<script\b[^>]*\btype="module"[^>]*)(>)/g,
+                (match, before, end) => before.includes("async") ? match : `${before} async${end}`
+              );
+              compilation.assets["out.html"] = {
+                source: () => updated,
+                size: () => Buffer.byteLength(updated)
+              };
+            }
+            cb();
+          });
+        }
+      },
       isDev && new ReactRefreshPlugin(),
       includeHotPlugin && isDev && new rspack.HotModuleReplacementPlugin(),
       ...extraPlugins

package/dist/utils/Head.tsx

@@ -273,8 +273,7 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
                     () => { unsuspend.cache.set(cacheKey, { status: 'suspense-resolved' }); },
                 );
                 unsuspend.cache.set(cacheKey, { status: 'pending', promise: suspensePromise });
-                unsuspend.hasPending = true;
-                return undefined;
+                throw suspensePromise; // slim-react will await and retry
             }
             throw thrown;
         }
@@ -294,12 +293,10 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
             reason => { unsuspend.cache.set(cacheKey, { status: 'rejected', reason }); },
         );
         unsuspend.cache.set(cacheKey, { status: 'pending', promise });
-        unsuspend.hasPending = true;
-        return undefined;
+        throw promise; // slim-react will await and retry
     }
     if (existing.status === 'pending') {
-        unsuspend.hasPending = true;
-        return undefined;
+        throw existing.promise; // slim-react will await and retry
     }
     if (existing.status === 'rejected') throw existing.reason;
     return existing.value as T;

package/index.ts

@@ -12,4 +12,4 @@ export type {
     HadarsEntryModule,
     HadarsApp,
 } from "./src/types/hadars";
-export { HadarsHead, HadarsContext, loadModule } from "./src/index";
+export { HadarsHead, HadarsContext, loadModule, CacheSegment, deleteSegment, clearSegments } from "./src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",
@@ -29,7 +29,7 @@
     }
   },
   "scripts": {
-    "build:lib": "tsup src/index.tsx --format esm,cjs --dts --out-dir dist --clean --external '@rspack/*' --external '@rspack/binding'",
+    "build:lib": "tsup src/index.tsx src/slim-react/index.ts src/slim-react/jsx-runtime.ts --format esm,cjs --dts --out-dir dist --clean --external '@rspack/*' --external '@rspack/binding'",
     "build:cli": "node build-scripts/build-cli.mjs",
     "build:all": "npm run build:lib && npm run build:cli",
     "test": "bun test test/ssr.test.ts",

package/src/build.ts

@@ -9,7 +9,6 @@ import { isBun, isDeno, isNode } from "./utils/runtime";
 import { RspackDevServer } from "@rspack/dev-server";
 import pathMod from "node:path";
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { createRequire } from 'node:module';
 import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import { existsSync } from 'node:fs';
@@ -17,6 +16,7 @@ import os from 'node:os';
 import { spawn } from 'node:child_process';
 import cluster from 'node:cluster';
 import type { HadarsEntryModule, HadarsOptions, HadarsProps } from "./types/hadars";
+import { processSegmentCache } from "./utils/segmentCache";
 const encoder = new TextEncoder();
 
 /**
@@ -73,17 +73,7 @@ async function processHtmlTemplate(templatePath: string): Promise<string> {
 const HEAD_MARKER = '<meta name="HADARS_HEAD">';
 const BODY_MARKER = '<meta name="HADARS_BODY">';
 
-// Resolve renderToString from react-dom/server in the project's node_modules.
-let _renderToString: ((element: any) => string) | null = null;
-async function getRenderToString(): Promise<(element: any) => string> {
-    if (!_renderToString) {
-        const req = createRequire(pathMod.resolve(process.cwd(), '__hadars_fake__.js'));
-        const resolved = req.resolve('react-dom/server');
-        const mod = await import(pathToFileURL(resolved).href);
-        _renderToString = mod.renderToString;
-    }
-    return _renderToString!;
-}
+import { renderToString as slimRenderToString } from './slim-react/index';
 
 // Round-robin thread pool for SSR rendering — used on Bun/Deno where
 // node:cluster is not available but node:worker_threads is.
@@ -210,26 +200,21 @@ async function buildSsrResponse(
     getPrecontentHtml: (headHtml: string) => Promise<[string, string]>,
     unsuspendForRender: any,
 ): Promise<Response> {
-    // Pre-load renderer before starting the stream so the set→call→clear
-    // sequence around __hadarsUnsuspend is fully synchronous (no await between them).
-    const renderToString = await getRenderToString();
-
     const responseStream = new ReadableStream({
         async start(controller) {
             const [precontentHtml, postContent] = await getPrecontentHtml(headHtml);
             // Flush the shell (precontentHtml) immediately so the browser can
             // start loading CSS/fonts before renderToString blocks the thread.
             controller.enqueue(encoder.encode(precontentHtml));
-            await Promise.resolve(); // yield to let the runtime flush the shell chunk
 
-            // set → call (synchronous) → clear: no await in between, safe under concurrency
             let bodyHtml: string;
             try {
                 (globalThis as any).__hadarsUnsuspend = unsuspendForRender;
-                bodyHtml = renderToString(ReactPage);
+                bodyHtml = await slimRenderToString(ReactPage);
             } finally {
                 (globalThis as any).__hadarsUnsuspend = null;
             }
+            bodyHtml = processSegmentCache(bodyHtml);
             controller.enqueue(encoder.encode(bodyHtml + postContent));
             controller.close();
         },
@@ -697,7 +682,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                 getFinalProps,
             } = (await import(importPath)) as HadarsEntryModule<any>;
 
-            const { ReactPage, status, headHtml, renderPayload } = await getReactResponse(request, {
+            const { ReactPage, unsuspend, status, headHtml } = await getReactResponse(request, {
                 document: {
                     body: Component as React.FC<HadarsProps<object>>,
                     lang: 'en',
@@ -707,7 +692,6 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                 },
             });
 
-            const unsuspend = (renderPayload.appProps.context as any)?._unsuspend ?? null;
             return buildSsrResponse(ReactPage, headHtml, status, getPrecontentHtml, unsuspend);
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);
@@ -885,7 +869,7 @@ export const run = async (options: HadarsRuntimeOptions) => {
                 });
             }
 
-            const { ReactPage, status, headHtml, renderPayload } = await getReactResponse(request, {
+            const { ReactPage, unsuspend, status, headHtml } = await getReactResponse(request, {
                 document: {
                     body: Component as React.FC<HadarsProps<object>>,
                     lang: 'en',
@@ -895,7 +879,6 @@ export const run = async (options: HadarsRuntimeOptions) => {
                 },
             });
 
-            const unsuspend = (renderPayload.appProps.context as any)?._unsuspend ?? null;
             return buildSsrResponse(ReactPage, headHtml, status, getPrecontentHtml, unsuspend);
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);

package/src/components/CacheSegment.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { getSegment, CACHE_TAG } from '../utils/segmentCache';
+
+interface CacheSegmentProps {
+    /**
+     * Unique cache key for this segment. Use a key that encodes all values
+     * the output depends on, e.g. `"product-" + product.id`.
+     */
+    cacheKey: string;
+    /**
+     * Time-to-live in milliseconds. Omit for entries that never expire.
+     */
+    ttl?: number;
+    children: React.ReactNode;
+}
+
+/**
+ * Caches the server-rendered HTML of its children across requests.
+ *
+ * **Server (SSR):**
+ * - Cache miss — children are rendered normally as part of the main
+ *   `renderToString` call, so React context propagates correctly. The output
+ *   is wrapped in a `<hadars-c>` marker that `processSegmentCache` uses to
+ *   extract and store the HTML. The marker is stripped before the response
+ *   is sent; the browser never sees it.
+ * - Cache hit — children are **not** rendered at all. The cached HTML is
+ *   injected directly, saving the entire subtree render cost.
+ *
+ * **Client:** renders children normally (no caching). Because the server
+ * strips the marker wrapper, the client output matches the server HTML and
+ * React hydration succeeds without warnings for deterministic components.
+ *
+ * **Note:** components that rely on request-specific data (cookies, auth,
+ * personalisation) must not be wrapped in `CacheSegment` unless the cache
+ * key encodes that data — otherwise a cached response for one user could be
+ * served to another.
+ */
+export function CacheSegment({ cacheKey, ttl, children }: CacheSegmentProps) {
+    // Client: render children normally — no server cache on the client.
+    if (typeof window !== 'undefined') {
+        return <>{children}</>;
+    }
+
+    const cached = getSegment(cacheKey);
+
+    if (cached !== null) {
+        // Cache hit: skip rendering children entirely.
+        // The <hadars-c> wrapper is stripped by processSegmentCache before
+        // the response is sent to the browser.
+        return React.createElement(CACHE_TAG as any, {
+            'data-key': cacheKey,
+            'data-cache': 'hit',
+            dangerouslySetInnerHTML: { __html: cached },
+        });
+    }
+
+    // Cache miss: render children as normal React elements so that React
+    // context (providers, etc.) propagates correctly into the subtree.
+    // processSegmentCache will extract the rendered HTML and store it.
+    const props: Record<string, unknown> = {
+        'data-key': cacheKey,
+        'data-cache': 'miss',
+    };
+    if (ttl != null) props['data-ttl'] = ttl;
+
+    return React.createElement(CACHE_TAG as any, props, children);
+}

package/src/index.tsx

@@ -10,6 +10,8 @@ export type {
     HadarsApp,
 } from "./types/hadars";
 export { Head as HadarsHead, useServerData, initServerDataCache } from './utils/Head';
+export { CacheSegment } from './components/CacheSegment';
+export { deleteSegment, clearSegments } from './utils/segmentCache';
 import { AppProviderSSR, AppProviderCSR } from "./utils/Head";
 
 export const HadarsContext = typeof window === 'undefined' ? AppProviderSSR : AppProviderCSR;

package/src/slim-react/context.ts

@@ -0,0 +1,52 @@
+import type { SlimNode } from "./types";
+
+/**
+ * Minimal Context implementation for SSR.
+ *
+ * Because SSR is single-pass and synchronous within each component,
+ * we just track the "current" value on the context object and
+ * save / restore around Provider renders (handled by the renderer).
+ */
+
+export interface Context<T> {
+  _currentValue: T;
+  Provider: ContextProvider<T>;
+  Consumer: (props: { children: (value: T) => SlimNode }) => SlimNode;
+}
+
+export type ContextProvider<T> = ((props: {
+  value: T;
+  children?: SlimNode;
+}) => SlimNode) & {
+  _context: Context<T>;
+};
+
+export function createContext<T>(defaultValue: T): Context<T> {
+  const context: Context<T> = {
+    _currentValue: defaultValue,
+    Provider: null!,
+    Consumer: null!,
+  };
+
+  // Provider is a function component recognised by the renderer.
+  // The `_context` tag tells the renderer to push / pop the value.
+  const Provider = function ContextProvider({
+    children,
+  }: {
+    value: T;
+    children?: SlimNode;
+  }): SlimNode {
+    return children ?? null;
+  } as unknown as ContextProvider<T>;
+
+  Provider._context = context;
+  context.Provider = Provider;
+
+  context.Consumer = ({ children }) => {
+    return (children as unknown as (value: T) => SlimNode)(
+      context._currentValue,
+    );
+  };
+
+  return context;
+}

package/src/slim-react/hooks.ts

@@ -0,0 +1,137 @@
+/**
+ * SSR hook implementations.
+ *
+ * On the server every hook is either a no-op or returns the initial /
+ * snapshot value.  This is enough for the vast majority of React-
+ * compatible libraries to work during server-side rendering.
+ */
+
+import { makeId } from "./renderContext";
+
+// ---- useState ----
+export function useState<T>(
+  initialState: T | (() => T),
+): [T, (value: T | ((prev: T) => T)) => void] {
+  const value =
+    typeof initialState === "function"
+      ? (initialState as () => T)()
+      : initialState;
+  return [value, () => {}];
+}
+
+// ---- useReducer ----
+export function useReducer<S, A>(
+  _reducer: (state: S, action: A) => S,
+  initialState: S,
+): [S, (action: A) => void] {
+  return [initialState, () => {}];
+}
+
+// ---- useEffect / useLayoutEffect / useInsertionEffect ----
+export function useEffect(
+  _effect: () => void | (() => void),
+  _deps?: any[],
+) {}
+export function useLayoutEffect(
+  _effect: () => void | (() => void),
+  _deps?: any[],
+) {}
+export function useInsertionEffect(
+  _effect: () => void | (() => void),
+  _deps?: any[],
+) {}
+
+// ---- useRef ----
+export function useRef<T>(initialValue: T): { current: T } {
+  return { current: initialValue };
+}
+
+// ---- useMemo / useCallback ----
+export function useMemo<T>(factory: () => T, _deps?: any[]): T {
+  return factory();
+}
+export function useCallback<T extends Function>(callback: T, _deps?: any[]): T {
+  return callback;
+}
+
+// ---- useId ----
+export function useId(): string {
+  return makeId();
+}
+
+// ---- useDebugValue ----
+export function useDebugValue(_value: any, _format?: (v: any) => any) {}
+
+// ---- useImperativeHandle ----
+export function useImperativeHandle(
+  _ref: any,
+  _createHandle: () => any,
+  _deps?: any[],
+) {}
+
+// ---- useSyncExternalStore ----
+export function useSyncExternalStore<T>(
+  _subscribe: (onStoreChange: () => void) => () => void,
+  getSnapshot: () => T,
+  getServerSnapshot?: () => T,
+): T {
+  return (getServerSnapshot || getSnapshot)();
+}
+
+// ---- useTransition ----
+export function useTransition(): [boolean, (callback: () => void) => void] {
+  return [false, (cb) => cb()];
+}
+
+// ---- useDeferredValue ----
+export function useDeferredValue<T>(value: T): T {
+  return value;
+}
+
+// ---- useOptimistic (React 19) ----
+export function useOptimistic<T>(passthrough: T): [T, () => void] {
+  return [passthrough, () => {}];
+}
+
+// ---- useFormStatus (React 19) ----
+export function useFormStatus() {
+  return { pending: false, data: null, method: null, action: null };
+}
+
+// ---- useActionState (React 19) ----
+export function useActionState<S>(
+  _action: (state: S, payload: any) => S | Promise<S>,
+  initialState: S,
+  _permalink?: string,
+): [S, (payload: any) => void, boolean] {
+  return [initialState, () => {}, false];
+}
+
+// ---- use (React 19 – Suspense integration) ----
+export function use<T>(
+  usable: (Promise<T> & { status?: string; value?: T; reason?: any }) | { _currentValue: T },
+): T {
+  // Context object
+  if (
+    typeof usable === "object" &&
+    usable !== null &&
+    "_currentValue" in usable
+  ) {
+    return (usable as { _currentValue: T })._currentValue;
+  }
+
+  // Promise – Suspense protocol
+  const promise = usable as Promise<T> & {
+    status?: string;
+    value?: T;
+    reason?: any;
+  };
+  if (promise.status === "fulfilled") return promise.value!;
+  if (promise.status === "rejected") throw promise.reason;
+  throw promise; // caught by the nearest Suspense boundary
+}
+
+// ---- startTransition ----
+export function startTransition(callback: () => void) {
+  callback();
+}