@valentinkolb/ssr 0.7.0 → 0.8.0

package/README.md

@@ -1,171 +1,108 @@
-# @valentinkolb/SSR
+# @valentinkolb/ssr
 
-A minimal server-side rendering framework for SolidJS and Bun with islands architecture.
+Minimal SSR + islands framework for SolidJS on Bun.
 
 ## 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.
+This library renders Solid components on the server and hydrates only interactive islands on the client.
 
-## Size & Philosophy
+It uses file conventions:
 
-This framework is intentionally minimal. The entire codebase:
+- `*.island.tsx`: SSR + hydrated on the client
+- `*.client.tsx`: client-only (no SSR HTML content)
+- `*.tsx`: server-only output
 
-| Component | Lines | Raw | Gzipped |
-|-----------|-------|-----|---------|
-| Core (index, transform, build) | ~490 | 15 KB | 4.7 KB |
-| Client hydration (dev only) | ~200 | 6 KB | 2 KB |
-| Adapters | ~50 each | — | — |
+## Size & Philosophy
 
-**Important:** These sizes reflect the framework source code, which runs at build-time and on the server only. The browser receives:
-- Your island components
-- SolidJS runtime (~7 KB gzipped)
-- seroval's `deserialize` function (~2 KB gzipped)
-- A tiny hydration snippet (~150 bytes per island)
+This framework is intentionally minimal and focused on SSR + islands only.
 
-Minimal framework overhead in the client bundle.
+Current source size in this repo (`packages/ssr-core/src`):
 
-**What's not included** (by design):
-- No client-side routing
-- No state management
-- No CSS-in-JS
-- No build tool abstractions
+| Component | Lines | Raw | Gzipped |
+| --- | ---: | ---: | ---: |
+| Core (`index`, `transform`, `build`, island ID + resolver) | ~689 | 23.8 KB | 7.2 KB |
+| Dev client (overlay + reload, dev only) | ~211 | 6.1 KB | 2.0 KB |
+| Adapters (`bun`, `hono`, `elysia`, shared utils) | ~355 | 10.4 KB | 3.3 KB |
 
-Use the libraries you already know. This framework just handles SSR and islands hydration.
+Important: these sizes describe framework source code that runs at build time and on the server.
+The browser receives only:
 
-## Features
+- your island bundles
+- Solid runtime from your app dependencies
+- `seroval` deserialize runtime
+- a tiny hydration import snippet
 
-- **Islands architecture**: `*.island.tsx` for hydrated components, `*.client.tsx` for client-only
-- **Framework agnostic**: Works with Bun's native server, **Elysia**, or **Hono** (easy to [write your own adapter](#writing-your-own-adapter))
-- **Fast**: Built on Bun's runtime with optimized bundling
-- **Dev experience**: Hot reload, source maps, and TypeScript support
+Framework overhead in the browser is intentionally small.
 
-## Example
+What is intentionally not included:
 
-See [github.com/valentinkolb/ssr-example](https://github.com/valentinkolb/ssr-example) for a complete working example with all three adapters, including Tailwind CSS integration.
+- no client-side router
+- no state management layer
+- no CSS-in-JS abstraction
+- no build tool wrapper around Bun
 
-## Installation
+Use the libraries you already prefer. This package only handles SSR and islands hydration.
 
-Core dependencies (always required):
+## Features
 
-```bash
-bun add @valentinkolb/ssr solid-js
-bun add -d @babel/core @babel/preset-typescript babel-preset-solid
-```
+- Small SSR core with Bun-native build/plugin flow
+- 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>`)
 
-Plus one adapter depending on your framework:
+## Install
 
 ```bash
-# Bun native - no extra dependencies
+bun add @valentinkolb/ssr solid-js
 
-# Hono
+# choose adapter deps you need
 bun add hono
-
-# Elysia
+# or
 bun add elysia @elysiajs/static
 ```
 
-> **Note:** Dependencies like `solid-js`, `hono`, and `elysia` are peer dependencies. This lets you control the exact versions in your project and avoids version conflicts.
+## Required TypeScript settings
 
-## Quick Start
-
-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>
-  );
+```json
+{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "jsx": "preserve",
+    "jsxImportSource": "solid-js",
+    "moduleResolution": "bundler"
+  }
 }
 ```
 
-## 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;
-```
-
-#### Hono SSR Helper
+## Quick Start (Hono)
 
