@voltx/server 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <strong>@voltx/server</strong><br/>
-  <em>Hono-based HTTP server with file-based routing and SSE streaming</em>
+  <em>Hono-based HTTP server with file-based routing, SSR, and SSE streaming</em>
 </p>
 
 <p align="center">
@@ -11,7 +11,7 @@
 
 ---
 
-The HTTP layer of the [VoltX](https://github.com/codewithshail/voltx) framework. Built on [Hono](https://hono.dev) with file-based routing (Next.js-style), CORS, logging, error handling, and static file serving out of the box.
+The HTTP layer of the [VoltX](https://github.com/codewithshail/voltx) framework. Built on [Hono](https://hono.dev) with file-based routing, React SSR (streaming), CORS, logging, error handling, and static file serving.
 
 ## Installation
 
@@ -22,34 +22,63 @@ npm install @voltx/server
 ## Quick Start
 
 ```ts
-import { createServer } from "@voltx/server";
+import { Hono } from "hono";
+import { registerSSR } from "@voltx/server";
 
-const server = createServer({
-  port: 3000,
-  routesDir: "src/routes",
-  cors: true,
-  logger: true,
+const app = new Hono();
+
+// API routes
+app.get("/api", (c) => c.json({ status: "ok" }));
+
+// SSR — renders React on the server, hydrates on the client
+registerSSR(app, null, {
+  title: "My App",
+  entryServer: "src/entry-server.tsx",
+  entryClient: "src/entry-client.tsx",
 });
 
-await server.start();
-// ⚡ VoltX server running at http://localhost:3000
+export default app;
 ```
 
+## Server-Side Rendering
+
+`registerSSR()` provides streaming React SSR with zero config:
+
+- **Dev mode** — works with `@hono/vite-dev-server` for HMR
+- **Production** — reads the Vite client manifest for hashed asset paths, serves pre-built SSR bundle
+- **Streaming** — uses `renderToReadableStream` for fast TTFB
+- **Public env** — injects `window.__VOLTX_ENV__` for `VITE_*` variables
+
+```ts
+import { registerSSR } from "@voltx/server";
+
+registerSSR(app, viteInstance, {
+  title: "My App",
+  entryServer: "src/entry-server.tsx",
+  entryClient: "src/entry-client.tsx",
+});
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title` | `string` | HTML `<title>` |
+| `entryServer` | `string` | Path to SSR entry (exports `render()`) |
+| `entryClient` | `string` | Path to client hydration entry |
+
 ## File-Based Routing
 
-Drop files in `src/routes/` and they become API endpoints automatically:
+Drop files in `api/` and they become API endpoints:
 
 ```
-src/routes/index.ts           → GET /
-src/routes/api/chat.ts        → POST /api/chat
-src/routes/api/users/[id].ts  → GET /api/users/:id
-src/routes/api/[...slug].ts   → /api/* (catch-all)
+api/index.ts              → GET /api
+api/chat.ts               → POST /api/chat
+api/users/[id].ts         → GET /api/users/:id
+api/rag/query.ts          → POST /api/rag/query
 ```
 
 Each file exports HTTP method handlers:
 
 ```ts
-// src/routes/api/chat.ts
 import type { Context } from "@voltx/server";
 
 export async function POST(c: Context) {
@@ -64,24 +93,12 @@ export function GET(c: Context) {
 
 ## Features
 
-- **File-based routing** — Next.js-style, zero config
-- **Dynamic routes** — `[param]` → `:param`, `[...slug]` → catch-all
+- **React SSR** — streaming server-side rendering with `registerSSR()`
+- **File-based routing** — Next.js-style `api/` directory
+- **Dynamic routes** — `[param]` and `[...slug]` catch-all
 - **Built-in middleware** — CORS, request logging, error handling
-- **Static file serving** — Serves from `public/` directory
-- **Per-route middleware** — Export `middleware` from any route file
-- **Graceful shutdown** — Clean server stop with `server.stop()`
-- **Full Hono access** — `server.app` gives you the raw Hono instance
-
-## Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `port` | `number` | `3000` | Server port |
-| `hostname` | `string` | `"0.0.0.0"` | Bind address |
-| `routesDir` | `string` | `"src/routes"` | Routes directory |
-| `staticDir` | `string` | `"public"` | Static files directory |
-| `cors` | `boolean \| object` | `true` | CORS configuration |
-| `logger` | `boolean` | `true` (dev) | Request logging |
+- **Static file serving** — `public/` directory (favicon, robots.txt, manifest)
+- **Full Hono access** — use any Hono middleware or plugin
 
 ## Part of VoltX
 

package/dist/index.cjs

@@ -26,7 +26,9 @@ __export(index_exports, {
   createErrorHandler: () => createErrorHandler,
   createLoggerMiddleware: () => createLoggerMiddleware,
   createServer: () => createServer,
+  createViteDevConfig: () => createViteDevConfig,
   filePathToUrlPath: () => filePathToUrlPath,
+  registerSSR: () => registerSSR,
   registerStaticFiles: () => registerStaticFiles,
   scanAndRegisterRoutes: () => scanAndRegisterRoutes
 });
@@ -161,13 +163,16 @@ function filePathToUrlPath(filePath, routesDir) {
   const ext = (0, import_node_path.extname)(rel);
   rel = rel.slice(0, -ext.length);
   rel = rel.replace(/\\/g, "/");
-  if (rel === "index") return "/";
-  if (rel.endsWith("/index")) {
+  if (rel === "index") rel = "";
+  else if (rel.endsWith("/index")) {
     rel = rel.slice(0, -"/index".length);
   }
   rel = rel.replace(/\[([^\]\.]+)\]/g, ":$1");
   rel = rel.replace(/\[\.\.\.([^\]]+)\]/g, "*");
-  return "/" + rel;
+  const dirBasename = routesDir.replace(/\\/g, "/").split("/").pop() ?? "";
+  const prefix = dirBasename && dirBasename !== "routes" && dirBasename !== "src" ? `/${dirBasename}` : "";
+  if (!rel) return prefix || "/";
+  return `${prefix}/${rel}`;
 }
 async function importRouteModule(filePath) {
   try {
@@ -190,7 +195,7 @@ function createServer(config = {}) {
   const {
     port = Number(process.env.PORT) || 3e3,
     hostname = "0.0.0.0",
-    routesDir = "src/routes",
+    routesDir = "api",
     staticDir = "public",
     cors = true,
     logger: enableLogger = process.env.NODE_ENV !== "production",
@@ -246,10 +251,10 @@ function createServer(config = {}) {
     },
     async stop() {
       if (httpServer) {
-        await new Promise((resolve2, reject) => {
+        await new Promise((resolve3, reject) => {
           httpServer.close((err) => {
             if (err) reject(err);
-            else resolve2();
+            else resolve3();
           });
         });
         httpServer = null;
@@ -271,6 +276,137 @@ function createServer(config = {}) {
 
 // src/index.ts
 var import_hono2 = require("hono");
+
+// src/vite.ts
+function createViteDevConfig(options = {}) {
+  const {
+    root = process.cwd(),
+    entry = "src/index.ts"
+  } = options;
+  return {
+    root,
+    server: {
+      // Let Hono handle the port — Vite runs in middleware mode via the plugin
+      hmr: true
+    },
+    plugins: [],
+    // Plugins are added dynamically when starting
+    // Externalize Node.js packages for SSR
+    ssr: {
+      external: ["react", "react-dom"]
+    },
+    entry
+  };
+}
+
+// src/ssr.ts
+var import_node_path3 = require("path");
+var import_node_fs = require("fs");
+function getPublicEnv() {
+  const publicEnv = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("VOLTX_PUBLIC_") && value !== void 0) {
+      publicEnv[key] = value;
+    }
+  }
+  return publicEnv;
+}
+function registerSSR(app, vite, options = {}) {
+  const entryServer = options.entryServer ?? "src/entry-server.tsx";
+  const entryClient = options.entryClient ?? "src/entry-client.tsx";
+  const title = options.title ?? "VoltX App";
+  let manifest = null;
+  app.get("*", async (c) => {
+    const url = new URL(c.req.url, "http://localhost").pathname;
+    if (url.startsWith("/api/") || url.startsWith("/assets/") || url.startsWith("/@") || url.startsWith("/node_modules/") || url.includes(".")) {
+      return c.notFound();
+    }
+    try {
+      let render;
+      if (vite) {
+        const mod = await vite.ssrLoadModule(entryServer);
+        render = mod.render;
+      } else if (process.env.NODE_ENV === "production") {
+        const ssrBundlePath = (0, import_node_path3.resolve)(process.cwd(), "dist/server/entry-server.js");
+        const mod = await import(ssrBundlePath);
+        render = mod.render;
+      } else {
+        const mod = await import(
+          /* @vite-ignore */
+          (0, import_node_path3.resolve)(process.cwd(), entryServer)
+        );
+        render = mod.render;
+      }
+      const appStream = await render(url);
+      const publicEnv = getPublicEnv();
+      let clientScript;
+      let cssLinks = "";
+      const isProd = process.env.NODE_ENV === "production";
+      if (!isProd) {
+        clientScript = `/${entryClient}`;
+      } else {
+        if (!manifest) {
+          const manifestPath = (0, import_node_path3.resolve)(process.cwd(), "dist/client/.vite/manifest.json");
+          if ((0, import_node_fs.existsSync)(manifestPath)) {
+            manifest = JSON.parse((0, import_node_fs.readFileSync)(manifestPath, "utf-8"));
+          }
+        }
+        const entry = manifest?.[entryClient];
+        clientScript = entry ? `/${entry.file}` : "/assets/entry-client.js";
+        if (entry?.css) {
+          cssLinks = entry.css.map((css) => `    <link rel="stylesheet" href="/${css}" />`).join("\n");
+        }
+      }
+      const htmlHead = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  <link rel="manifest" href="/site.webmanifest" />
+  <meta name="theme-color" content="#0a0a0a" />
+${!isProd ? '  <script type="module" src="/@vite/client"></script>' : ""}
+${cssLinks}
+  <script>window.__VOLTX_ENV__ = ${JSON.stringify(publicEnv)}</script>
+</head>
+<body>
+  <div id="root">`;
+      const htmlTail = `</div>
+  <script type="module" src="${clientScript}"></script>
+</body>
+</html>`;
+      const { readable, writable } = new TransformStream();
+      const writer = writable.getWriter();
+      const encoder = new TextEncoder();
+      (async () => {
+        try {
+          await writer.write(encoder.encode(htmlHead));
+          const reader = appStream.getReader();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            await writer.write(value);
+          }
+          await writer.write(encoder.encode(htmlTail));
+        } catch (err) {
+          console.error("[voltx] SSR stream error:", err);
+        } finally {
+          await writer.close();
+        }
+      })();
+      return new Response(readable, {
+        headers: { "Content-Type": "text/html; charset=utf-8" }
+      });
+    } catch (err) {
+      if (vite) vite.ssrFixStacktrace(err);
+      console.error("[voltx] SSR render error:", err);
+      return c.text("Internal Server Error", 500);
+    }
+  });
+}
+
+// src/index.ts
 var VERSION = "0.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -280,7 +416,9 @@ var VERSION = "0.3.0";
   createErrorHandler,
   createLoggerMiddleware,
   createServer,
