@valentinkolb/ssr 0.6.2 → 0.7.3

package/README.md

@@ -1,171 +1,106 @@
-# @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.
+
+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. The entire codebase:
+This framework is intentionally minimal and focused on SSR + islands only.
 
-| 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 | — | — |
+Current source size in this repo (`packages/ssr-core/src`):
 
-**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)
+| 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 |
 
-Minimal framework overhead in the client bundle.
+Important: these sizes describe framework source code that runs at build time and on the server.
+The browser receives only:
 
-**What's not included** (by design):
-- No client-side routing
-- No state management
-- No CSS-in-JS
-- No build tool abstractions
+- your island bundles
+- Solid runtime from your app dependencies
+- `seroval` deserialize runtime
+- a tiny hydration import snippet
 
-Use the libraries you already know. This framework just handles SSR and islands hydration.
+Framework overhead in the browser is intentionally small.
 
-## Features
+What is intentionally not included:
 
-- **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
+- no client-side router
+- no state management layer
+- no CSS-in-JS abstraction
+- no build tool wrapper around Bun
 
-## Example
+Use the libraries you already prefer. This package only handles SSR and islands hydration.
 
-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.
+## Features
 
-## Installation
+- 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`
+- Stable file-path-based island IDs (collision-safe across workspace packages)
+- Production chunk cache busting (`/_ssr/*.js?v=<buildTimestamp>`)
 
-Core dependencies (always required):
+## Install
 
 ```bash
 bun add @valentinkolb/ssr solid-js
 bun add -d @babel/core @babel/preset-typescript babel-preset-solid
-```
-
-Plus one adapter depending on your framework:
 
-```bash
-# Bun native - no extra dependencies
-
-# 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.
-
-## 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:
+## Required TypeScript settings
 
-```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
+## Quick Start (Hono)
 
-### Bun Native Server
+### 1) Create config
 
-```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
-
-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.
-
-```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",
   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 +113,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,65 +143,55 @@ 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:
+### 6) Run
 
-```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} />;
-  }
-);
+```bash
+NODE_ENV=development bun --watch --preload=./scripts/preload.ts src/server.ts
 ```
 
-### Elysia
+## Adapter imports
 
-```typescript
-import { Elysia } from "elysia";
-import { routes } from "@valentinkolb/ssr/adapter/elysia";
-import { config, html } from "./config";
-import Home from "./pages/Home";
+- Bun: `@valentinkolb/ssr/bun`
+- Hono: `@valentinkolb/ssr/hono`
+- Elysia: `@valentinkolb/ssr/elysia`
+
+## `createConfig` options
 
-new Elysia()
-  .use(routes(config))
-  .get("/", () => html(<Home />))
-  .listen(3000);
+```ts
+createConfig({
+  dev?: boolean;         // default: false
+  verbose?: boolean;     // default: !dev
+  rootDir?: string;      // default: process.cwd()
+  external?: string[];   // passed to Bun.build for island bundle
+  template?: ({ body, scripts, ...custom }) => string | Promise<string>;
+})
 ```
 
-## Build Configuration
+### Notes
+
+- `rootDir` is important in monorepos where server entrypoint and island files live in different packages.
+- In production, hydration imports include a build timestamp query (`?v=...`) for cache busting.
 
-Add the plugin to your build script:
+## Build for production
 
-```typescript
+```ts
 // scripts/build.ts
 import { plugin } from "./config";
 
@@ -257,203 +203,38 @@ await Bun.build({
 });
 ```
 
-For development with watch mode:
+## Hono `createSSRHandler` behavior
 
-```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`)
+`createSSRHandler(html)` returns an `ssr()` helper that:
 
-Client-only components are not rendered on the server. They render only in the browser, useful for components that depend on browser APIs.
+- initializes `c.get("page")` as typed page options
+- accepts middlewares/validators before final handler
+- lets handlers return either JSX or `Response`
 
-```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>;
-}
-```
+## Dev mode tools
 
-### Regular Components
+With `dev: true`, a small `[ssr]` overlay is injected.
 
-Standard Solid components that are only rendered on the server. No client-side JavaScript is shipped for these.
+It can:
 
-```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}
-/>
-```
+- auto-reload on server restart
+- highlight island/client boundaries
+- show source filenames for wrapped components
 
-## 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
-└── 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)
-})
-```
-
-## Dev Tools
-
-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:
-
-- 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.6.2",
+  "version": "0.7.3",
   "description": "Minimal SSR framework for SolidJS and Bun",
   "type": "module",
   "main": "src/index.ts",

package/src/adapter/bun.ts

@@ -30,7 +30,7 @@ type Routes = Record<string, RouteHandler>;
  */
 export const routes = (config: SsrConfig): Routes => {
   const { dev } = config;
-  const ssrDir = getSsrDir(dev);
+  const ssrDir = getSsrDir(config);
 
   const devRoutes: Routes = dev
     ? {

package/src/adapter/elysia.ts

@@ -26,7 +26,7 @@ import {
  */
 export const routes = (config: SsrConfig) => {
   const { dev } = config;
-  const ssrDir = getSsrDir(dev);
+  const ssrDir = getSsrDir(config);
 
   return new Elysia({ name: "ssr" })
     .use(

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,15 @@
  * SSE stream for hot reload, and security utilities.
  */
 import { dirname, join, resolve } from "path";
+import type { SsrConfig } from "../index";
 
 /**
  * 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";
 
@@ -18,10 +19,13 @@ const fmt = (ms: number) => (ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${Math
 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 } = options;
+  const { pattern, outdir, cwd, verbose, dev = false, external } = options;
+  const resolvedCwd = resolve(cwd);
 
   const totalStart = performance.now();
 
@@ -29,7 +33,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);
@@ -43,29 +47,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
@@ -77,6 +83,7 @@ export const buildIslands = async (options: {
     outdir,
     naming: { entry: "[name].js", chunk: "chunk-[hash].js" },
     target: "browser",
+    external,
     minify: !dev,
     splitting: true,
     sourcemap: dev ? "inline" : "none",
@@ -85,7 +92,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",
           }));
@@ -171,7 +178,7 @@ export const buildIslands = async (options: {
   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,11 @@
 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";
 // @ts-ignore - Bun text import
 import devClientCode from "./adapter/client.js" with { type: "text" };
 
@@ -20,6 +22,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 +44,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;
+  /** Modules to exclude from the island bundle (passed to Bun.build) */
+  external?: string[];
   /** HTML template function (optional, has default) */
   template?: (
     ctx: {
@@ -41,6 +60,7 @@ export type SsrOptions<T extends object = object> = {
 export type SsrConfig = {
   dev: boolean;
   verbose?: boolean;
+  rootDir?: string;
 };
 
 export type HtmlFn<T extends object> = (element: JSX.Element, options?: T) => Promise<Response>;
@@ -85,7 +105,8 @@ export type SsrResult<T extends object> = {
  * ```
  */
 export const createConfig = <T extends object = object>(options: SsrOptions<T> = {}): SsrResult<T> => {
-  const { dev = false, verbose, template } = options;
+  const { dev = false, verbose, external, template, rootDir: rootDirOption } = options;
+  const rootDir = resolve(rootDirOption ?? process.cwd());
 
   // Default template if none provided
   const htmlTemplate =
@@ -108,10 +129,13 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
   const config: SsrConfig = {
     dev,
     verbose,
+    rootDir,
   };
 
+  const buildVersion = getBuildVersion(dev);
+
   // 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 v=${JSON.stringify(buildVersion)};document.querySelectorAll('solid-island,solid-client').forEach(e=>import('/_ssr/'+e.dataset.id+'.js'+(v?'?v='+v:'')));</script>`;
 
   // HTML renderer
   const html: HtmlFn<T> = async (element, opts = {} as T) => {
@@ -146,7 +170,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;
@@ -154,8 +178,10 @@ export const createConfig = <T extends object = object>(options: SsrOptions<T> =
           await buildIslands({
             pattern: COMPONENT_PATTERN,
             outdir: islandsOutdir,
+            cwd: rootDir,
             verbose: verbose ?? !dev,
             dev,
+            external,
           });
         };
 
@@ -163,9 +189,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 }) => {
@@ -175,7 +204,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;
   }