-The Hono adapter also exports `createSSRHandler`, a factory that creates a type-safe `ssr()` helper for page components. This eliminates boilerplate and integrates with Hono's middleware/validator system.
+### 1) Create config
 
-```typescript
+```ts
 // config.ts
 import { createConfig } from "@valentinkolb/ssr";
-import { createSSRHandler, routes } from "@valentinkolb/ssr/adapter/hono";
+import { createSSRHandler, routes } from "@valentinkolb/ssr/hono";
 
-type PageOptions = { title?: string; description?: string };
+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>
+    <!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>
@@ -178,7 +115,28 @@ export const ssr = createSSRHandler(html);
 export { routes };
 ```
 
-Pages become async handler functions with access to the Hono context:
+### 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
@@ -187,273 +145,121 @@ import Counter from "../components/Counter.island";
 
 export default ssr(async (c) => {
   c.get("page").title = "Home";
-
-  return (
-    <div>
-      <h1>Welcome</h1>
-      <Counter start={5} />
-    </div>
-  );
+  return <Counter initial={5} />;
 });
 ```
 
-```typescript
+### 5) Wire server
+
+```ts
 // server.ts
 import { Hono } from "hono";
 import { config, routes } from "./config";
 import Home from "./pages/Home";
 
-const app = new Hono()
+export default new Hono()
   .route("/_ssr", routes(config))
   .get("/", ...Home);
-
-export default app;
-```
-
-The `ssr()` helper also supports Hono middlewares and validators as leading arguments:
-
-```tsx
-import { ssr } from "../config";
-import { zValidator } from "@hono/zod-validator";
-import { z } from "zod";
-
-export default ssr(
-  zValidator("param", z.object({ id: z.string() })),
-  async (c) => {
-    const { id } = c.req.valid("param");
-    c.get("page").title = `Item ${id}`;
-    return <ItemView id={id} />;
-  }
-);
-```
-
-### 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";
+### 6) Run
 
-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"
-  }
-}
+```bash
+NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
 ```
 
-## Component Types
-
-### Island Components (`*.island.tsx`)
+## Adapter imports
 
-Island components are server-rendered and then hydrated on the client. They should be used for interactive UI elements that need JavaScript.
+- Bun: `@valentinkolb/ssr/bun`
+- Hono: `@valentinkolb/ssr/hono`
+- Elysia: `@valentinkolb/ssr/elysia`
 
-```tsx
-// Sidebar.island.tsx
-import { createSignal } from "solid-js";
+## `createConfig` options
 
-export default function Sidebar() {
-  const [open, setOpen] = createSignal(false);
-  return <div>{open() ? "Open" : "Closed"}</div>;
-}
+```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
+  template?: ({ body, scripts, ...custom }) => string | Promise<string>;
+})
 ```
 
-### 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.
+### Notes
 
-```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>;
-}
-```
+- `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.
 
-### Regular Components
+## Microfrontend mount example
 
-Standard Solid components that are only rendered on the server. No client-side JavaScript is shipped for these.
+Use `basePath` when the SSR app is mounted under a sub-path:
 
-```tsx
-// Header.tsx
-export default function Header() {
-  return <header><h1>My Site</h1></header>;
-}
-```
-
-## Props Serialization
+```ts
+// config.ts
+export const { config, html } = createConfig({
+  basePath: "/docs",
+});
 