+  createViteDevConfig,
   filePathToUrlPath,
+  registerSSR,
   registerStaticFiles,
   scanAndRegisterRoutes
 });

package/dist/index.d.cts

@@ -7,7 +7,7 @@ interface ServerConfig {
     port?: number;
     /** Hostname to bind to (default: "0.0.0.0") */
     hostname?: string;
-    /** Directory to scan for file-based routes (default: "src/routes") */
+    /** Directory to scan for file-based routes (default: "api") */
     routesDir?: string;
     /** Directory for static files (default: "public") */
     staticDir?: string;
@@ -90,7 +90,7 @@ interface VoltxServer {
  *
  * const server = createServer({
  *   port: 3000,
- *   routesDir: "src/routes",
+ *   routesDir: "api",
  *   cors: true,
  *   logger: true,
  * });
@@ -111,11 +111,11 @@ declare function scanAndRegisterRoutes(app: Hono, routesDir: string): Promise<Ro
 /**
  * Convert a file path to a URL path.
  *
- * Examples:
- *   routes/index.ts           → /
- *   routes/api/chat.ts        → /api/chat
- *   routes/api/users/[id].ts  → /api/users/:id
- *   routes/api/[...slug].ts   → /api/*
+ * Examples (routesDir = "api"):
+ *   api/index.ts             → /api
+ *   api/chat.ts              → /api/chat
+ *   api/users/[id].ts        → /api/users/:id
+ *   api/[...slug].ts         → /api/*
  */
 declare function filePathToUrlPath(filePath: string, routesDir: string): string;
 
@@ -145,6 +145,60 @@ declare function createLoggerMiddleware(): hono.MiddlewareHandler;
  */
 declare function createErrorHandler(customHandler?: (err: Error, c: Context) => Response | Promise<Response>): (err: Error, c: Context) => Promise<Response>;
 
+interface ViteDevOptions {
+    /** Project root directory (default: process.cwd()) */
+    root?: string;
+    /** Hono server entry file (default: src/index.ts) */
+    entry?: string;
+    /** Frontend entry for client-side hydration */
+    entryClient?: string;
+    /** Frontend entry for SSR rendering */
+    entryServer?: string;
+}
+/**
+ * Create a Vite config for full-stack development with Hono.
+ *
+ * Uses @hono/vite-dev-server to embed Vite inside Hono.
+ * The Hono app handles API routes, Vite handles frontend assets + HMR.
+ *
+ * This function returns a Vite config object that can be written to
+ * a temporary vite.config.ts or passed to Vite's createServer API.
+ */
+declare function createViteDevConfig(options?: ViteDevOptions): {
+    root: string;
+    server: {
+        hmr: boolean;
+    };
+    plugins: never[];
+    ssr: {
+        external: string[];
+    };
+    entry: string;
+};
+
+interface SSROptions {
+    /** Path to entry-server module (default: src/entry-server.tsx) */
+    entryServer?: string;
+    /** Path to entry-client module (default: src/entry-client.tsx) */
+    entryClient?: string;
+    /** App title (default: "VoltX App") */
+    title?: string;
+}
+/** Vite dev server shape — minimal interface to avoid hard dep on vite */
+interface ViteDevServer {
+    ssrLoadModule(url: string): Promise<Record<string, unknown>>;
+    ssrFixStacktrace(e: Error): void;
+}
+/**
+ * Register SSR catch-all handler on a Hono app.
+ * Must be registered AFTER API routes — it catches all non-API GET requests
+ * and renders the React app server-side with streaming.
+ *
+ * In dev: loads entry-server via Vite's ssrLoadModule (HMR-aware).
+ * In prod: loads pre-built SSR bundle + reads Vite manifest for asset paths.
+ */
+declare function registerSSR(app: Hono, vite: ViteDevServer | null, options?: SSROptions): void;
+
 declare const VERSION = "0.3.0";
 
-export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type ServerConfig, type ServerInfo, VERSION, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, filePathToUrlPath, registerStaticFiles, scanAndRegisterRoutes };
+export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type SSROptions, type ServerConfig, type ServerInfo, VERSION, type ViteDevOptions, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, createViteDevConfig, filePathToUrlPath, registerSSR, registerStaticFiles, scanAndRegisterRoutes };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ interface ServerConfig {
     port?: number;
     /** Hostname to bind to (default: "0.0.0.0") */
     hostname?: string;
-    /** Directory to scan for file-based routes (default: "src/routes") */
+    /** Directory to scan for file-based routes (default: "api") */
     routesDir?: string;
     /** Directory for static files (default: "public") */
     staticDir?: string;
@@ -90,7 +90,7 @@ interface VoltxServer {
  *
  * const server = createServer({
  *   port: 3000,
- *   routesDir: "src/routes",
+ *   routesDir: "api",
  *   cors: true,
  *   logger: true,
  * });
@@ -111,11 +111,11 @@ declare function scanAndRegisterRoutes(app: Hono, routesDir: string): Promise<Ro
 /**
  * Convert a file path to a URL path.
  *
- * Examples:
- *   routes/index.ts           → /
- *   routes/api/chat.ts        → /api/chat
- *   routes/api/users/[id].ts  → /api/users/:id
- *   routes/api/[...slug].ts   → /api/*
+ * Examples (routesDir = "api"):
+ *   api/index.ts             → /api
+ *   api/chat.ts              → /api/chat
+ *   api/users/[id].ts        → /api/users/:id
+ *   api/[...slug].ts         → /api/*
  */
 declare function filePathToUrlPath(filePath: string, routesDir: string): string;
 
@@ -145,6 +145,60 @@ declare function createLoggerMiddleware(): hono.MiddlewareHandler;
  */
 declare function createErrorHandler(customHandler?: (err: Error, c: Context) => Response | Promise<Response>): (err: Error, c: Context) => Promise<Response>;
 
+interface ViteDevOptions {
+    /** Project root directory (default: process.cwd()) */
+    root?: string;
+    /** Hono server entry file (default: src/index.ts) */
+    entry?: string;
+    /** Frontend entry for client-side hydration */
+    entryClient?: string;
+    /** Frontend entry for SSR rendering */
+    entryServer?: string;
+}
+/**
+ * Create a Vite config for full-stack development with Hono.
+ *
+ * Uses @hono/vite-dev-server to embed Vite inside Hono.
+ * The Hono app handles API routes, Vite handles frontend assets + HMR.
+ *
+ * This function returns a Vite config object that can be written to
+ * a temporary vite.config.ts or passed to Vite's createServer API.
+ */
+declare function createViteDevConfig(options?: ViteDevOptions): {
+    root: string;
+    server: {
+        hmr: boolean;
+    };
+    plugins: never[];
+    ssr: {
+        external: string[];
+    };
+    entry: string;
+};
+
+interface SSROptions {
+    /** Path to entry-server module (default: src/entry-server.tsx) */
+    entryServer?: string;
+    /** Path to entry-client module (default: src/entry-client.tsx) */
+    entryClient?: string;
+    /** App title (default: "VoltX App") */
+    title?: string;
+}
+/** Vite dev server shape — minimal interface to avoid hard dep on vite */
+interface ViteDevServer {
+    ssrLoadModule(url: string): Promise<Record<string, unknown>>;
+    ssrFixStacktrace(e: Error): void;
+}
+/**
+ * Register SSR catch-all handler on a Hono app.
+ * Must be registered AFTER API routes — it catches all non-API GET requests
+ * and renders the React app server-side with streaming.
+ *
+ * In dev: loads entry-server via Vite's ssrLoadModule (HMR-aware).
+ * In prod: loads pre-built SSR bundle + reads Vite manifest for asset paths.
+ */
+declare function registerSSR(app: Hono, vite: ViteDevServer | null, options?: SSROptions): void;
+
 declare const VERSION = "0.3.0";
 
-export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type ServerConfig, type ServerInfo, VERSION, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, filePathToUrlPath, registerStaticFiles, scanAndRegisterRoutes };
+export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type SSROptions, type ServerConfig, type ServerInfo, VERSION, type ViteDevOptions, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, createViteDevConfig, filePathToUrlPath, registerSSR, registerStaticFiles, scanAndRegisterRoutes };

