@valentinkolb/ssr 0.8.0 → 0.9.0

package/README.md

@@ -145,7 +145,7 @@ import Counter from "../components/Counter.island";
 
 export default ssr(async (c) => {
   c.get("page").title = "Home";
-  return <Counter initial={5} />;
+  return () => <Counter initial={5} />;
 });
 ```
 
@@ -174,6 +174,45 @@ NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
 - Hono: `@valentinkolb/ssr/hono`
 - Elysia: `@valentinkolb/ssr/elysia`
 
+## Rendering API
+
+`html()` and Hono `ssr()` handlers expect a synchronous render function:
+
+```tsx
+export default ssr(async (c) => {
+  const data = await loadData();
+  c.get("page").title = data.title;
+
+  return () => <Page data={data} />;
+});
+
+app.get("/", () => html(() => <Page />));
+```
+
+Do async work in the handler before returning the render function. Do not make the render function itself `async`; Solid SSR expects synchronous JSX evaluation.
+
+### v0.9.0 migration
+
+This is a breaking change in v0.9.0. In v0.8.x and earlier, examples often returned already-created JSX:
+
+```tsx
+// v0.8.x and earlier
+export default ssr(async () => <Page />);
+
+app.get("/", () => html(<Page />));
+```
+
+In v0.9.0, wrap JSX creation in a render function:
+
+```tsx
+// v0.9.0+
+export default ssr(async () => () => <Page />);
+
+app.get("/", () => html(() => <Page />));
+```
+
+This ensures Solid primitives such as `createUniqueId()` run inside `renderToString()`, where the SSR context exists.
+
 ## `createConfig` options
 
 ```ts
@@ -206,7 +245,7 @@ export const { config, html } = createConfig({
 // docs-app.ts
 const docsApp = new Hono()
   .route("/_ssr", routes(config))
-  .get("/", () => html(<DocsHome />));
+  .get("/", () => html(() => <DocsHome />));
 
 // host-app.ts
 export default new Hono().route("/docs", docsApp);
@@ -234,7 +273,7 @@ await Bun.build({
 
 - initializes `c.get("page")` as typed page options
 - accepts middlewares/validators before final handler
-- lets handlers return either JSX or `Response`
+- lets handlers return either a synchronous render function or `Response`
 
 ## Dev mode tools
 

package/package.json

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

package/src/adapter/bun.ts

@@ -23,7 +23,7 @@ type Routes = Record<string, RouteHandler>;
  * serve({
  *   routes: {
  *     ...routes(config),
- *     "/": () => html(<Home />),
+ *     "/": () => html(() => <Home />),
  *   },
  * });
  * ```

package/src/adapter/elysia.ts

@@ -20,7 +20,7 @@ import {
  * import { routes } from "@valentinkolb/ssr/adapter/elysia";
  * new Elysia()
  *   .use(routes(config))
- *   .get("/", () => html(<Home />))
+ *   .get("/", () => html(() => <Home />))
  *   .listen(3000);
  * ```
  */

package/src/adapter/hono.ts

@@ -5,8 +5,7 @@
 import { Hono } from "hono";
 import { createFactory } from "hono/factory";
 import type { Context, Env, Handler, MiddlewareHandler, TypedResponse } from "hono";
-import type { JSX } from "solid-js";
-import type { SsrConfig, HtmlFn } from "../index";
+import type { SsrConfig, HtmlFn, RenderFn } from "../index";
 import { getSsrDir, getCacheHeaders, createReloadResponse, safePath } from "./utils";
 
 // ============================================================================
@@ -20,8 +19,8 @@ type PageEnv<T extends object> = {
   };
 };
 
-/** SSR handler return type - JSX element or Response (for redirects etc.) */
-type SsrHandlerResult = JSX.Element | Response | TypedResponse;
+/** SSR handler return type - render function or Response (for redirects etc.) */
+type SsrHandlerResult = RenderFn | Response | TypedResponse;
 
 /** SSR handler function signature */
 type SsrHandler<E extends Env, T extends object> = (
@@ -41,7 +40,7 @@ type SsrHandlers = [MiddlewareHandler, ...MiddlewareHandler[], Handler];
  * Features:
  * - Full compatibility with Hono middlewares/validators
  * - Type-safe page options via `c.get("page")`
- * - Return JSX directly or Response for redirects
+ * - Return a render function or Response for redirects
  * - No manual `html()` call needed
  *
  * @example
@@ -88,7 +87,7 @@ type SsrHandlers = [MiddlewareHandler, ...MiddlewareHandler[], Handler];
  *     c.get("page").title = room.name;
  *     c.get("page").description = `Welcome to ${room.name}`;
  *
- *     return <RoomView room={room} />;
+ *     return () => <RoomView room={room} />;
  *   }
  * );
  * ```
@@ -125,7 +124,7 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
       await next();
     });
 
-    // Wrapped handler: JSX → html(), Response → passthrough
+    // Wrapped handler: render function → html(), Response → passthrough
     const wrappedHandler: Handler = async (c) => {
       const result = await finalHandler(c as Context<E & PageEnv<T>>);
 
@@ -134,8 +133,15 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
         return result;
       }
 
-      // Otherwise treat as JSX element and render with html()
-      return html(result as JSX.Element, c.get("page") as T);
+      if (typeof result !== "function") {
+        throw new Error("[ssr] ssr() handlers must return a render function: return () => <Page />");
+      }
+
+      if (result.constructor.name === "AsyncFunction") {
+        throw new Error("[ssr] ssr() render functions must be synchronous: return () => <Page />");
+      }
+
+      return html(result as RenderFn, c.get("page") as T);
     };
 
     // Return tuple for spread: .get('/path', ...ssr(handler))
@@ -155,7 +161,7 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
  * import { routes } from "@valentinkolb/ssr/adapter/hono";
  * const app = new Hono()
  *   .route("/_ssr", routes(config))
- *   .get("/", () => html(<Home />));
+ *   .get("/", () => html(() => <Home />));
  * ```
  */
 export const routes = (config: SsrConfig) => {

package/src/index.ts

@@ -68,7 +68,9 @@ export type SsrConfig = {
   ssrPath: string;
 };
 
-export type HtmlFn<T extends object> = (element: JSX.Element, options?: T) => Promise<Response>;
+export type RenderFn = () => JSX.Element;
+
+export type HtmlFn<T extends object> = (render: RenderFn, options?: T) => Promise<Response>;
 
 type PluginFn = () => BunPlugin;
 
@@ -151,8 +153,12 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
   const devConfigScript = `<script>globalThis.__SSR_CONFIG=${JSON.stringify({ ssrPath })}</script>`;
 
   // HTML renderer
-  const html: HtmlFn<T> = async (element, opts = {} as T) => {
-    const body = renderToString(() => element);
+  const html: HtmlFn<T> = async (render, opts = {} as T) => {
+    if (render.constructor.name === "AsyncFunction") {
+      throw new Error("[ssr] html() expects a synchronous render function: html(() => <Page />)");
+    }
+
+    const body = renderToString(render);
 
     // Framework-injected assets
     let scripts = `${islandDisplayStyle}\n${hydrationScript}`;