-The framework uses [seroval](https://github.com/lxsmnsyc/seroval) for props serialization, which supports complex JavaScript types that JSON cannot handle:
+// docs-app.ts
+const docsApp = new Hono()
+  .route("/_ssr", routes(config))
+  .get("/", () => html(<DocsHome />));
 
-```tsx
-<Island
-  date={new Date()}
-  map={new Map([["key", "value"]])}
-  set={new Set([1, 2, 3])}
-  regex={/test/gi}
-  bigint={123n}
-  undefined={undefined}
-/>
+// host-app.ts
+export default new Hono().route("/docs", docsApp);
 ```
 
-## Custom HTML Template
+With this setup, hydration chunks and dev endpoints are served from `/docs/_ssr/...`.
 
-You can pass additional options to your HTML template. All options are type safe!
+## Build for production
 
-```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>
-  `,
-});
+```ts
+// scripts/build.ts
+import { plugin } from "./config";
 
-// Usage
-await html(<Home />, { 
-  title: "Home Page",               // type safe
-  description: "Welcome to my site" // type safe
+await Bun.build({
+  entrypoints: ["src/server.tsx"],
+  outdir: "dist",
+  target: "bun",
+  plugins: [plugin()],
 });
 ```
 
-## How It Works
+## Hono `createSSRHandler` behavior
 
-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
+`createSSRHandler(html)` returns an `ssr()` helper that:
 
-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.
+- initializes `c.get("page")` as typed page options
+- accepts middlewares/validators before final handler
+- lets handlers return either JSX or `Response`
 
-Babel is used since Solid only supports Babel for JSX transformation at the moment.
+## Dev mode tools
 
-## File Structure
-
-```
-src/
-├── index.ts           # Core SSR logic and createConfig()
-├── transform.ts       # Babel plugin for island wrapping
-├── build.ts           # Island bundling with code splitting
-└── adapter/
-    ├── bun.ts         # Bun.serve() adapter
-    ├── elysia.ts      # Elysia adapter
-    ├── hono.ts        # Hono adapter
-    ├── client.js      # Dev mode client (reload + dev tools)
-    └── utils.ts       # Shared adapter utilities
-```
-
-## Configuration Options
-
-```typescript
-createConfig({
-  dev?: boolean;                // Enable dev mode (default: false)
-  verbose?: boolean;            // Enable verbose logging (default: !dev)
-  template?: (context) => string; // HTML template function (optional, has default)
-})
-```
+With `dev: true`, a small `[ssr]` overlay is injected.
 
-## Dev Tools
+It can:
 
-In dev mode, a small `[ssr]` badge appears in the corner of the page. Click it to open the dev tools panel where you can:
+- auto-reload on server restart
+- highlight island/client boundaries
+- show source filenames for wrapped components
 
-- Toggle auto-reload on/off
-- Highlight island components (green border)
-- Highlight client components (blue border)
-- Move the panel to any corner
-
-Settings are persisted in localStorage.
-
-## Writing Your Own Adapter
+## Limitations
 
-Adapters just need to serve files from the `_ssr` directory. See `src/adapter/utils.ts` for shared helpers:
+- islands must use default export
+- props must be serializable (via `seroval`)
+- nested island/client imports are not supported
 
-- `getSsrDir(dev)` - Returns path to `_ssr` folder
-- `getCacheHeaders(dev)` - Cache headers (immutable in prod, no-cache in dev)
-- `createReloadResponse()` - SSE stream for hot reload
-- `safePath(base, filename)` - Prevents path traversal attacks
+## Local monorepo example
 
-Check the existing adapters (~30 lines each) for reference.
+This repo includes a current example app:
 
-## TypeScript Config
+- `packages/ssr-example`
 
-Required tsconfig.json settings for SolidJS:
+Run from workspace root:
 