package/dist/index.js

@@ -127,13 +127,16 @@ function filePathToUrlPath(filePath, routesDir) {
   const ext = extname(rel);
   rel = rel.slice(0, -ext.length);
   rel = rel.replace(/\\/g, "/");
-  if (rel === "index") return "/";
-  if (rel.endsWith("/index")) {
+  if (rel === "index") rel = "";
+  else if (rel.endsWith("/index")) {
     rel = rel.slice(0, -"/index".length);
   }
   rel = rel.replace(/\[([^\]\.]+)\]/g, ":$1");
   rel = rel.replace(/\[\.\.\.([^\]]+)\]/g, "*");
-  return "/" + rel;
+  const dirBasename = routesDir.replace(/\\/g, "/").split("/").pop() ?? "";
+  const prefix = dirBasename && dirBasename !== "routes" && dirBasename !== "src" ? `/${dirBasename}` : "";
+  if (!rel) return prefix || "/";
+  return `${prefix}/${rel}`;
 }
 async function importRouteModule(filePath) {
   try {
@@ -156,7 +159,7 @@ function createServer(config = {}) {
   const {
     port = Number(process.env.PORT) || 3e3,
     hostname = "0.0.0.0",
-    routesDir = "src/routes",
+    routesDir = "api",
     staticDir = "public",
     cors = true,
     logger: enableLogger = process.env.NODE_ENV !== "production",
@@ -212,10 +215,10 @@ function createServer(config = {}) {
     },
     async stop() {
       if (httpServer) {
-        await new Promise((resolve2, reject) => {
+        await new Promise((resolve3, reject) => {
           httpServer.close((err) => {
             if (err) reject(err);
-            else resolve2();
+            else resolve3();
           });
         });
         httpServer = null;
@@ -237,6 +240,137 @@ function createServer(config = {}) {
 
 // src/index.ts
 import { Hono as Hono2 } from "hono";
+
+// src/vite.ts
+function createViteDevConfig(options = {}) {
+  const {
+    root = process.cwd(),
+    entry = "src/index.ts"
+  } = options;
+  return {
+    root,
+    server: {
+      // Let Hono handle the port — Vite runs in middleware mode via the plugin
+      hmr: true
+    },
+    plugins: [],
+    // Plugins are added dynamically when starting
+    // Externalize Node.js packages for SSR
+    ssr: {
+      external: ["react", "react-dom"]
+    },
+    entry
+  };
+}
+
+// src/ssr.ts
+import { resolve as resolve2 } from "path";
+import { readFileSync, existsSync } from "fs";
+function getPublicEnv() {
+  const publicEnv = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("VOLTX_PUBLIC_") && value !== void 0) {
+      publicEnv[key] = value;
+    }
+  }
+  return publicEnv;
+}
+function registerSSR(app, vite, options = {}) {
+  const entryServer = options.entryServer ?? "src/entry-server.tsx";
+  const entryClient = options.entryClient ?? "src/entry-client.tsx";
+  const title = options.title ?? "VoltX App";
+  let manifest = null;
+  app.get("*", async (c) => {
+    const url = new URL(c.req.url, "http://localhost").pathname;
+    if (url.startsWith("/api/") || url.startsWith("/assets/") || url.startsWith("/@") || url.startsWith("/node_modules/") || url.includes(".")) {
+      return c.notFound();
+    }
+    try {
+      let render;
+      if (vite) {
+        const mod = await vite.ssrLoadModule(entryServer);
+        render = mod.render;
+      } else if (process.env.NODE_ENV === "production") {
+        const ssrBundlePath = resolve2(process.cwd(), "dist/server/entry-server.js");
+        const mod = await import(ssrBundlePath);
+        render = mod.render;
+      } else {
+        const mod = await import(
+          /* @vite-ignore */
+          resolve2(process.cwd(), entryServer)
+        );
+        render = mod.render;
+      }
+      const appStream = await render(url);
+      const publicEnv = getPublicEnv();
+      let clientScript;
+      let cssLinks = "";
+      const isProd = process.env.NODE_ENV === "production";
+      if (!isProd) {
+        clientScript = `/${entryClient}`;
+      } else {
+        if (!manifest) {
+          const manifestPath = resolve2(process.cwd(), "dist/client/.vite/manifest.json");
+          if (existsSync(manifestPath)) {
+            manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+          }
+        }
+        const entry = manifest?.[entryClient];
+        clientScript = entry ? `/${entry.file}` : "/assets/entry-client.js";
+        if (entry?.css) {
+          cssLinks = entry.css.map((css) => `    <link rel="stylesheet" href="/${css}" />`).join("\n");
+        }
+      }
+      const htmlHead = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  <link rel="manifest" href="/site.webmanifest" />
+  <meta name="theme-color" content="#0a0a0a" />
+${!isProd ? '  <script type="module" src="/@vite/client"></script>' : ""}
+${cssLinks}
+  <script>window.__VOLTX_ENV__ = ${JSON.stringify(publicEnv)}</script>
+</head>
+<body>
+  <div id="root">`;
+      const htmlTail = `</div>
+  <script type="module" src="${clientScript}"></script>
+</body>
+</html>`;
+      const { readable, writable } = new TransformStream();
+      const writer = writable.getWriter();
+      const encoder = new TextEncoder();
+      (async () => {
+        try {
+          await writer.write(encoder.encode(htmlHead));
+          const reader = appStream.getReader();
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            await writer.write(value);
+          }
+          await writer.write(encoder.encode(htmlTail));
+        } catch (err) {
+          console.error("[voltx] SSR stream error:", err);
+        } finally {
+          await writer.close();
+        }
+      })();
+      return new Response(readable, {
+        headers: { "Content-Type": "text/html; charset=utf-8" }
+      });
+    } catch (err) {
+      if (vite) vite.ssrFixStacktrace(err);
+      console.error("[voltx] SSR render error:", err);
+      return c.text("Internal Server Error", 500);
+    }
+  });
+}
+
+// src/index.ts
 var VERSION = "0.3.0";
 export {
   Hono2 as Hono,
@@ -245,7 +379,9 @@ export {
   createErrorHandler,
   createLoggerMiddleware,
   createServer,
+  createViteDevConfig,
   filePathToUrlPath,
+  registerSSR,
   registerStaticFiles,
   scanAndRegisterRoutes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltx/server",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "VoltX Server — Hono-based HTTP server with file-based routing, SSE streaming, and static file serving",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,9 +23,19 @@
     "hono": "^4.7.0",
     "@hono/node-server": "^1.14.0"
   },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
+  },
   "devDependencies": {
     "tsup": "^8.0.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0"
   },
   "keywords": ["voltx", "server", "hono", "http", "routing", "file-based", "sse", "streaming", "middleware"],
   "license": "MIT",