npm - @valentinkolb/ssr - Versions diffs - 0.7.3 → 0.9.0 - Mend

@valentinkolb/ssr 0.7.3 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -49,6 +49,7 @@ Use the libraries you already prefer. This package only handles SSR and islands
 - Adapters for Bun, Hono, and Elysia
 - Type-safe Hono page helper via `createSSRHandler`
 - 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>`)
@@ -56,7 +57,6 @@ Use the libraries you already prefer. This package only handles SSR and islands
 ```bash
 bun add @valentinkolb/ssr solid-js
-bun add -d @babel/core @babel/preset-typescript babel-preset-solid
 # choose adapter deps you need
 bun add hono
@@ -95,6 +95,8 @@ export const { config, plugin, html } = createConfig<PageOptions>({
   dev: process.env.NODE_ENV === "development",
   // For monorepos with separated packages:
   // rootDir: "/path/to/workspace-root",
+  // For microfrontends mounted under /docs:
+  // basePath: "/docs",
   template: ({ body, scripts, title, description }) => `
     <!doctype html>
     <html>
@@ -143,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} />;
 });
 ```
@@ -172,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
@@ -179,6 +220,7 @@ createConfig({
   dev?: boolean;         // default: false
   verbose?: boolean;     // default: !dev
   rootDir?: string;      // default: process.cwd()
+  basePath?: string;     // default: "", example: "/docs"
   external?: string[];   // passed to Bun.build for island bundle
   template?: ({ body, scripts, ...custom }) => string | Promise<string>;
 })
@@ -187,8 +229,30 @@ createConfig({
 ### Notes
 - `rootDir` is important in monorepos where server entrypoint and island files live in different packages.
+- `basePath` moves SSR assets and dev endpoints under that prefix, e.g. `/docs/_ssr`.
 - In production, hydration imports include a build timestamp query (`?v=...`) for cache busting.
+## Microfrontend mount example
+Use `basePath` when the SSR app is mounted under a sub-path:
+```ts
+// config.ts
+export const { config, html } = createConfig({
+  basePath: "/docs",
+});
+// docs-app.ts
+const docsApp = new Hono()
+  .route("/_ssr", routes(config))
+  .get("/", () => html(() => <DocsHome />));
+// host-app.ts
+export default new Hono().route("/docs", docsApp);
+```
+With this setup, hydration chunks and dev endpoints are served from `/docs/_ssr/...`.
 ## Build for production
 ```ts
@@ -209,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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/ssr",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",
@@ -32,15 +32,15 @@
     }
   },
   "dependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-typescript": "^7.24.0",
+    "babel-preset-solid": "^1.8.0",
     "seroval": "^1.0.0"
   },
   "devDependencies": {
-    "@babel/core": "^7.24.0",
-    "@babel/preset-typescript": "^7.24.0",
     "@elysiajs/static": "^1.2.0",
     "@types/babel__core": "^7.20.5",
     "@types/bun": "latest",
-    "babel-preset-solid": "^1.8.0",
     "elysia": "^1.2.0",
     "hono": "^4.6.14",
     "solid-js": "^1.9.0",

package/src/adapter/bun.ts CHANGED Viewed

@@ -23,26 +23,26 @@ type Routes = Record<string, RouteHandler>;
  * serve({
  *   routes: {
  *     ...routes(config),
- *     "/": () => html(<Home />),
+ *     "/": () => html(() => <Home />),
  *   },
  * });
  * ```
  */
 export const routes = (config: SsrConfig): Routes => {
-  const { dev } = config;
+  const { dev, ssrPath } = config;
   const ssrDir = getSsrDir(config);
   const devRoutes: Routes = dev
     ? {
-        "/_ssr/_reload": () => createReloadResponse(),
-        "/_ssr/_ping": () => new Response("ok"),
+        [`${ssrPath}/_reload`]: () => createReloadResponse(),
+        [`${ssrPath}/_ping`]: () => new Response("ok"),
       }
     : {};
   return {
     ...devRoutes,
-    "/_ssr/*.js": async (req) => {
+    [`${ssrPath}/*.js`]: async (req) => {
       const filename = new URL(req.url).pathname.split("/").pop()!;
       const path = safePath(ssrDir, filename);
       if (!path) return notFound();

package/src/adapter/client.js CHANGED Viewed

@@ -3,8 +3,10 @@ if (!window.__ssr_reload) {
   window.__ssr_reload = true;
   (function () {
+    const ssrPath = globalThis.__SSR_CONFIG?.ssrPath || "/_ssr";
     // Settings
-    const STORAGE_KEY = "_ssr";
+    const STORAGE_KEY = `_ssr:${ssrPath}`;
     const defaults = {
       autoReload: true,
       highlightIslands: false,
@@ -24,9 +26,9 @@ if (!window.__ssr_reload) {
     const highlightCSS = (tag, color) => `
       ${tag} {
-        display: block;
+        display: block !important;
         box-shadow: 0 0 0 1px ${color} !important;
-        position: relative;
+        position: relative !important;
       }
       ${tag}::before {
         content: attr(data-file);
@@ -178,7 +180,7 @@ if (!window.__ssr_reload) {
     const start = () => {
       if (es) return;
       try {
-        es = new EventSource("/_ssr/_reload");
+        es = new EventSource(`${ssrPath}/_reload`);
         stopAnimation();
         badge.innerText = "[ssr]";
       } catch {
@@ -191,7 +193,7 @@ if (!window.__ssr_reload) {
         startAnimation();
         if (!settings.autoReload) return;
         reconnectInterval = setInterval(() => {
-          fetch("/_ssr/_ping")
+          fetch(`${ssrPath}/_ping`)
             .then((r) => r.ok && location.reload())
             .catch(() => {});
         }, 300);

package/src/adapter/elysia.ts CHANGED Viewed

@@ -20,22 +20,22 @@ import {
  * import { routes } from "@valentinkolb/ssr/adapter/elysia";
  * new Elysia()
  *   .use(routes(config))
- *   .get("/", () => html(<Home />))
+ *   .get("/", () => html(() => <Home />))
  *   .listen(3000);
  * ```
  */
 export const routes = (config: SsrConfig) => {
-  const { dev } = config;
+  const { dev, ssrPath } = config;
   const ssrDir = getSsrDir(config);
   return new Elysia({ name: "ssr" })
     .use(
       staticPlugin({
         assets: ssrDir,
-        prefix: "/_ssr",
+        prefix: ssrPath,
         headers: { "Cache-Control": getCacheHeaders(dev) },
       }),
     )
-    .get("/_ssr/_reload", () => (dev ? createReloadResponse() : notFound()))
-    .get("/_ssr/_ping", () => (dev ? new Response("ok") : notFound()));
+    .get(`${ssrPath}/_reload`, () => (dev ? createReloadResponse() : notFound()))
+    .get(`${ssrPath}/_ping`, () => (dev ? new Response("ok") : notFound()));
 };

package/src/adapter/hono.ts CHANGED Viewed

@@ -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/adapter/utils.ts CHANGED Viewed

@@ -5,6 +5,27 @@
 import { dirname, join, resolve } from "path";
 import type { SsrConfig } from "../index";
+/**
+ * Normalize a public app base path.
+ * - undefined, "", "/" => ""
+ * - "/docs/" => "/docs"
+ * - values without leading slash are rejected
+ */
+export const normalizeBasePath = (input?: string): string => {
+  const value = input?.trim() ?? "";
+  if (!value || value === "/") return "";
+  if (!value.startsWith("/")) {
+    throw new Error(`[ssr] basePath must start with "/" or be empty. Received: ${JSON.stringify(input)}`);
+  }
+  return value.replace(/\/+$/, "");
+};
+/**
+ * Public HTTP path prefix used for SSR assets/endpoints.
+ */
+export const toSsrPath = (basePath: string): string =>
+  basePath ? `${basePath}/_ssr` : "/_ssr";
 /**
  * Get the _ssr directory path based on dev/prod mode.
  * Dev: uses config.rootDir (fallback process.cwd())

package/src/build.ts CHANGED Viewed

@@ -16,6 +16,57 @@ const getSelector = (type: ComponentType, id: string) =>
 const fmt = (ms: number) => (ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${Math.round(ms)}ms`);
+/**
+ * Workaround for Bun bundler bug: duplicate export statements in shared chunks
+ * when splitting=true. We only run this in production because rewriting chunk
+ * source in dev can affect evaluation order in cyclic-sensitive modules.
+ */
+export const dedupeSharedChunkExports = async (outdir: string, verbose: boolean): Promise<number> => {
+  let fixedChunks = 0;
+  const chunkGlob = new Glob("chunk-*.js");
+  for await (const chunkFile of chunkGlob.scan({ cwd: outdir, absolute: true })) {
+    const src = await Bun.file(chunkFile).text();
+    // Collect all export blocks and deduplicate.
+    const exportRegex = /^export\s*\{[^}]*\}\s*;?\s*$/gm;
+    const exportBlocks = [...src.matchAll(exportRegex)].map((m) => m[0]);
+    if (exportBlocks.length > 1) {
+      // Parse all exported names from all blocks.
+      const seenNames = new Set<string>();
+      const uniqueBlocks: string[] = [];
+      for (const block of exportBlocks) {
+        const names =
+          block
+            .match(/\{([^}]*)\}/)?.[1]
+            ?.split(",")
+            .map((n) => n.trim())
+            .filter(Boolean) ?? [];
+        const newNames = names.filter((n) => !seenNames.has(n));
+        if (newNames.length > 0) {
+          uniqueBlocks.push(`export { ${newNames.join(", ")} };`);
+          newNames.forEach((n) => seenNames.add(n));
+        }
+      }
+      // Replace all export blocks with deduplicated ones.
+      let fixed = src;
+      for (const block of exportBlocks) {
+        fixed = fixed.replace(block, "");
+      }
+      // Append single combined export before any debugId comment.
+      const debugIdIdx = fixed.lastIndexOf("//# debugId=");
+      const combined = uniqueBlocks.join("\n") + "\n";
+      if (debugIdIdx !== -1) {
+        fixed = fixed.slice(0, debugIdIdx) + combined + fixed.slice(debugIdIdx);
+      } else {
+        fixed = fixed.trimEnd() + "\n" + combined;
+      }
+      await Bun.write(chunkFile, fixed);
+      fixedChunks += 1;
+      if (verbose) console.log(`  Fixed duplicate exports in ${chunkFile.split("/").pop()}`);
+    }
+  }
+  return fixedChunks;
+};
 export const buildIslands = async (options: {
   pattern: string;
   outdir: string;
@@ -130,49 +181,10 @@ export const buildIslands = async (options: {
     ],
   });
-  // Workaround for Bun bundler bug: duplicate export statements in shared chunks
-  // when splitting: true. Scan chunk files and deduplicate export lines.
-  if (result.success) {
-    const chunkGlob = new Glob("chunk-*.js");
-    for await (const chunkFile of chunkGlob.scan({ cwd: outdir, absolute: true })) {
-      const src = await Bun.file(chunkFile).text();
-      // Collect all export blocks and deduplicate
-      const exportRegex = /^export\s*\{[^}]*\}\s*;?\s*$/gm;
-      const exportBlocks = [...src.matchAll(exportRegex)].map((m) => m[0]);
-      if (exportBlocks.length > 1) {
-        // Parse all exported names from all blocks
-        const seenNames = new Set<string>();
-        const uniqueBlocks: string[] = [];
-        for (const block of exportBlocks) {
-          const names =
-            block
-              .match(/\{([^}]*)\}/)?.[1]
-              ?.split(",")
-              .map((n) => n.trim())
-              .filter(Boolean) ?? [];
-          const newNames = names.filter((n) => !seenNames.has(n));
-          if (newNames.length > 0) {
-            uniqueBlocks.push(`export { ${newNames.join(", ")} };`);
-            newNames.forEach((n) => seenNames.add(n));
-          }
-        }
-        // Replace all export blocks with deduplicated ones
-        let fixed = src;
-        for (const block of exportBlocks) {
-          fixed = fixed.replace(block, "");
-        }
-        // Append single combined export before any debugId comment
-        const debugIdIdx = fixed.lastIndexOf("//# debugId=");
-        const combined = uniqueBlocks.join("\n") + "\n";
-        if (debugIdIdx !== -1) {
-          fixed = fixed.slice(0, debugIdIdx) + combined + fixed.slice(debugIdIdx);
-        } else {
-          fixed = fixed.trimEnd() + "\n" + combined;
-        }
-        await Bun.write(chunkFile, fixed);
-        if (verbose) console.log(`  Fixed duplicate exports in ${chunkFile.split("/").pop()}`);
-      }
-    }
+  if (result.success && !dev) {
+    await dedupeSharedChunkExports(outdir, verbose);
+  } else if (result.success && dev && verbose) {
+    console.log("Skipped shared-chunk export rewrite in dev mode.");
   }
   if (verbose) {

package/src/index.ts CHANGED Viewed

@@ -12,6 +12,7 @@ import { transform } from "./transform";
 import { buildIslands } from "./build";
 import { join, dirname, resolve } from "path";
 import { resolveIslandImport } from "./island-resolve";
+import { normalizeBasePath, toSsrPath } from "./adapter/utils";
 // @ts-ignore - Bun text import
 import devClientCode from "./adapter/client.js" with { type: "text" };
@@ -46,6 +47,8 @@ export type SsrOptions<T extends object = object> = {
   verbose?: boolean;
   /** Project root for island discovery and dev _ssr assets (default: process.cwd()) */
   rootDir?: string;
+  /** Public app mount path for SSR assets and dev endpoints (default: "") */
+  basePath?: string;
   /** Modules to exclude from the island bundle (passed to Bun.build) */
   external?: string[];
   /** HTML template function (optional, has default) */
@@ -61,9 +64,13 @@ export type SsrConfig = {
   dev: boolean;
   verbose?: boolean;
   rootDir?: string;
+  basePath: string;
+  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;
@@ -105,8 +112,10 @@ export type SsrResult<T extends object> = {
  * ```
  */
 export const createConfig = <T extends object = object>(options: SsrOptions<T> = {}): SsrResult<T> => {
-  const { dev = false, verbose, external, template, rootDir: rootDirOption } = options;
+  const { dev = false, verbose, external, template, rootDir: rootDirOption, basePath: basePathOption } = options;
   const rootDir = resolve(rootDirOption ?? process.cwd());
+  const basePath = normalizeBasePath(basePathOption);
+  const ssrPath = toSsrPath(basePath);
   // Default template if none provided
   const htmlTemplate =
@@ -130,23 +139,33 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
     dev,
     verbose,
     rootDir,
+    basePath,
+    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 v=${JSON.stringify(buildVersion)};document.querySelectorAll('solid-island,solid-client').forEach(e=>import('/_ssr/'+e.dataset.id+'.js'+(v?'?v='+v:'')));</script>`;
+  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 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);
-    // Component scripts
-    let scripts = hydrationScript;
+    // Framework-injected assets
+    let scripts = `${islandDisplayStyle}\n${hydrationScript}`;
     // Add dev tools script in dev mode (inlined)
     if (dev) {
-      scripts += `\n<script type="module">${devClientCode}</script>`;
+      scripts += `\n${devConfigScript}\n<script type="module">${devClientCode}</script>`;
     }
     const content = await htmlTemplate({