-```json
-{
-  "compilerOptions": {
-    "lib": ["ESNext", "DOM"],
-    "jsx": "preserve",
-    "jsxImportSource": "solid-js",
-    "moduleResolution": "bundler"
-  }
-}
+```bash
+bun run dev:example
 ```
-
-See the [example project](https://github.com/valentinkolb/ssr-example) for a full recommended config.
-
-## Limitations
-
-- **Islands must have default export**: `export default function MyIsland() {}`
-- **Props must be serializable**: seroval supports Date, Map, Set, RegExp, BigInt, but not functions or class instances
-- **No shared state between islands**: Each island hydrates independently. Use URL params, localStorage, or a global store for cross-island communication
-- **No nested islands/clients**: An island cannot import another island or client component. This is not needed anyway - once a component is an island, its entire subtree is hydrated. Just use regular components inside islands.
-
-## Contributing
-
-Contributions are welcome! The codebase is intentionally minimal. Keep changes focused and avoid adding unnecessary complexity.
-
-## License
-
-MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/ssr",
-  "version": "0.7.0",
+  "version": "0.8.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

@@ -29,20 +29,20 @@ type Routes = Record<string, RouteHandler>;
  * ```
  */
 export const routes = (config: SsrConfig): Routes => {
-  const { dev } = config;
-  const ssrDir = getSsrDir(dev);
+  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

@@ -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

@@ -25,17 +25,17 @@ import {
  * ```
  */
 export const routes = (config: SsrConfig) => {
-  const { dev } = config;
-  const ssrDir = getSsrDir(dev);
+  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

@@ -160,7 +160,7 @@ export const createSSRHandler = <T extends object>(html: HtmlFn<T>) => {
  */
 export const routes = (config: SsrConfig) => {
   const { dev } = config;
-  const ssrDir = getSsrDir(dev);
+  const ssrDir = getSsrDir(config);
 
   const app = new Hono();
 

package/src/adapter/utils.ts

@@ -3,14 +3,36 @@
  * SSE stream for hot reload, and security utilities.
  */
 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 process.cwd() (project root)
+ * Dev: uses config.rootDir (fallback process.cwd())
  * Prod: uses dirname(Bun.main) (next to compiled binary)
  */
-export const getSsrDir = (dev: boolean): string =>
-  join(dev ? process.cwd() : dirname(Bun.main), "_ssr");
+export const getSsrDir = (config: SsrConfig): string =>
+  join(config.dev ? config.rootDir ?? process.cwd() : dirname(Bun.main), "_ssr");
 
 /**
  * Cache headers for static assets

package/src/build.ts

@@ -2,9 +2,10 @@
  * Island bundler - discovers *.island.tsx and *.client.tsx files,
  * transforms them for the browser, and outputs chunks to _ssr directory.
  */
-import { relative } from "path";
+import { relative, resolve } from "path";
 import { Glob } from "bun";
-import { transform, hash } from "./transform";
+import { transform } from "./transform";
+import { ISLAND_ID_LENGTH, islandIdFromFile, toStableKey } from "./island-id";
 
 type ComponentType = "island" | "client";
 
@@ -15,14 +16,67 @@ 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;
+  cwd: string;
   verbose: boolean;
   dev?: boolean;
   external?: string[];
 }): Promise<void> => {
-  const { pattern, outdir, verbose, dev = false, external } = options;
+  const { pattern, outdir, cwd, verbose, dev = false, external } = options;
+  const resolvedCwd = resolve(cwd);
 
   const totalStart = performance.now();
 
@@ -30,7 +84,7 @@ export const buildIslands = async (options: {
 
   const scanStart = performance.now();
   for await (const file of new Glob(pattern).scan({
-    cwd: process.cwd(),
+    cwd: resolvedCwd,
     absolute: true,
   })) {
     files.push(file);
@@ -44,29 +98,31 @@ export const buildIslands = async (options: {
 
   // Build component metadata
   const components = files.map((componentPath) => {
-    const id = hash(componentPath);
+    const id = islandIdFromFile(componentPath, resolvedCwd);
+    const key = toStableKey(componentPath, resolvedCwd);
     const type = getComponentType(componentPath);
     const selector = getSelector(type, id);
-    return { path: componentPath, id, type, selector };
+    return { path: componentPath, id, key, type, selector };
   });
 
-  // Check for duplicate filenames (same filename -> same hash -> collision)
-  const filenameMap = new Map<string, string[]>();
+  // Detect hash collisions and fail fast with actionable diagnostics
+  const idMap = new Map<string, typeof components>();
   for (const c of components) {
-    const filename = c.path.split("/").pop()!;
-    if (!filenameMap.has(filename)) {
-      filenameMap.set(filename, []);
+    if (!idMap.has(c.id)) {
+      idMap.set(c.id, []);
     }
-    filenameMap.get(filename)!.push(c.path);
+    idMap.get(c.id)!.push(c);
   }
 
-  for (const [filename, paths] of filenameMap) {
-    if (paths.length > 1) {
-      console.warn(`[ssr] Warning: Multiple files with the same name detected: ${filename}`);
-      console.warn("  Files:");
-      paths.forEach((p) => console.warn(`    - ${relative(process.cwd(), p)}`));
-      console.warn("  This will cause hash collisions. Consider renaming these files.");
-    }
+  const collisions = [...idMap.entries()].filter(([, items]) => items.length > 1);
+  if (collisions.length > 0) {
+    const details = collisions
+      .map(([id, items]) => {
+        const list = items.map((item) => `    - ${item.key} (${relative(resolvedCwd, item.path)})`).join("\n");
+        return `  ID ${id}:\n${list}`;
+      })
+      .join("\n");
+    throw new Error(`[ssr] Island ID collision detected. Rename files or adjust roots.\n${details}`);
   }
 
   // Build all islands together with code splitting
@@ -87,7 +143,7 @@ export const buildIslands = async (options: {
         name: "solid-islands",
         setup(build) {
           // Resolve component IDs as virtual entrypoints
-          build.onResolve({ filter: /^[a-f0-9]{8}$/ }, (args) => ({
+          build.onResolve({ filter: new RegExp(`^[a-f0-9]{${ISLAND_ID_LENGTH}}$`) }, (args) => ({
             path: args.path,
             namespace: "island",
           }));
@@ -125,55 +181,16 @@ 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) {
     console.log(`Bundle: ${fmt(performance.now() - bundleStart)}`);
     for (const c of components) {
-      const rel = relative(process.cwd(), c.path);
+      const rel = relative(resolvedCwd, c.path);
       const t = transformTimings?.get(c.path);
       console.log(`  ${rel} -> ${outdir}/${c.id}.js${t != null ? ` (transform: ${fmt(t)})` : ""}`);
     }

package/src/index.ts

@@ -7,9 +7,12 @@
 import { renderToString } from "solid-js/web";
 import type { JSX } from "solid-js";
 import type { BunPlugin } from "bun";
+import { statSync } from "fs";
 import { transform } from "./transform";
 import { buildIslands } from "./build";
-import { join, dirname } from "path";
+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" };
 
@@ -20,6 +23,19 @@ import devClientCode from "./adapter/client.js" with { type: "text" };
 /** Glob pattern for island/client component files */
 const COMPONENT_PATTERN = "**/*.{island,client}.tsx";
 
+/**
+ * Build version used for cache busting island script imports in production.
+ * Uses server entrypoint mtime as a stable per-build version value.
+ */
+const getBuildVersion = (dev: boolean): string => {
+  if (dev) return "";
+  try {
+    return String(Math.floor(statSync(Bun.main).mtimeMs));
+  } catch {
+    return String(Date.now());
+  }
+};
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -29,6 +45,10 @@ export type SsrOptions<T extends object = object> = {
   dev?: boolean;
   /** Enable verbose logging (default: true in prod, false in dev) */
   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) */
@@ -43,6 +63,9 @@ export type SsrOptions<T extends object = object> = {
 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>;
@@ -87,7 +110,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 } = 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 =
@@ -110,21 +136,30 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
   const config: SsrConfig = {
     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">document.querySelectorAll('solid-island,solid-client').forEach(e=>import('/_ssr/'+e.dataset.id+'.js'));</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);
 
-    // 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({
@@ -148,7 +183,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
       setup(build) {
         // Determine output directory
         const prodOutdir = build.config?.outdir;
-        const islandsOutdir = prodOutdir ? join(prodOutdir, "_ssr") : "_ssr";
+        const islandsOutdir = prodOutdir ? join(prodOutdir, "_ssr") : join(rootDir, "_ssr");
 
         const ensureIslands = async () => {
           if (islandsBuilt) return;
@@ -156,6 +191,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
           await buildIslands({
             pattern: COMPONENT_PATTERN,
             outdir: islandsOutdir,
+            cwd: rootDir,
             verbose: verbose ?? !dev,
             dev,
             external,
@@ -166,9 +202,12 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
         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",
-        }));
+        build.onResolve({ filter: /\.(island|client)$/ }, (args) => {
+          const resolveDir = args.resolveDir || (args.importer ? dirname(args.importer) : rootDir);
+          return {
+            path: resolveIslandImport(args.path, resolveDir, args.importer || undefined),
+          };
+        });
 
         // Transform TSX/JSX files with Solid SSR
         build.onLoad({ filter: /\.(tsx|jsx)$/ }, async ({ path }) => {
@@ -178,7 +217,7 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
           // 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", dev),
+            contents: await transform(contents.default, path, "ssr", dev, rootDir),
             loader: "js",
           };
         });

package/src/island-id.ts

@@ -0,0 +1,78 @@
+/**
+ * Stable island ID generation based on canonical file paths.
+ * IDs are deterministic for file-based imports and robust in monorepos.
+ */
+import { realpathSync } from "fs";
+import { isAbsolute, relative, resolve } from "path";
+
+/** Length of hashed island IDs used in data-id and generated chunk filenames */
+export const ISLAND_ID_LENGTH = 12;
+
+const canonicalFileCache = new Map<string, string>();
+const canonicalRootCache = new Map<string, string>();
+
+const toPosixPath = (value: string): string => value.replace(/\\/g, "/");
+
+/**
+ * Short deterministic hash helper used for island IDs.
+ */
+export const hash = (value: string): string =>
+  new Bun.CryptoHasher("md5").update(value).digest("hex").slice(0, ISLAND_ID_LENGTH);
+
+/**
+ * Canonicalize file path for stable hashing.
+ * Falls back to resolve() when realpath cannot be resolved.
+ */
+export const canonicalFilePath = (file: string): string => {
+  const absolutePath = resolve(file);
+  const cached = canonicalFileCache.get(absolutePath);
+  if (cached) return cached;
+
+  let canonical = absolutePath;
+  try {
+    canonical = realpathSync(absolutePath);
+  } catch {
+    // Keep resolved absolute path when the file does not exist yet.
+  }
+
+  const normalized = toPosixPath(canonical);
+  canonicalFileCache.set(absolutePath, normalized);
+  return normalized;
+};
+
+const canonicalRootPath = (rootDir: string): string => {
+  const absolutePath = resolve(rootDir);
+  const cached = canonicalRootCache.get(absolutePath);
+  if (cached) return cached;
+
+  let canonical = absolutePath;
+  try {
+    canonical = realpathSync(absolutePath);
+  } catch {
+    // Keep resolved absolute path when the directory does not exist yet.
+  }
+
+  const normalized = toPosixPath(canonical);
+  canonicalRootCache.set(absolutePath, normalized);
+  return normalized;
+};
+
+/**
+ * Convert file path to a stable key:
+ * - relative to rootDir when inside rootDir
+ * - otherwise canonical absolute path
+ */
+export const toStableKey = (file: string, rootDir: string): string => {
+  const canonicalFile = canonicalFilePath(file);
+  const root = canonicalRootPath(rootDir);
+  const rel = toPosixPath(relative(root, canonicalFile));
+  const isWithinRoot = !isAbsolute(rel) && rel !== ".." && !rel.startsWith("../");
+
+  return isWithinRoot ? rel : canonicalFile;
+};
+
+/**
+ * Build final stable island ID from canonical path key.
+ */
+export const islandIdFromFile = (file: string, rootDir: string): string =>
+  hash(toStableKey(file, rootDir));

package/src/island-resolve.ts

@@ -0,0 +1,39 @@
+import { dirname, isAbsolute, resolve } from "path";
+
+const hasScriptExtension = (value: string): boolean => /\.(tsx|jsx|ts|js)$/.test(value);
+
+export const withDefaultIslandExtension = (specifier: string): string =>
+  hasScriptExtension(specifier) ? specifier : `${specifier}.tsx`;
+
+const formatResolveError = (specifier: string, resolveDir: string, importer?: string, reason?: string): Error => {
+  const importerHint = importer ? ` from "${importer}"` : "";
+  const detail = reason ? `\nReason: ${reason}` : "";
+  return new Error(
+    `[ssr] Failed to resolve island/client import "${specifier}"${importerHint} using resolveDir "${resolveDir}".` +
+      `\nCheck your tsconfig paths/baseUrl (for aliases) or use a relative/absolute file import.${detail}`,
+  );
+};
+
+export const resolveIslandImport = (specifier: string, resolveDir: string, importer?: string): string => {
+  const normalizedSpecifier = withDefaultIslandExtension(specifier);
+  const normalizedResolveDir = resolveDir || (importer ? dirname(importer) : process.cwd());
+
+  if (specifier.startsWith(".")) {
+    return resolve(normalizedResolveDir, normalizedSpecifier);
+  }
+
+  if (isAbsolute(specifier)) {
+    return resolve(normalizedSpecifier);
+  }
+
+  try {
+    const resolved = Bun.resolveSync(normalizedSpecifier, normalizedResolveDir);
+    if (!isAbsolute(resolved)) {
+      throw formatResolveError(specifier, normalizedResolveDir, importer, `resolved to non-absolute path "${resolved}"`);
+    }
+    return resolved;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw formatResolveError(specifier, normalizedResolveDir, importer, reason);
+  }
+};

package/src/transform.ts

@@ -7,18 +7,16 @@ import { transformAsync, types as t } from "@babel/core";
 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";
+import { dirname } from "path";
+import { islandIdFromFile } from "./island-id";
+import { resolveIslandImport } from "./island-resolve";
+
+export { hash } from "./island-id";
 
 // ============================================================================
 // Helpers
 // ============================================================================
 
-export const hash = (s: string) => {
-  // Extract filename from path to ensure consistent hashing regardless of import aliases
-  const filename = s.split("/").pop() || s;
-  return new Bun.CryptoHasher("md5").update(filename).digest("hex").slice(0, 8);
-};
-
 // JSX AST helpers
 const jsx = (tag: string, attrs: any[], children: any[] = []) =>
   t.jsxElement(
@@ -43,13 +41,13 @@ type ComponentType = "island" | "client";
 const getComponentType = (path: string): ComponentType | null =>
   path.includes(".island") ? "island" : path.includes(".client") ? "client" : null;
 
-const componentWrapperPlugin = (filename: string, dev: boolean) => {
+const componentWrapperPlugin = (filename: string, rootDir: string, dev: boolean) => {
   const parentType = getComponentType(filename);
 
   return {
     visitor: {
       Program(programPath: any) {
-        const componentImports = new Map<string, { path: string; type: ComponentType }>();
+        const componentImports = new Map<string, { path: string; type: ComponentType; id: string }>();
 
         // Inject seroval serialize helper at the top
         programPath.node.body.unshift(
@@ -77,10 +75,11 @@ const componentWrapperPlugin = (filename: string, dev: boolean) => {
             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";
+            const resolvedPath = resolveIslandImport(source, dirname(filename), filename);
+            const componentPath = resolvedPath;
+            const id = islandIdFromFile(resolvedPath, rootDir);
 
-            componentImports.set(spec.local.name, { path: absPath, type });
+            componentImports.set(spec.local.name, { path: componentPath, type, id });
           },
 
           JSXElement(path: any) {
@@ -88,7 +87,6 @@ const componentWrapperPlugin = (filename: string, dev: boolean) => {
             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(
@@ -109,7 +107,7 @@ const componentWrapperPlugin = (filename: string, dev: boolean) => {
             const file = component.path.split("/").pop() || "";
 
             const attrs = [
-              attr("data-id", id),
+              attr("data-id", component.id),
               attr("data-props", t.callExpression(t.identifier("__seroval_serialize"), [props])),
             ];
 
@@ -138,6 +136,7 @@ export const transform = async (
   filename: string,
   mode: "ssr" | "dom",
   dev: boolean = false,
+  rootDir: string = process.cwd(),
 ): Promise<string> => {
   let code = source;
 
@@ -145,7 +144,7 @@ export const transform = async (
     const result = await transformAsync(code, {
       filename,
       parserOpts: { plugins: ["jsx", "typescript"] },
-      plugins: [() => componentWrapperPlugin(filename, dev)],
+      plugins: [() => componentWrapperPlugin(filename, rootDir, dev)],
     });
     code = result?.code || code;
   }