@valentinkolb/ssr 0.0.1

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,290 @@
+# @valentinkolb/SSR
+
+A minimal server-side rendering framework for SolidJS and Bun with islands architecture.
+
+## Overview
+
+This framework provides SSR capabilities for SolidJS applications using Bun's runtime. It follows the islands architecture pattern where you can selectively hydrate interactive components while keeping the rest of your page static HTML.
+
+The entire framework is roughly 750 lines of code with zero runtime dependencies beyond Solid, seroval and your chosen web framework adapter.
+
+## Features
+
+- **Minimal footprint**: Under 800 lines of core code and seroval as only dependency beside solid and your chosen web framework.
+- **Islands architecture**: `*.island.tsx` for hydrated components, `*.client.tsx` for client-only - thats it
+- **Framework agnostic**: Works with Bun's native server, **Elysia**, or **Hono**
+- **Fast**: Built on Bun's runtime with optimized bundling
+- **Dev experience**: Hot reload, source maps, and TypeScript support
+
+## Quick Start
+
+Install the package:
+
+```bash
+bun add @valentinkolb/ssr@jsr solid-js
+```
+
+Create a configuration file (optional - has sensible defaults):
+
+```typescript
+// config.ts
+import { createConfig } from "@valentinkolb/ssr";
+
+export const { config, plugin, html } = createConfig({
+  dev: process.env.NODE_ENV === "development",
+});
+```
+
+Create an interactive island component:
+
+```tsx
+// components/Counter.island.tsx
+import { createSignal } from "solid-js";
+
+export default function Counter({ initialCount = 0 }) {
+  const [count, setCount] = createSignal(initialCount);
+
+  return (
+    <button onClick={() => setCount(count() + 1)}>
+      Count: {count()}
+    </button>
+  );
+}
+```
+
+Use it in a page:
+
+```tsx
+// pages/Home.tsx
+import Counter from "../components/Counter.island";
+
+export default function Home() {
+  return (
+    <div>
+      <h1>My Page</h1>
+      <Counter initialCount={5} />
+    </div>
+  );
+}
+```
+
+## Adapter Usage
+
+### Bun Native Server
+
+```typescript
+import { Bun } from "bun";
+import { routes } from "@valentinkolb/ssr/adapter/bun";
+import { config, html } from "./config";
+import Home from "./pages/Home";
+
+Bun.serve({
+  port: 3000,
+  routes: {
+    ...routes(config),
+    "/": () => html(<Home />),
+  },
+});
+```
+
+### Hono
+
+```typescript
+import { Hono } from "hono";
+import { routes } from "@valentinkolb/ssr/adapter/hono";
+import { config, html } from "./config";
+import Home from "./pages/Home";
+
+const app = new Hono()
+  .route("/_ssr", routes(config))
+  .get("/", async (c) => {
+    const response = await html(<Home />);
+    return c.html(await response.text());
+  });
+
+export default app;
+```
+
+### Elysia
+
+```typescript
+import { Elysia } from "elysia";
+import { routes } from "@valentinkolb/ssr/adapter/elysia";
+import { config, html } from "./config";
+import Home from "./pages/Home";
+
+new Elysia()
+  .use(routes(config))
+  .get("/", () => html(<Home />))
+  .listen(3000);
+```
+
+## Build Configuration
+
+Add the plugin to your build script:
+
+```typescript
+// scripts/build.ts
+import { plugin } from "./config";
+
+await Bun.build({
+  entrypoints: ["src/server.tsx"],
+  outdir: "dist",
+  target: "bun",
+  plugins: [plugin()],
+});
+```
+
+For development with watch mode:
+
+```typescript
+// scripts/preload.ts
+import { plugin } from "./config";
+
+Bun.plugin(plugin());
+```
+
+```json
+{
+  "scripts": {
+    "dev": "bun --watch --preload=./scripts/preload.ts run src/server.tsx",
+    "build": "bun run scripts/build.ts",
+    "start": "bun run dist/server.js"
+  }
+}
+```
+
+## Component Types
+
+### Island Components (`*.island.tsx`)
+
+Island components are server-rendered and then hydrated on the client. They should be used for interactive UI elements that need JavaScript.
+
+```tsx
+// Sidebar.island.tsx
+import { createSignal } from "solid-js";
+
+export default function Sidebar() {
+  const [open, setOpen] = createSignal(false);
+  return <div>{open() ? "Open" : "Closed"}</div>;
+}
+```
+
+### Client-Only Components (`*.client.tsx`)
+
+Client-only components are not rendered on the server. They render only in the browser, useful for components that depend on browser APIs.
+
+```tsx
+// ThemeToggle.client.tsx
+import { createSignal, onMount } from "solid-js";
+
+export default function ThemeToggle() {
+  const [theme, setTheme] = createSignal("light");
+  
+  onMount(() => {
+    setTheme(localStorage.getItem("theme") || "light");
+  });
+  
+  return <button onClick={() => setTheme(theme() === "light" ? "dark" : "light")}>
+    {theme()}
+  </button>;
+}
+```
+
+### Regular Components
+
+Standard Solid components that are only rendered on the server. No client-side JavaScript is shipped for these.
+
+```tsx
+// Header.tsx
+export default function Header() {
+  return <header><h1>My Site</h1></header>;
+}
+```
+
+## Props Serialization
+
+The framework uses [seroval](https://github.com/lxsmnsyc/seroval) for props serialization, which supports complex JavaScript types that JSON cannot handle:
+
+```tsx
+<Island
+  date={new Date()}
+  map={new Map([["key", "value"]])}
+  set={new Set([1, 2, 3])}
+  regex={/test/gi}
+  bigint={123n}
+  undefined={undefined}
+/>
+```
+
+## Custom HTML Template
+
+You can pass additional options to your HTML template. All options are type safe!
+
+```typescript
+type PageOptions = { title: string; description?: string };
+
+const { html } = createConfig<PageOptions>({
+  template: ({
+    body, scripts,     // must be provided and used for hydration
+    title, description // user defined options
+  }) => `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>${title}</title>
+        ${description ? `<meta name="description" content="${description}">` : ""}
+      </head>
+      <body>${body}${scripts}</body>
+    </html>
+  `,
+});
+
+// Usage
+await html(<Home />, { 
+  title: "Home Page",               // type safe
+  description: "Welcome to my site" // type safe
+});
+```
+
+## How It Works
+
+1. **Build time**: The framework discovers all `*.island.tsx` and `*.client.tsx` files in the project and bundles them separately for the browser
+2. **During SSR**: Normal components are rendered to HTML strings. Island/client components are wrapped in custom elements with data attributes containing their props
+3. **At the client**: Individual island bundles load and hydrate their corresponding DOM elements
+
+The framework uses a Babel plugin to transform island imports into wrapped components during SSR. Props are serialized using seroval and embedded in data attributes. On the client, each island bundle deserializes its props and renders the component.
+
+Babel is used since Solid only supports Babel for JSX transformation at the moment.
+
+## File Structure
+
+```
+src/
+├── index.ts       # Core SSR logic and createConfig()
+├── transform.ts   # Babel plugin for island wrapping
+├── build.ts       # Island bundling with code splitting
+├── bun.ts         # Bun.serve() adapter
+├── elysia.ts      # Elysia adapter
+├── hono.ts        # Hono adapter
+└── client.js      # Dev mode auto-reload client
+```
+
+## Configuration Options
+
+```typescript
+createConfig({
+  dev?: boolean;                // Enable dev mode (default: false)
+  verbose?: boolean;            // Enable verbose logging (default: !dev)
+  autoRefresh?: boolean;        // Enable auto-reload in dev (default: true)
+  template?: (context) => string; // HTML template function (optional, has default)
+})
+```
+
+## Contributing
+
+Contributions are welcome! The codebase is intentionally minimal. Keep changes focused and avoid adding unnecessary complexity.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@valentinkolb/ssr",
+  "version": "0.0.1",
+  "description": "Minimal SSR framework for SolidJS and Bun",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapter/bun": "./src/adapter/bun.ts",
+    "./adapter/elysia": "./src/adapter/elysia.ts",
+    "./adapter/hono": "./src/adapter/hono.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build:example": "bun run example/build.ts",
+    "example": "bun --watch --preload=./example/preload.ts run example/server.tsx",
+    "dev": "bun run build:example && bun run example"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.0",
+    "elysia": "^1.0.0",
+    "@elysiajs/static": "^1.0.0",
+    "hono": ""
+  },
+  "peerDependenciesMeta": {
+    "elysia": {
+      "optional": true
+    },
+    "@elysiajs/static": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "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",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "author": "Valentin Kolb",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/valentinkolb/ssr"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "ssr",
+    "bun",
+    "server-side-rendering",
+    "elysia",
+    "hono"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.js",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/adapter/bun.ts

@@ -0,0 +1,105 @@
+import { join, dirname } from "path";
+import type { SsrConfig } from "../index";
+// @ts-ignore - Bun text import
+import devClientCode from "./client.js" with { type: "text" };
+
+type RouteHandler = (req: Request) => Response | Promise<Response>;
+type Routes = Record<string, RouteHandler>;
+
+/**
+ * Creates routes for Bun.serve from SSR config.
+ * Only handles /_ssr/* routes for islands and dev tools.
+ * Static file serving should be handled by the user.
+ *
+ * @example
+ * ```ts
+ * import { routes } from "@valentinkolb/ssr/bun";
+ * import { config, html } from "./config";
+ *
+ * serve({
+ *   routes: {
+ *     ...routes(config),
+ *     "/": () => html(<Home />),
+ *     // Handle static files yourself:
+ *     "/public/*": (req) => {
+ *       const path = new URL(req.url).pathname.replace("/public/", "");
+ *       return new Response(Bun.file(`./public/${path}`));
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export const routes = (config: SsrConfig): Routes => {
+  const { dev, autoRefresh } = config;
+
+  return {
+    // Dev mode: SSE endpoint for live reload
+    "/_ssr/_reload": () => {
+      if (!dev || !autoRefresh) {
+        return new Response("Not found", { status: 404 });
+      }
+      return new Response(
+        new ReadableStream({
+          start(controller) {
+            controller.enqueue(new TextEncoder().encode(": connected\n\n"));
+            const interval = setInterval(() => {
+              try {
+                controller.enqueue(new TextEncoder().encode(": ping\n\n"));
+              } catch {
+                clearInterval(interval);
+              }
+            }, 5000);
+          },
+        }),
+        {
+          headers: {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+          },
+        },
+      );
+    },
+
+    // Dev mode: Ping endpoint for reconnection check
+    "/_ssr/_ping": () => {
+      if (!dev || !autoRefresh) {
+        return new Response("Not found", { status: 404 });
+      }
+      return new Response("ok");
+    },
+
+    // Dev mode: Serve reload client script
+    "/_ssr/_client.js": () => {
+      if (!dev || !autoRefresh) {
+        return new Response("Not found", { status: 404 });
+      }
+      return new Response(devClientCode, {
+        headers: {
+          "Content-Type": "application/javascript",
+          "Cache-Control": "no-cache",
+        },
+      });
+    },
+
+    // Serve islands
+    "/_ssr/*.js": async (req) => {
+      const filename = new URL(req.url).pathname.split("/").pop()!;
+
+      const file = Bun.file(join(dev ? "." : Bun.main, "_ssr", filename));
+
+      if (!(await file.exists())) {
+        return new Response("Not found", { status: 404 });
+      }
+
+      return new Response(file, {
+        headers: {
+          "Content-Type": file.type,
+          "Cache-Control": dev
+            ? "no-cache"
+            : "public, max-age=31536000, immutable",
+        },
+      });
+    },
+  };
+};

package/src/adapter/client.js

@@ -0,0 +1,75 @@
+// Dev mode live-reload client
+// Uses Server-Sent Events to detect server restart
+
+if (!window.__ssr_reload) {
+  window.__ssr_reload = true;
+
+  // Tooltip
+  const tooltip = document.body.appendChild(
+    Object.assign(document.createElement("div"), {
+      innerHTML: `
+        auto refresh enabled
+        <br/><br/>
+        to disable, add to config
+        <br/>
+        { autoRefresh: false }
+      `,
+    }),
+  );
+  Object.assign(tooltip.style, {
+    fontFamily: "monospace",
+    fontSize: "12px",
+    color: "#888",
+    background: "#000",
+    padding: "8px",
+    border: "1px solid #333",
+    position: "fixed",
+    bottom: "28px",
+    left: "8px",
+    zIndex: "9999",
+    display: "none",
+  });
+
+  // Badge
+  const badge = document.body.appendChild(
+    Object.assign(document.createElement("div"), {
+      innerText: "[ssr]",
+      onmouseenter: () => (tooltip.style.display = "block"),
+      onmouseleave: () => (tooltip.style.display = "none"),
+    }),
+  );
+  Object.assign(badge.style, {
+    fontFamily: "monospace",
+    fontSize: "12px",
+    color: "#555",
+    position: "fixed",
+    bottom: "8px",
+    left: "8px",
+    zIndex: "9999",
+    cursor: "default",
+  });
+
+  const es = new EventSource("/_ssr/_reload");
+
+  es.onerror = () => {
+    es.close();
+    window.__ssr_reload = false;
+    badge.innerText = "[...]";
+
+    const check = setInterval(() => {
+      fetch("/_ssr/_ping")
+        .then(({ ok }) => {
+          if (!ok) return;
+          clearInterval(check);
+          location.reload();
+        })
+        .catch(() => {});
+    }, 300);
+  };
+
+  // Clean up on page unload (for bfcache)
+  window.addEventListener("pagehide", () => {
+    es.close();
+    window.__ssr_reload = false;
+  });
+}

package/src/adapter/elysia.ts

@@ -0,0 +1,96 @@
+import { Elysia } from "elysia";
+import { staticPlugin } from "@elysiajs/static";
+import { join } from "path";
+import type { SsrConfig } from "../index";
+// @ts-ignore - Bun text import
+import devClientCode from "./client.js" with { type: "text" };
+
+/**
+ * Creates Elysia plugin with routes from SSR config.
+ * Handles /_ssr/* routes for islands and dev tools using @elysiajs/static.
+ *
+ * @example
+ * ```ts
+ * import { Elysia } from "elysia";
+ * import { staticPlugin } from "@elysiajs/static";
+ * import { routes } from "@valentinkolb/ssr/elysia";
+ * import { config, html } from "./config";
+ *
+ * new Elysia()
+ *   .use(routes(config))
+ *   .use(staticPlugin({ assets: "./public", prefix: "/public" }))
+ *   .get("/", () => html(<Home />))
+ *   .listen(3000);
+ * ```
+ */
+export const routes = (config: SsrConfig) => {
+  const { dev, autoRefresh } = config;
+
+  const ssrDir = join(dev ? "." : Bun.main, "_ssr");
+
+  return (
+    new Elysia({ name: "ssr" })
+      // Serve island chunks
+      .use(
+        staticPlugin({
+          assets: ssrDir,
+          prefix: "/_ssr",
+          headers: {
+            "Cache-Control": dev
+              ? "no-cache"
+              : "public, max-age=31536000, immutable",
+          },
+        }),
+      )
+
+      // Dev mode: SSE endpoint for live reload
+      .get("/_ssr/_reload", () => {
+        if (!dev || !autoRefresh) {
+          return new Response("Not found", { status: 404 });
+        }
+
+        return new Response(
+          new ReadableStream({
+            start(controller) {
+              controller.enqueue(new TextEncoder().encode(": connected\n\n"));
+              const interval = setInterval(() => {
+                try {
+                  controller.enqueue(new TextEncoder().encode(": ping\n\n"));
+                } catch {
+                  clearInterval(interval);
+                }
+              }, 5000);
+            },
+          }),
+          {
+            headers: {
+              "Content-Type": "text/event-stream",
+              "Cache-Control": "no-cache",
+              Connection: "keep-alive",
+            },
+          },
+        );
+      })
+
+      // Dev mode: Ping endpoint for reconnection check
+      .get("/_ssr/_ping", () => {
+        if (!dev || !autoRefresh) {
+          return new Response("Not found", { status: 404 });
+        }
+        return new Response("ok");
+      })
+
+      // Dev mode: Serve reload client script
+      .get("/_ssr/_client.js", () => {
+        if (!dev || !autoRefresh) {
+          return new Response("Not found", { status: 404 });
+        }
+        return new Response(devClientCode, {
+          headers: {
+            "Content-Type": "application/javascript",
+            "Cache-Control": "no-cache",
+          },
+        });
+      })
+  );
+};

package/src/adapter/hono.ts

@@ -0,0 +1,102 @@
+import { Hono } from "hono";
+import { dirname, join } from "path";
+import type { SsrConfig } from "../index";
+// @ts-ignore - Bun text import
+import devClientCode from "./client.js" with { type: "text" };
+
+/**
+ * Creates Hono app with SSR routes.
+ * Handles /_ssr/* routes for islands and dev tools.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from "hono";
+ * import { serveStatic } from "hono/bun";
+ * import { routes } from "@valentinkolb/ssr/hono";
+ * import { config, html } from "./config";
+ *
+ * const app = new Hono()
+ *   .route("/_ssr", routes(config))
+ *   .use("/public/*", serveStatic({ root: "./" }))
+ *   .get("/", async (c) => {
+ *     const response = await html(<Home />);
+ *     return c.html(await response.text());
+ *   });
+ *
+ * export default app;
+ * ```
+ */
+export const routes = (config: SsrConfig) => {
+  const { dev, autoRefresh } = config;
+
+  const app = new Hono();
+
+  // Dev mode: Serve reload client script
+  app.get("/_client.js", (c) => {
+    if (!dev || !autoRefresh) {
+      return c.notFound();
+    }
+    return new Response(devClientCode, {
+      headers: {
+        "Content-Type": "application/javascript",
+        "Cache-Control": "no-cache",
+      },
+    });
+  });
+
+  // Dev mode: SSE endpoint for live reload
+  app.get("/_reload", (c) => {
+    if (!dev || !autoRefresh) {
+      return c.notFound();
+    }
+    return c.body(
+      new ReadableStream({
+        start(controller) {
+          controller.enqueue(new TextEncoder().encode(": connected\n\n"));
+          const interval = setInterval(() => {
+            try {
+              controller.enqueue(new TextEncoder().encode(": ping\n\n"));
+            } catch {
+              clearInterval(interval);
+            }
+          }, 5000);
+        },
+      }),
+      {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+      },
+    );
+  });
+
+  // Dev mode: Ping endpoint for reconnection check
+  app.get("/_ping", (c) => {
+    if (!dev || !autoRefresh) {
+      return c.notFound();
+    }
+    return c.text("ok");
+  });
+
+  // Serve all other files as island chunks (use :filename+ to capture filename with extension)
+  app.get("/:filename{.+\\.js$}", async (c) => {
+    const file = Bun.file(
+      join(dev ? "." : Bun.main, "_ssr", c.req.param("filename")),
+    );
+
+    if (!(await file.exists())) return c.notFound();
+
+    return c.body(await file.text(), {
+      headers: {
+        "Content-Type": file.type,
+        "Cache-Control": dev
+          ? "no-cache"
+          : "public, max-age=31536000, immutable",
+      },
+    });
+  });
+
+  return app;
+};

package/src/build.ts

@@ -0,0 +1,107 @@
+import { relative } from "path";
+import { Glob } from "bun";
+import { transform, hash } from "./transform";
+
+type ComponentType = "island" | "client";
+
+const getComponentType = (path: string): ComponentType =>
+  path.includes(".client.") ? "client" : "island";
+
+const getSelector = (type: ComponentType, id: string) =>
+  type === "island"
+    ? `solid-island[data-id="${id}"]`
+    : `solid-client[data-id="${id}"]`;
+
+export const buildIslands = async (options: {
+  pattern: string;
+  outdir: string;
+  verbose: boolean;
+  dev?: boolean;
+}): Promise<void> => {
+  const { pattern, outdir, verbose, dev = false } = options;
+
+  const files: string[] = [];
+
+  for await (const file of new Glob(pattern).scan({
+    cwd: process.cwd(),
+    absolute: true,
+  })) {
+    files.push(file);
+  }
+
+  if (!files.length) {
+    if (verbose) console.log("No island/client files found.");
+    return;
+  }
+
+  // Build component metadata
+  const components = files.map((componentPath) => {
+    const id = hash(componentPath);
+    const type = getComponentType(componentPath);
+    const selector = getSelector(type, id);
+    return { path: componentPath, id, type, selector };
+  });
+
+  // Build all islands together with code splitting
+  // This ensures Solid is only bundled once as a shared chunk
+  const result = await Bun.build({
+    entrypoints: components.map((c) => c.id),
+    outdir,
+    naming: { entry: "[name].js", chunk: "chunk-[hash].js" },
+    target: "browser",
+    minify: !dev,
+    splitting: true,
+    sourcemap: dev ? "inline" : "none",
+    plugins: [
+      {
+        name: "solid-islands",
+        setup(build) {
+          // Resolve component IDs as virtual entrypoints
+          build.onResolve({ filter: /^[a-f0-9]{8}$/ }, (args) => ({
+            path: args.path,
+            namespace: "island",
+          }));
+
+          // Generate hydration code for each component
+          build.onLoad({ filter: /.*/, namespace: "island" }, (args) => {
+            const component = components.find((c) => c.id === args.path);
+            if (!component) {
+              return { contents: "", loader: "js" };
+            }
+
+            return {
+              contents: `import{render,createComponent}from"solid-js/web";import{deserialize}from"seroval";import C from"${component.path}";document.querySelectorAll('${component.selector}').forEach(e=>{e.innerHTML="";render(()=>createComponent(C,deserialize(e.dataset.props||"{}")),e)})`,
+              loader: "js",
+            };
+          });
+
+          // Transform TSX/JSX with Solid DOM mode
+          build.onLoad({ filter: /\.(tsx|jsx)$/ }, async ({ path }) => {
+            // Import with ? suffix to register file with bun --watch
+            // Issue: https://github.com/oven-sh/bun/issues/4689
+            const contents = await import(`${path}?`, {
+              with: { type: "text" },
+            });
+            return {
+              contents: await transform(contents.default, path, "dom"),
+              loader: "js",
+            };
+          });
+        },
+      },
+    ],
+  });
+
+  if (verbose) {
+    for (const c of components) {
+      const rel = relative(process.cwd(), c.path);
+      console.log(`${rel} -> ${outdir}/${c.id}.js`);
+    }
+    console.log(`Built ${files.length} component(s) to ${outdir}/`);
+  }
+
+  if (!result.success) {
+    console.error("Build failed:");
+    result.logs.forEach((m) => console.error(`  ${m}`));
+  }
+};

package/src/index.ts

@@ -0,0 +1,198 @@
+import { renderToString } from "solid-js/web";
+import type { JSX } from "solid-js";
+import type { BunPlugin } from "bun";
+import { transform } from "./transform";
+import { buildIslands } from "./build";
+import { join, dirname } from "path";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Glob pattern for island/client component files */
+const COMPONENT_PATTERN = "**/*.{island,client}.tsx";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type SsrOptions<T extends object = object> = {
+  /** Enable dev mode (default: false) */
+  dev?: boolean;
+  /** Enable verbose logging (default: true in prod, false in dev) */
+  verbose?: boolean;
+  /** Enable auto page refresh in dev mode (default: true) */
+  autoRefresh?: boolean;
+  /** HTML template function (optional, has default) */
+  template?: (
+    ctx: {
+      body: string;
+      scripts: string;
+    } & T,
+  ) => string | Promise<string>;
+};
+
+export type SsrConfig = {
+  dev: boolean;
+  verbose?: boolean;
+  autoRefresh: boolean;
+};
+
+type HtmlFn<T extends object> = (
+  element: JSX.Element,
+  options?: T,
+) => Promise<Response>;
+
+type PluginFn = () => BunPlugin;
+
+export type SsrResult<T extends object> = {
+  config: SsrConfig;
+  plugin: PluginFn;
+  html: HtmlFn<T>;
+};
+
+// ============================================================================
+// createConfig() - Create SSR configuration
+// ============================================================================
+
+/**
+ * Creates SSR configuration, html renderer, and build plugin.
+ *
+ * Components follow naming conventions:
+ * - `*.island.tsx` - SSR rendered + hydrated on client (interactive)
+ * - `*.client.tsx` - Client-only rendered (not SSR)
+ *
+ * @example
+ * ```ts
+ * // config.ts
+ * import { createConfig } from "@valentinkolb/ssr";
+ *
+ * type PageOptions = { title?: string };
+ *
+ * export const { config, plugin, html } = createConfig<PageOptions>({
+ *   dev: process.env.NODE_ENV === "development",
+ *   template: ({ body, scripts, title }) => `
+ *     <!DOCTYPE html>
+ *     <html>
+ *       <head><title>${title ?? "App"}</title></head>
+ *       <body>${body}</body>
+ *       ${scripts}
+ *     </html>
+ *   `,
+ * });
+ * ```
+ */
+export const createConfig = <T extends object = object>(
+  options: SsrOptions<T> = {},
+): SsrResult<T> => {
+  const { dev = false, verbose, autoRefresh = true, template } = options;
+
+  // Default template if none provided
+  const htmlTemplate =
+    template ??
+    (({ body, scripts }) => `
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+      </head>
+      <body>
+        ${body}
+        ${scripts}
+      </body>
+    </html>
+  `);
+
+  // Config object for routes adapters
+  const config: SsrConfig = {
+    dev,
+    verbose,
+    autoRefresh,
+  };
+
+  // HTML renderer
+  const html: HtmlFn<T> = async (element, opts = {} as T) => {
+    const body = renderToString(() => element);
+
+    // Extract island and client component IDs from rendered HTML
+    const islandIds = [
+      ...new Set(
+        [...body.matchAll(/<solid-(island|client) data-id="([^"]+)"/g)].map(
+          (m) => m[2],
+        ),
+      ),
+    ];
+
+    // Component scripts
+    let scripts = islandIds
+      .map((id) => `<script type="module" src="/_ssr/${id}.js"></script>`)
+      .join("\n");
+
+    // Add dev reload script in dev mode (if autoRefresh enabled)
+    if (dev && autoRefresh) {
+      scripts += `\n<script type="module" src="/_ssr/_client.js"></script>`;
+    }
+
+    const content = await htmlTemplate({
+      body,
+      scripts,
+      ...opts,
+    });
+
+    return new Response(content, {
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  };
+
+  // Build islands once per run
+  let islandsBuilt = false;
+
+  // Bun plugin for build/dev
+  const plugin: PluginFn = () => {
+    return {
+      name: "solid-ssr",
+      setup(build) {
+        // Determine output directory
+        const prodOutdir = build.config?.outdir;
+        const islandsOutdir = prodOutdir ? join(prodOutdir, "_ssr") : "_ssr";
+
+        const ensureIslands = async () => {
+          if (islandsBuilt) return;
+          islandsBuilt = true;
+          await buildIslands({
+            pattern: COMPONENT_PATTERN,
+            outdir: islandsOutdir,
+            verbose: verbose ?? !dev,
+            dev,
+          });
+        };
+
+        // Build islands on start (works for Bun.build)
+        build.onStart?.(ensureIslands);
+
+        // Handle .island and .client imports (without .tsx extension)
+        build.onResolve({ filter: /\.(island|client)$/ }, (args) => ({
+          path: args.path.startsWith(".")
+            ? join(dirname(args.importer), args.path + ".tsx")
+            : args.path + ".tsx",
+        }));
+
+        // Transform TSX/JSX files with Solid SSR
+        build.onLoad({ filter: /\.(tsx|jsx)$/ }, async ({ path }) => {
+          // Fallback for Bun.plugin (has no onStart)
+          await ensureIslands();
+          // Import with ? suffix to register file with bun --watch
+          // Issue: https://github.com/oven-sh/bun/issues/4689
+          const contents = await import(`${path}?`, { with: { type: "text" } });
+          return {
+            contents: await transform(contents.default, path, "ssr"),
+            loader: "js",
+          };
+        });
+      },
+    };
+  };
+
+  return { config, plugin, html };
+};

package/src/transform.ts

@@ -0,0 +1,162 @@
+import { transformAsync, types as t } from "@babel/core";
+// @ts-ignore - no types are available for this package
+import solidPreset from "babel-preset-solid";
+// @ts-ignore - no types are available for this package
+import tsPreset from "@babel/preset-typescript";
+import { join, dirname } from "path";
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+export const hash = (s: string) =>
+  new Bun.CryptoHasher("md5").update(s).digest("hex").slice(0, 8);
+
+// JSX AST helpers
+const jsx = (tag: string, attrs: any[], children: any[] = []) =>
+  t.jsxElement(
+    t.jsxOpeningElement(t.jsxIdentifier(tag), attrs, children.length === 0),
+    children.length ? t.jsxClosingElement(t.jsxIdentifier(tag)) : null,
+    children,
+    children.length === 0,
+  );
+
+const attr = (name: string, value: any) =>
+  t.jsxAttribute(
+    t.jsxIdentifier(name),
+    typeof value === "string"
+      ? t.stringLiteral(value)
+      : t.jsxExpressionContainer(value),
+  );
+
+// ============================================================================
+// Babel Plugin - Wraps island/client components
+// ============================================================================
+
+type ComponentType = "island" | "client";
+
+const componentWrapperPlugin = (filename: string) => ({
+  visitor: {
+    Program(programPath: any) {
+      const componentImports = new Map<
+        string,
+        { path: string; type: ComponentType }
+      >();
+
+      // Inject seroval serialize helper at the top
+      programPath.node.body.unshift(
+        t.importDeclaration(
+          [
+            t.importSpecifier(
+              t.identifier("serialize"),
+              t.identifier("serialize"),
+            ),
+          ],
+          t.stringLiteral("seroval"),
+        ),
+        t.variableDeclaration("const", [
+          t.variableDeclarator(
+            t.identifier("__seroval_serialize"),
+            t.identifier("serialize"),
+          ),
+        ]),
+      );
+
+      programPath.traverse({
+        ImportDeclaration(path: any) {
+          const source: string = path.node.source.value;
+
+          let type: ComponentType | null = null;
+          if (source.includes(".island")) type = "island";
+          else if (source.includes(".client")) type = "client";
+          if (!type) return;
+
+          const spec = path.node.specifiers.find(
+            (s: any) => s.type === "ImportDefaultSpecifier",
+          );
+          if (!spec) return;
+
+          let absPath = source.startsWith(".")
+            ? join(dirname(filename), source)
+            : source;
+          if (!absPath.match(/\.(tsx|jsx|ts|js)$/)) absPath += ".tsx";
+
+          componentImports.set(spec.local.name, { path: absPath, type });
+        },
+
+        JSXElement(path: any) {
+          const name = path.node.openingElement.name.name;
+          const component = componentImports.get(name);
+          if (!component) return;
+
+          const id = hash(component.path);
+          const wrapperTag =
+            component.type === "island" ? "solid-island" : "solid-client";
+
+          const props = t.objectExpression(
+            path.node.openingElement.attributes
+              .filter((a: any) => a.type === "JSXAttribute")
+              .map((a: any) =>
+                t.objectProperty(
+                  t.identifier(a.name.name),
+                  a.value?.type === "JSXExpressionContainer"
+                    ? a.value.expression
+                    : a.value || t.booleanLiteral(true),
+                ),
+              ),
+          );
+
+          // For islands: wrap the component, for client: empty wrapper (no SSR)
+          const children = component.type === "island" ? [path.node] : [];
+
+          const wrapper = jsx(
+            wrapperTag,
+            [
+              attr("data-id", id),
+              attr(
+                "data-props",
+                t.callExpression(t.identifier("__seroval_serialize"), [props]),
+              ),
+            ],
+            children,
+          );
+
+          path.replaceWith(wrapper);
+          path.skip();
+        },
+      });
+    },
+  },
+});
+
+// ============================================================================
+// Transform function
+// ============================================================================
+
+export const transform = async (
+  source: string,
+  filename: string,
+  mode: "ssr" | "dom",
+): Promise<string> => {
+  let code = source;
+
+  if (mode === "ssr") {
+    const result = await transformAsync(code, {
+      filename,
+      parserOpts: { plugins: ["jsx", "typescript"] },
+      plugins: [() => componentWrapperPlugin(filename)],
+    });
+    code = result?.code || code;
+  }
+
+  const result = await transformAsync(code, {
+    filename,
+    presets: [
+      [tsPreset, {}],
+      [solidPreset, { generate: mode, hydratable: false }],
+    ],
+  });
+
+  if (!result?.code) throw new Error(`Transform failed: ${filename}`);
+  return result.code;
+};