@k2b/ssr 0.12.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Valentin Kolb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,402 @@
+# @k2b/ssr
+
+Minimal SSR + islands framework for SolidJS on Bun.
+
+## Overview
+
+This library renders Solid components on the server and hydrates only interactive islands on the client.
+
+It uses file conventions:
+
+- `*.island.tsx`: SSR + hydrated on the client
+- `*.client.tsx`: client-only (no SSR HTML content)
+- `*.tsx`: server-only output
+
+## Size & Philosophy
+
+This framework is intentionally minimal and focused on SSR + islands only.
+
+Current source size in this repo (`packages/ssr-core/src`):
+
+| Component | Lines | Raw | Gzipped |
+| --- | ---: | ---: | ---: |
+| Core (`index`, `transform`, `build`, island ID + resolver) | ~750 | 26.2 KB | 8.3 KB |
+| Dev client (overlay + reload, dev only) | ~421 | 11.9 KB | 3.5 KB |
+| Adapters (`bun`, `hono`, `elysia`, shared utils) | ~465 | 14.4 KB | 4.8 KB |
+
+Important: these sizes describe framework source code that runs at build time and on the server.
+The browser receives only:
+
+- your island bundles
+- Solid runtime from your app dependencies
+- `seroval` deserialize runtime
+- a tiny hydration import snippet
+
+Framework overhead in the browser is intentionally small.
+
+What is intentionally not included:
+
+- no client-side router
+- no state management layer
+- no CSS-in-JS abstraction
+- no build tool wrapper around Bun
+
+Use the libraries you already prefer. This package only handles SSR and islands hydration.
+The optional `@k2b/ssr/nav` subpath provides progressive anchor
+enhancement for islands, but it still does not add route matching, loaders, or
+SPA routing.
+
+## Features
+
+- Small SSR core with Bun-native build/plugin flow
+- Adapters for Bun, Hono, and Elysia
+- Type-safe Hono page helper via `createSSRHandler`
+- Optional progressive navigation helpers via `@k2b/ssr/nav`
+- 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>`)
+- 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
+
+## Install
+
+```bash
+bun add @k2b/ssr solid-js
+
+# choose adapter deps you need
+bun add hono
+# or
+bun add elysia
+```
+
+### Package scope migration
+
+`@k2b/ssr` is the maintained successor to `@valentinkolb/ssr`. There are no
+framework API changes in the scope migration. Replace the dependency and all
+root or subpath imports:
+
+```ts
+// Before
+import { createConfig } from "@valentinkolb/ssr";
+import { routes } from "@valentinkolb/ssr/hono";
+
+// After
+import { createConfig } from "@k2b/ssr";
+import { routes } from "@k2b/ssr/hono";
+```
+
+## Required TypeScript settings
+
+```json
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+## Quick Start (Hono)
+
+### 1) Create config
+
+```ts
+// config.ts
+import { createConfig } from "@k2b/ssr";
+import { createSSRHandler, routes } from "@k2b/ssr/hono";
+
+type PageOptions = {
+  title?: string;
+  description?: string;
+};
+
+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>
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>${title ?? "App"}</title>
+        ${description ? `<meta name="description" content="${description}">` : ""}
+      </head>
+      <body>${body}${scripts}</body>
+    </html>
+  `,
+});
+
+export const ssr = createSSRHandler(html);
+export { routes };
+```
+
+### 2) Register plugin in dev
+
+```ts
+// scripts/preload.ts
+import { plugin } from "../config";
+
+Bun.plugin(plugin());
+```
+
+### 3) Create an island
+
+```tsx
+// components/Counter.island.tsx
+import { createSignal } from "solid-js";
+
+export default function Counter({ initial = 0 }: { initial?: number }) {
+  const [count, setCount] = createSignal(initial);
+  return <button onClick={() => setCount((c) => c + 1)}>Count: {count()}</button>;
+}
+```
+
+### 4) Create a page
+
+```tsx
+// pages/Home.tsx
+import { ssr } from "../config";
+import Counter from "../components/Counter.island";
+
+export default ssr(async (c) => {
+  c.get("page").title = "Home";
+  return () => <Counter initial={5} />;
+});
+```
+
+### 5) Wire server
+
+```ts
+// server.ts
+import { Hono } from "hono";
+import { config, routes } from "./config";
+import Home from "./pages/Home";
+
+export default new Hono()
+  .route("/_ssr", routes(config))
+  .get("/", ...Home);
+```
+
+### 6) Run
+
+```bash
+NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
+```
+
+## Adapter imports
+
+- Bun: `@k2b/ssr/bun`
+- Hono: `@k2b/ssr/hono`
+- Elysia: `@k2b/ssr/elysia`
+
+## Optional Navigation Helpers
+
+`@k2b/ssr/nav` is an opt-in browser helper for islands that want to
+update URL history after they have already updated client state.
+
+```tsx
+import { createSignal, onCleanup, onMount } from "solid-js";
+import { Link, listenPopState, type LinkNavigateEvent } from "@k2b/ssr/nav";
+
+export default function Tabs() {
+  const [tab, setTab] = createSignal("alpha");
+
+  onMount(() => {
+    onCleanup(
+      listenPopState(({ url }) => {
+        setTab(url.searchParams.get("tab") ?? "alpha");
+      }),
+    );
+  });
+
+  const openTab = (nav: LinkNavigateEvent) => {
+    const next = nav.url.searchParams.get("tab") ?? "alpha";
+    setTab(next);
+    nav.push(`/demo?tab=${next}`, { scroll: "preserve", state: { tab: next } });
+  };
+
+  return (
+    <Link href="/demo?tab=beta" scroll="preserve" onNavigate={openTab}>
+      Open beta
+    </Link>
+  );
+}
+```
+
+`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()`.
+
+Use `listenPopState()` whenever `nav.push()` represents client state. Browser
+Back/Forward changes history but cannot infer how an island maps the URL back to
+signals or stores. The helper reports the current `URL`, native `PopStateEvent`,
+and history state without adding route matching or data loading.
+
+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
+- relative URLs follow `document.baseURI`
+- cross-origin `navigate()` calls use full document navigation
+- replace navigation preserves existing `history.state` unless `state` is set
+- rejected async `onNavigate` callbacks log the error and fall back to a full
+  document navigation
+
+Available exports:
+
+- `Link`
+- `navigate()`, `navigateTo()`, `documentNavigate()`, `currentPathWithQuery()`, `refreshCurrentPath()`
+- `captureScroll()`, `restoreScroll()`, `listenPopState()`, `startViewTransition()`
+- `LinkNavigateEvent`, `LinkProps`, `EnhancedNavigateOptions`, `NavigationScrollMode`, `PopStateNavigationEvent`, `ScrollSnapshot`
+
+Use `data-scroll-preserve="stable-key"` on scroll containers that should keep
+their scroll position across enhanced navigation.
+
+## 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
+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
+  devSourcemap?: "none" | "linked" | "inline"; // default: "linked"
+  template?: ({ body, scripts, ...custom }) => string | Promise<string>;
+})
+```
+
+### 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`.
+- Development builds emit linked source maps by default. Use `"inline"` only when a tool requires embedded maps, or `"none"` to disable them.
+- In production, hydration imports include a build timestamp query (`?v=...`) for cache busting.
+- All adapters stream island assets from `Bun.file`. Production assets and content-hashed development chunks are immutable; stable development entries and source maps use validators for inexpensive freshness checks.
+
+## 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
+// scripts/build.ts
+import { plugin } from "./config";
+
+await Bun.build({
+  entrypoints: ["src/server.tsx"],
+  outdir: "dist",
+  target: "bun",
+  plugins: [plugin()],
+});
+```
+
+## Hono `createSSRHandler` behavior
+
+`createSSRHandler(html)` returns an `ssr()` helper that:
+
+- initializes `c.get("page")` as typed page options
+- accepts middlewares/validators before final handler
+- lets handlers return either a synchronous render function or `Response`
+
+## Dev mode tools
+
+With `dev: true`, a small `[ssr]` overlay is injected.
+
+It can:
+
+- auto-reload on server restart
+- highlight island/client boundaries
+- show source filenames for wrapped components
+
+In browsers with Web Locks support, auto-reload elects one visible tab per
+origin and SSR path to hold the SSE connection. Hidden tabs suspend reload work,
+leadership transfers automatically, and cached pages resume safely after a
+back-forward cache restore. Browsers without Web Locks retain visibility-scoped
+per-tab connections as a compatibility fallback.
+
+## Limitations
+
+- islands must use default export
+- props must be serializable via `seroval`; do not pass functions, callbacks, event handlers, Solid signals/stores, DOM nodes, or class instances as island/client props
+- nested island/client imports are not supported
+
+## Local monorepo example
+
+This repo includes a current example app:
+
+- `packages/ssr-example`
+
+Run from workspace root:
+
+```bash
+bun run dev:example
+```

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@k2b/ssr",
+  "version": "0.12.0-rc.0",
+  "description": "Minimal SSR framework for SolidJS and Bun",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./bun": "./src/adapter/bun.ts",
+    "./elysia": "./src/adapter/elysia.ts",
+    "./hono": "./src/adapter/hono.ts",
+    "./nav": "./src/nav.ts"
+  },
+  "scripts": {
+    "test": "bunx tsc -p test/tsconfig.json && bun test test/unit && bun test --conditions=browser --preload ./test/browser/setup.ts test/browser"
+  },
+  "peerDependencies": {
+    "elysia": "^1.0.0",
+    "hono": "^4.0.0",
+    "solid-js": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "elysia": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@babel/core": "^7.29.7",
+    "@babel/preset-typescript": "^7.29.7",
+    "@types/babel__core": "^7.20.5",
+    "babel-preset-solid": "^1.9.12",
+    "seroval": "^1.5.5"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
+    "@types/bun": "^1.3.14",
+    "elysia": "^1.4.29",
+    "file-type": "^21.3.1",
+    "hono": "^4.12.30",
+    "solid-js": "^1.9.14",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "author": "Valentin Kolb",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/k2b-dev/ssr.git"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "ssr",
+    "bun",
+    "server-side-rendering",
+    "islands",
+    "elysia",
+    "hono"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/adapter/bun.ts

@@ -0,0 +1,51 @@
+/**
+ * Bun.serve() adapter - provides routes object for native Bun server.
+ * Serves island chunks from _ssr and dev tools endpoints.
+ */
+import type { SsrConfig } from "../index";
+import {
+  createAssetResponse,
+  createPingResponse,
+  getSsrDir,
+  createReloadResponse,
+} from "./utils";
+
+type RouteHandler = (req: Request) => Response | Promise<Response>;
+type Routes = Record<string, RouteHandler>;
+
+/**
+ * Creates routes for Bun.serve from SSR config.
+ *
+ * @example
+ * ```ts
+ * import { routes } from "@k2b/ssr/bun";
+ * serve({
+ *   routes: {
+ *     ...routes(config),
+ *     "/": () => html(() => <Home />),
+ *   },
+ * });
+ * ```
+ */
+export const routes = (config: SsrConfig): Routes => {
+  const { dev, ssrPath } = config;
+  const ssrDir = getSsrDir(config);
+
+  const devRoutes: Routes = dev
+    ? {
+        [`${ssrPath}/_reload`]: (req) => createReloadResponse(req.signal),
+        [`${ssrPath}/_ping`]: () => createPingResponse(),
+      }
+    : {};
+
+  const serveAsset: RouteHandler = (req) => {
+    const filename = new URL(req.url).pathname.split("/").pop()!;
+    return createAssetResponse(req, ssrDir, filename, dev);
+  };
+
+  return {
+    ...devRoutes,
+    [`${ssrPath}/*.js`]: serveAsset,
+    [`${ssrPath}/*.js.map`]: serveAsset,
+  };
+};