@voltx/server 0.4.5 → 0.4.7

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <strong>@voltx/server</strong><br/>
-  <em>Hono-based HTTP server with file-based routing, SSR, and SSE streaming</em>
+  <em>Hono-based HTTP server with file-based routing, React SSR, and Vite plugins</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, React SSR (streaming), CORS, logging, error handling, and static file serving.
+The HTTP layer of the [VoltX](https://github.com/codewithshail/voltx) framework. Built on [Hono](https://hono.dev) with file-based page routing, file-based API routing, React SSR (streaming), CORS, logging, error handling, and static file serving.
 
 ## Installation
 
@@ -22,24 +22,125 @@ npm install @voltx/server
 ## Quick Start
 
 ```ts
+// server.ts
 import { Hono } from "hono";
 import { registerSSR } from "@voltx/server";
+import { registerRoutes } from "voltx/api";
 
 const app = new Hono();
 
-// API routes
-app.get("/api", (c) => c.json({ status: "ok" }));
+// Auto-discover and mount all API routes from api/ directory
+registerRoutes(app);
 
 // 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",
+  css: "src/globals.css",
 });
 
 export default app;
 ```
 
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import devServer from "@hono/vite-dev-server";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+import { voltxRouter, voltxAPI } from "@voltx/server";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+    voltxRouter(),   // File-based page routing → voltx/router
+    voltxAPI(),      // File-based API routing → voltx/api
+    devServer({ entry: "server.ts" }),
+  ],
+});
+```
+
+## Vite Plugins
+
+### `voltxRouter()` — File-Based Page Routing
+
+Auto-discovers React components in `src/pages/` and provides the `voltx/router` virtual module.
+
+```
+src/pages/index.tsx         → /
+src/pages/about.tsx         → /about
+src/pages/blog/index.tsx    → /blog
+src/pages/blog/[slug].tsx   → /blog/:slug (dynamic route)
+```
+
+```tsx
+// Use in entry-client.tsx and entry-server.tsx
+import { VoltxRoutes, Link, useNavigate, useParams } from "voltx/router";
+
+// VoltxRoutes renders the matched page component
+// Link, NavLink, useNavigate, useParams, useLocation, useSearchParams
+// are re-exported from react-router — no separate install needed
+```
+
+#### Options
+
+```ts
+voltxRouter({
+  pagesDir: "src/pages",  // default: "src/pages"
+})
+```
+
+### `voltxAPI()` — File-Based API Routing
+
+Auto-discovers API route files in `api/` and provides the `voltx/api` virtual module.
+
+```
+api/index.ts              → /api
+api/users.ts              → /api/users
+api/users/[id].ts         → /api/users/:id
+api/[...slug].ts          → /api/* (catch-all)
+```
+
+Each file exports named HTTP method handlers:
+
+```ts
+// api/users.ts
+import type { Context } from "@voltx/server";
+
+export function GET(c: Context) {
+  return c.json([{ id: 1, name: "Alice" }]);
+}
+
+export async function POST(c: Context) {
+  const body = await c.req.json();
+  return c.json({ created: true }, 201);
+}
+```
+
+Supported methods: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`.
+
+Routes are sorted automatically: static first, dynamic (`:param`) second, catch-all (`*`) last. HMR support means new files are picked up instantly in dev mode.
+
+#### Options
+
+```ts
+voltxAPI({
+  apiDir: "api",  // default: "api"
+})
+```
+
+#### Usage in server.ts
+
+```ts
+import { registerRoutes } from "voltx/api";
+
+// Mounts all discovered API handlers on the Hono app
+const registered = registerRoutes(app);
+// → [{ method: "GET", path: "/api" }, { method: "POST", path: "/api/users" }, ...]
+```
+
 ## Server-Side Rendering
 
 `registerSSR()` provides streaming React SSR with zero config:
@@ -47,6 +148,7 @@ export default app;
 - **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
+- **CSS injection** — injects your global CSS in dev mode to prevent FOUC
 - **Public env** — injects `window.__VOLTX_ENV__` for `VITE_*` variables
 
 ```ts
@@ -56,6 +158,7 @@ registerSSR(app, viteInstance, {
   title: "My App",
   entryServer: "src/entry-server.tsx",
   entryClient: "src/entry-client.tsx",
+  css: "src/globals.css",
 });
 ```
 
@@ -64,38 +167,16 @@ registerSSR(app, viteInstance, {
 | `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 `api/` and they become API endpoints:
-
-```
-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
-import type { Context } from "@voltx/server";
-
-export async function POST(c: Context) {
-  const body = await c.req.json();
-  return c.json({ message: "Hello!" });
-}
-
-export function GET(c: Context) {
-  return c.json({ status: "ok" });
-}
-```
+| `css` | `string` | Path to global CSS file (prevents FOUC in dev) |
 
 ## Features
 
+- **Vite plugins** — `voltxRouter()` and `voltxAPI()` for Next.js-style file-based routing
+- **Virtual modules** — `voltx/router` and `voltx/api` for clean imports
 - **React SSR** — streaming server-side rendering with `registerSSR()`
-- **File-based routing** — Next.js-style `api/` directory
-- **Dynamic routes** — `[param]` and `[...slug]` catch-all
+- **Navigation** — `Link`, `NavLink`, `useNavigate`, `useParams` from `voltx/router`
+- **Dynamic routes** — `[param]` and `[...slug]` catch-all for both pages and API
+- **HMR** — new pages and API files are picked up instantly in dev mode
 - **Built-in middleware** — CORS, request logging, error handling
 - **Static file serving** — `public/` directory (favicon, robots.txt, manifest)
 - **Full Hono access** — use any Hono middleware or plugin

package/dist/index.cjs

@@ -41,6 +41,7 @@ __export(index_exports, {
   registerSSR: () => registerSSR,
   registerStaticFiles: () => registerStaticFiles,
   scanAndRegisterRoutes: () => scanAndRegisterRoutes,
+  voltxAPI: () => voltxAPI,
   voltxRouter: () => voltxRouter
 });
 module.exports = __toCommonJS(index_exports);
@@ -333,55 +334,374 @@ function voltxRouter(options = {}) {
     },
     load(id) {
       if (id === RESOLVED_ID) {
-        return `
-import { createElement } from "react";
-import { Routes, Route } from "react-router";
+        return generateRouterModule(pagesDir);
+      }
+    },
+    handleHotUpdate({ file, server }) {
+      if (file.includes(pagesDir.replace(/\//g, "/"))) {
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          server.ws.send({ type: "full-reload" });
+        }
+      }
+    }
+  };
+}
+function generateRouterModule(pagesDir) {
+  return `
+import { createElement, Component, Suspense } from "react";
+import { Routes, Route, Outlet } from "react-router";
+
+// \u2500\u2500\u2500 Glob all files in pages directory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+const allFiles = import.meta.glob("/${pagesDir}/**/*.tsx", { eager: true });
 
-const pages = import.meta.glob("/${pagesDir}/**/*.tsx", { eager: true });
+// \u2500\u2500\u2500 Classify files by type \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Special files: layout.tsx, loading.tsx, error.tsx, not-found.tsx
+// Page files: everything else (index.tsx, about.tsx, [slug].tsx, etc.)
 
-function buildRoutes() {
-  const routes = [];
-  for (const [filePath, mod] of Object.entries(pages)) {
+const SPECIAL_FILES = new Set(["layout", "loading", "error", "not-found"]);
+
+function classifyFiles() {
+  const pages = {};      // dir \u2192 [{ routePath, Component }]
+  const layouts = {};    // dir \u2192 Component
+  const loadings = {};   // dir \u2192 Component
+  const errors = {};     // dir \u2192 Component
+  let notFound = null;   // global not-found component
+
+  for (const [filePath, mod] of Object.entries(allFiles)) {
     const Component = mod.default;
     if (!Component) continue;
 
-    let routePath = filePath
-      .replace("/${pagesDir}", "")
-      .replace(/\\.tsx$/, "")
-      .replace(/\\/index$/, "/")
-      .replace(/\\[([^\\]]+)\\]/g, ":$1");
+    // Get relative path from pages dir: "/src/pages/blog/index.tsx" \u2192 "blog/index.tsx"
+    const rel = filePath.replace("/${pagesDir}/", "");
+    const parts = rel.replace(/\\.tsx$/, "").split("/");
+    const fileName = parts[parts.length - 1];
+    const dir = parts.length > 1 ? parts.slice(0, -1).join("/") : "";
+
+    if (fileName === "layout") {
+      layouts[dir] = Component;
+    } else if (fileName === "loading") {
+      loadings[dir] = Component;
+    } else if (fileName === "error") {
+      errors[dir] = Component;
+    } else if (fileName === "not-found") {
+      if (dir === "") notFound = Component;
+    } else {
+      // It's a page file \u2014 compute route path
+      let routePath = rel
+        .replace(/\\.tsx$/, "")
+        .replace(/(^|\\/)index$/, "$1")
+        .replace(/\\[([^\\]]+)\\]/g, ":$1")
+        .replace(/\\/$/, "");
+
+      if (!routePath) routePath = "";
 
-    if (!routePath.startsWith("/")) routePath = "/" + routePath;
-    if (routePath !== "/" && routePath.endsWith("/")) {
-      routePath = routePath.slice(0, -1);
+      if (!pages[dir]) pages[dir] = [];
+      pages[dir].push({ routePath: "/" + routePath, Component });
     }
+  }
+
+  return { pages, layouts, loadings, errors, notFound };
+}
 
-    routes.push({ path: routePath, Component });
+const { pages, layouts, loadings, errors, notFound } = classifyFiles();
+
+// \u2500\u2500\u2500 Error Boundary Component \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+class VoltxErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
   }
-  return routes;
+
+  render() {
+    if (this.state.hasError) {
+      const reset = () => this.setState({ hasError: false, error: null });
+      if (this.props.fallback) {
+        return createElement(this.props.fallback, {
+          error: this.state.error,
+          reset,
+        });
+      }
+      return createElement("div", { style: { padding: "2rem" } },
+        createElement("h2", null, "Something went wrong"),
+        createElement("button", { onClick: reset }, "Try again")
+      );
+    }
+    return this.props.children;
+  }
+}
+
+// \u2500\u2500\u2500 Build nested route tree \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Directories are sorted so parents come before children.
+// Each directory with a layout.tsx becomes a layout route.
+// Pages within that directory become its children.
+
+function getAllDirs() {
+  const dirs = new Set([""]);
+  for (const dir of Object.keys(pages)) dirs.add(dir);
+  for (const dir of Object.keys(layouts)) dirs.add(dir);
+  for (const dir of Object.keys(loadings)) dirs.add(dir);
+  for (const dir of Object.keys(errors)) dirs.add(dir);
+  return Array.from(dirs).sort((a, b) => {
+    if (a === "") return -1;
+    if (b === "") return 1;
+    return a.localeCompare(b);
+  });
+}
+
+function getParentDir(dir) {
+  if (dir === "") return null;
+  const idx = dir.lastIndexOf("/");
+  return idx === -1 ? "" : dir.substring(0, idx);
+}
+
+// Find the nearest ancestor directory that has a layout
+function findLayoutAncestor(dir) {
+  let current = getParentDir(dir);
+  while (current !== null) {
+    if (layouts[current]) return current;
+    current = getParentDir(current);
+  }
+  return null;
+}
+
+// Wrap element with loading (Suspense) and error boundary if available for a dir
+function wrapElement(element, dir) {
+  let wrapped = element;
+  if (errors[dir]) {
+    wrapped = createElement(VoltxErrorBoundary, { fallback: errors[dir] }, wrapped);
+  }
+  if (loadings[dir]) {
+    wrapped = createElement(Suspense, { fallback: createElement(loadings[dir]) }, wrapped);
+  }
+  return wrapped;
 }
 
-const routes = buildRoutes();
+// \u2500\u2500\u2500 Layout wrapper component \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// A layout component that renders the layout with <Outlet /> for children
+function createLayoutElement(LayoutComp, dir) {
+  // The layout component receives <Outlet /> as its children rendering point
+  // We create a wrapper that renders Layout with Outlet inside
+  function LayoutWrapper() {
+    return createElement(LayoutComp, null, createElement(Outlet));
+  }
+  LayoutWrapper.displayName = "Layout(" + (dir || "root") + ")";
+  return LayoutWrapper;
+}
+
+// \u2500\u2500\u2500 Generate the <Routes> tree \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+function buildRouteElements() {
+  const allDirs = getAllDirs();
+
+  // Build a tree structure: each dir can have child routes and child layout dirs
+  // dirChildren[dir] = array of Route elements (pages + nested layout routes)
+  const dirChildren = {};
+  for (const dir of allDirs) {
+    dirChildren[dir] = [];
+  }
+
+  // First, add page routes to their directory
+  for (const dir of allDirs) {
+    const dirPages = pages[dir] || [];
+    for (const { routePath, Component: PageComp } of dirPages) {
+      // Compute the path relative to the directory's base
+      const dirBase = dir ? "/" + dir : "";
+      let relativePath = routePath;
+      if (dirBase && relativePath.startsWith(dirBase)) {
+        relativePath = relativePath.substring(dirBase.length);
+      }
+      if (relativePath.startsWith("/")) relativePath = relativePath.substring(1);
+
+      const isIndex = relativePath === "";
+      const routeProps = isIndex
+        ? { index: true, element: createElement(PageComp), key: routePath }
+        : { path: relativePath, element: createElement(PageComp), key: routePath };
+
+      dirChildren[dir].push(createElement(Route, routeProps));
+    }
+  }
+
+  // Now, nest directories bottom-up: child dirs become Route children of parent dirs
+  // Process in reverse order (deepest first)
+  const reversedDirs = allDirs.slice().reverse();
+
+  for (const dir of reversedDirs) {
+    if (dir === "") continue; // root handled last
+
+    const parentDir = getParentDir(dir);
+    if (parentDir === null) continue;
+
+    const hasLayout = !!layouts[dir];
+    const children = dirChildren[dir];
+
+    // Compute path segment for this directory relative to parent
+    const parentBase = parentDir ? parentDir + "/" : "";
+    const segment = dir.startsWith(parentBase) ? dir.substring(parentBase.length) : dir;
+    // Convert [param] to :param in segment
+    const routeSegment = segment.replace(/\\[([^\\]]+)\\]/g, ":$1");
+
+    if (hasLayout) {
+      // This dir has a layout \u2014 create a layout route with children
+      const LayoutWrapper = createLayoutElement(layouts[dir], dir);
+      let layoutElement = createElement(LayoutWrapper);
+      layoutElement = wrapElement(layoutElement, dir);
+
+      const layoutRoute = createElement(
+        Route,
+        { path: routeSegment, element: layoutElement, key: "layout:" + dir },
+        ...children
+      );
+      dirChildren[parentDir].push(layoutRoute);
+    } else if (children.length > 0) {
+      // No layout \u2014 just a path prefix grouping
+      if (routeSegment) {
+        const prefixRoute = createElement(
+          Route,
+          { path: routeSegment, key: "prefix:" + dir },
+          ...children
+        );
+        dirChildren[parentDir].push(prefixRoute);
+      } else {
+        // Empty segment \u2014 push children directly
+        dirChildren[parentDir].push(...children);
+      }
+    }
+  }
+
+  // Build root routes
+  const rootChildren = dirChildren[""];
+
+  // Add not-found catch-all at the end
+  if (notFound) {
+    rootChildren.push(
+      createElement(Route, { path: "*", element: createElement(notFound), key: "not-found" })
+    );
+  }
+
+  // If root has a layout, wrap everything in it
+  if (layouts[""]) {
+    const RootLayout = createLayoutElement(layouts[""], "");
+    let rootElement = createElement(RootLayout);
+    rootElement = wrapElement(rootElement, "");
+
+    return createElement(
+      Routes,
+      null,
+      createElement(Route, { path: "/", element: rootElement }, ...rootChildren)
+    );
+  }
+
+  // No root layout \u2014 wrap with loading/error if present
+  let routesElement = createElement(Routes, null, ...rootChildren);
+  if (errors[""]) {
+    routesElement = createElement(VoltxErrorBoundary, { fallback: errors[""] }, routesElement);
+  }
+  if (loadings[""]) {
+    routesElement = createElement(Suspense, { fallback: createElement(loadings[""]) }, routesElement);
+  }
+
+  return routesElement;
+}
+
+// \u2500\u2500\u2500 Collect flat routes list (for backward compat) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+function collectRoutes() {
+  const result = [];
+  for (const dirPages of Object.values(pages)) {
+    for (const { routePath, Component } of dirPages) {
+      result.push({ path: routePath, Component });
+    }
+  }
+  return result;
+}
+
+const routes = collectRoutes();
 
 export function VoltxRoutes() {
-  return createElement(
-    Routes,
-    null,
-    routes.map(({ path, Component }) =>
-      createElement(Route, { key: path, path, element: createElement(Component) })
-    )
-  );
+  return buildRouteElements();
 }
 
 export { routes };
 
 // Navigation primitives \u2014 single import source
-export { Link, NavLink, useNavigate, useParams, useLocation, useSearchParams } from "react-router";
+export { Link, NavLink, Outlet, useNavigate, useParams, useLocation, useSearchParams, useOutletContext } from "react-router";
+`;
+}
+
+// src/vite-api-plugin.ts
+function voltxAPI(options = {}) {
+  const apiDir = options.apiDir ?? "api";
+  const PUBLIC_ID = "voltx/api";
+  const RESOLVED_ID = "\0voltx/api";
+  return {
+    name: "voltx-api",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === PUBLIC_ID) {
+        return RESOLVED_ID;
+      }
+    },
+    load(id) {
+      if (id === RESOLVED_ID) {
+        return `
+const modules = import.meta.glob("/${apiDir}/**/*.ts", { eager: true });
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+
+function fileToRoute(filePath) {
+  let route = filePath
+    .replace("/${apiDir}", "/${apiDir}")
+    .replace(/\\.ts$/, "")
+    .replace(/\\/index$/, "");
+
+  // Convert [param] -> :param
+  route = route.replace(/\\[([^\\]\\.]+)\\]/g, ":$1");
+  // Convert [...slug] -> *
+  route = route.replace(/\\[\\.\\.\\.([^\\]]+)\\]/g, "*");
+
+  if (!route || route === "/${apiDir}") route = "/${apiDir}";
+  return route;
+}
+
+export function registerRoutes(app) {
+  const registered = [];
+
+  // Sort: static routes first, dynamic (:param) second, catch-all (*) last
+  const entries = Object.entries(modules).sort(([a], [b]) => {
+    const ra = fileToRoute(a);
+    const rb = fileToRoute(b);
+    const sa = ra.includes("*") ? 2 : ra.includes(":") ? 1 : 0;
+    const sb = rb.includes("*") ? 2 : rb.includes(":") ? 1 : 0;
+    if (sa !== sb) return sa - sb;
+    return ra.localeCompare(rb);
+  });
+
+  for (const [filePath, mod] of entries) {
+    const route = fileToRoute(filePath);
+
+    for (const method of HTTP_METHODS) {
+      const handler = mod[method];
+      if (typeof handler === "function") {
+        app.on(method, route, handler);
+        registered.push({ method, path: route });
+      }
+    }
+  }
+
+  return registered;
+}
+
+export { modules as apiModules };
 `;
       }
     },
+    // HMR: when a file in api/ is added/removed, invalidate the virtual module
     handleHotUpdate({ file, server }) {
-      if (file.includes(pagesDir.replace(/\//g, "/"))) {
+      if (file.includes(`/${apiDir}/`) || file.endsWith(`/${apiDir}`)) {
         const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
         if (mod) {
           server.moduleGraph.invalidateModule(mod);
@@ -532,7 +852,7 @@ ${cssLinks}
 }
 
 // src/index.ts
-var VERSION = "0.4.5";
+var VERSION = "0.4.7";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Hono,
@@ -546,5 +866,6 @@ var VERSION = "0.4.5";
   registerSSR,
   registerStaticFiles,
   scanAndRegisterRoutes,
+  voltxAPI,
   voltxRouter
 });

package/dist/index.d.cts

@@ -185,18 +185,30 @@ interface VoltxRouterOptions {
  * VoltX file-based router plugin for Vite.
  *
  * Scans `src/pages/` and generates a virtual module that maps
- * file paths to routes — just like Next.js.
+ * file paths to routes with nested layout support — like Next.js App Router.
  *
  * Usage:
  *   import { Link, VoltxRoutes, useNavigate } from "voltx/router";
+ */
+declare function voltxRouter(options?: VoltxRouterOptions): Plugin;
+
+interface VoltxAPIOptions {
+    /** Directory to scan for API route files (default: "api") */
+    apiDir?: string;
+}
+/**
+ * VoltX file-based API routing plugin for Vite.
+ *
+ * Usage in server.ts:
+ *   import { registerRoutes } from "voltx/api";
+ *   registerRoutes(app);
  *
  * Convention:
- *   src/pages/index.tsx       → /
- *   src/pages/about.tsx       → /about
- *   src/pages/blog/index.tsx  → /blog
- *   src/pages/blog/[slug].tsx → /blog/:slug
+ *   api/index.ts       → /api
+ *   api/users.ts       → /api/users
+ *   api/users/[id].ts  → /api/users/:id
  */
-declare function voltxRouter(options?: VoltxRouterOptions): Plugin;
+declare function voltxAPI(options?: VoltxAPIOptions): Plugin;
 
 interface SSROptions {
     /** Path to entry-server module (default: src/entry-server.tsx) */
@@ -245,6 +257,6 @@ interface ViteDevServer {
  */
 declare function registerSSR(app: Hono, vite: ViteDevServer | null, options?: SSROptions): void;
 
-declare const VERSION = "0.4.5";
+declare const VERSION = "0.4.7";
 
-export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type SSROptions, type ServerConfig, type ServerInfo, VERSION, type ViteDevOptions, type VoltxRouterOptions, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, createViteDevConfig, filePathToUrlPath, registerSSR, registerStaticFiles, scanAndRegisterRoutes, voltxRouter };
+export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type SSROptions, type ServerConfig, type ServerInfo, VERSION, type ViteDevOptions, type VoltxAPIOptions, type VoltxRouterOptions, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, createViteDevConfig, filePathToUrlPath, registerSSR, registerStaticFiles, scanAndRegisterRoutes, voltxAPI, voltxRouter };

package/dist/index.d.ts

@@ -185,18 +185,30 @@ interface VoltxRouterOptions {
  * VoltX file-based router plugin for Vite.
  *
  * Scans `src/pages/` and generates a virtual module that maps
- * file paths to routes — just like Next.js.
+ * file paths to routes with nested layout support — like Next.js App Router.
  *
  * Usage:
  *   import { Link, VoltxRoutes, useNavigate } from "voltx/router";
+ */
+declare function voltxRouter(options?: VoltxRouterOptions): Plugin;
+
+interface VoltxAPIOptions {
+    /** Directory to scan for API route files (default: "api") */
+    apiDir?: string;
+}
+/**
+ * VoltX file-based API routing plugin for Vite.
+ *
+ * Usage in server.ts:
+ *   import { registerRoutes } from "voltx/api";
+ *   registerRoutes(app);
  *
  * Convention:
- *   src/pages/index.tsx       → /
- *   src/pages/about.tsx       → /about
- *   src/pages/blog/index.tsx  → /blog
- *   src/pages/blog/[slug].tsx → /blog/:slug
+ *   api/index.ts       → /api
+ *   api/users.ts       → /api/users
+ *   api/users/[id].ts  → /api/users/:id
  */
-declare function voltxRouter(options?: VoltxRouterOptions): Plugin;
+declare function voltxAPI(options?: VoltxAPIOptions): Plugin;
 
 interface SSROptions {
     /** Path to entry-server module (default: src/entry-server.tsx) */
@@ -245,6 +257,6 @@ interface ViteDevServer {
  */
 declare function registerSSR(app: Hono, vite: ViteDevServer | null, options?: SSROptions): void;
 
-declare const VERSION = "0.4.5";
+declare const VERSION = "0.4.7";
 
-export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type SSROptions, type ServerConfig, type ServerInfo, VERSION, type ViteDevOptions, type VoltxRouterOptions, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, createViteDevConfig, filePathToUrlPath, registerSSR, registerStaticFiles, scanAndRegisterRoutes, voltxRouter };
+export { type CorsConfig, type HttpMethod, type MiddlewareHandler, type RouteEntry, type RouteHandler, type RouteModule, type SSROptions, type ServerConfig, type ServerInfo, VERSION, type ViteDevOptions, type VoltxAPIOptions, type VoltxRouterOptions, type VoltxServer, createCorsMiddleware, createErrorHandler, createLoggerMiddleware, createServer, createViteDevConfig, filePathToUrlPath, registerSSR, registerStaticFiles, scanAndRegisterRoutes, voltxAPI, voltxRouter };

package/dist/index.js

@@ -286,55 +286,374 @@ function voltxRouter(options = {}) {
     },
     load(id) {
       if (id === RESOLVED_ID) {
-        return `
-import { createElement } from "react";
-import { Routes, Route } from "react-router";
+        return generateRouterModule(pagesDir);
+      }
+    },
+    handleHotUpdate({ file, server }) {
+      if (file.includes(pagesDir.replace(/\//g, "/"))) {
+        const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
+        if (mod) {
+          server.moduleGraph.invalidateModule(mod);
+          server.ws.send({ type: "full-reload" });
+        }
+      }
+    }
+  };
+}
+function generateRouterModule(pagesDir) {
+  return `
+import { createElement, Component, Suspense } from "react";
+import { Routes, Route, Outlet } from "react-router";
+
+// \u2500\u2500\u2500 Glob all files in pages directory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+const allFiles = import.meta.glob("/${pagesDir}/**/*.tsx", { eager: true });
 
-const pages = import.meta.glob("/${pagesDir}/**/*.tsx", { eager: true });
+// \u2500\u2500\u2500 Classify files by type \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Special files: layout.tsx, loading.tsx, error.tsx, not-found.tsx
+// Page files: everything else (index.tsx, about.tsx, [slug].tsx, etc.)
 
-function buildRoutes() {
-  const routes = [];
-  for (const [filePath, mod] of Object.entries(pages)) {
+const SPECIAL_FILES = new Set(["layout", "loading", "error", "not-found"]);
+
+function classifyFiles() {
+  const pages = {};      // dir \u2192 [{ routePath, Component }]
+  const layouts = {};    // dir \u2192 Component
+  const loadings = {};   // dir \u2192 Component
+  const errors = {};     // dir \u2192 Component
+  let notFound = null;   // global not-found component
+
+  for (const [filePath, mod] of Object.entries(allFiles)) {
     const Component = mod.default;
     if (!Component) continue;
 
-    let routePath = filePath
-      .replace("/${pagesDir}", "")
-      .replace(/\\.tsx$/, "")
-      .replace(/\\/index$/, "/")
-      .replace(/\\[([^\\]]+)\\]/g, ":$1");
+    // Get relative path from pages dir: "/src/pages/blog/index.tsx" \u2192 "blog/index.tsx"
+    const rel = filePath.replace("/${pagesDir}/", "");
+    const parts = rel.replace(/\\.tsx$/, "").split("/");
+    const fileName = parts[parts.length - 1];
+    const dir = parts.length > 1 ? parts.slice(0, -1).join("/") : "";
+
+    if (fileName === "layout") {
+      layouts[dir] = Component;
+    } else if (fileName === "loading") {
+      loadings[dir] = Component;
+    } else if (fileName === "error") {
+      errors[dir] = Component;
+    } else if (fileName === "not-found") {
+      if (dir === "") notFound = Component;
+    } else {
+      // It's a page file \u2014 compute route path
+      let routePath = rel
+        .replace(/\\.tsx$/, "")
+        .replace(/(^|\\/)index$/, "$1")
+        .replace(/\\[([^\\]]+)\\]/g, ":$1")
+        .replace(/\\/$/, "");
+
+      if (!routePath) routePath = "";
 
-    if (!routePath.startsWith("/")) routePath = "/" + routePath;
-    if (routePath !== "/" && routePath.endsWith("/")) {
-      routePath = routePath.slice(0, -1);
+      if (!pages[dir]) pages[dir] = [];
+      pages[dir].push({ routePath: "/" + routePath, Component });
     }
+  }
+
+  return { pages, layouts, loadings, errors, notFound };
+}
 
-    routes.push({ path: routePath, Component });
+const { pages, layouts, loadings, errors, notFound } = classifyFiles();
+
+// \u2500\u2500\u2500 Error Boundary Component \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+class VoltxErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error };
   }
-  return routes;
+
+  render() {
+    if (this.state.hasError) {
+      const reset = () => this.setState({ hasError: false, error: null });
+      if (this.props.fallback) {
+        return createElement(this.props.fallback, {
+          error: this.state.error,
+          reset,
+        });
+      }
+      return createElement("div", { style: { padding: "2rem" } },
+        createElement("h2", null, "Something went wrong"),
+        createElement("button", { onClick: reset }, "Try again")
+      );
+    }
+    return this.props.children;
+  }
+}
+
+// \u2500\u2500\u2500 Build nested route tree \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// Directories are sorted so parents come before children.
+// Each directory with a layout.tsx becomes a layout route.
+// Pages within that directory become its children.
+
+function getAllDirs() {
+  const dirs = new Set([""]);
+  for (const dir of Object.keys(pages)) dirs.add(dir);
+  for (const dir of Object.keys(layouts)) dirs.add(dir);
+  for (const dir of Object.keys(loadings)) dirs.add(dir);
+  for (const dir of Object.keys(errors)) dirs.add(dir);
+  return Array.from(dirs).sort((a, b) => {
+    if (a === "") return -1;
+    if (b === "") return 1;
+    return a.localeCompare(b);
+  });
+}
+
+function getParentDir(dir) {
+  if (dir === "") return null;
+  const idx = dir.lastIndexOf("/");
+  return idx === -1 ? "" : dir.substring(0, idx);
+}
+
+// Find the nearest ancestor directory that has a layout
+function findLayoutAncestor(dir) {
+  let current = getParentDir(dir);
+  while (current !== null) {
+    if (layouts[current]) return current;
+    current = getParentDir(current);
+  }
+  return null;
+}
+
+// Wrap element with loading (Suspense) and error boundary if available for a dir
+function wrapElement(element, dir) {
+  let wrapped = element;
+  if (errors[dir]) {
+    wrapped = createElement(VoltxErrorBoundary, { fallback: errors[dir] }, wrapped);
+  }
+  if (loadings[dir]) {
+    wrapped = createElement(Suspense, { fallback: createElement(loadings[dir]) }, wrapped);
+  }
+  return wrapped;
 }
 
-const routes = buildRoutes();
+// \u2500\u2500\u2500 Layout wrapper component \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+// A layout component that renders the layout with <Outlet /> for children
+function createLayoutElement(LayoutComp, dir) {
+  // The layout component receives <Outlet /> as its children rendering point
+  // We create a wrapper that renders Layout with Outlet inside
+  function LayoutWrapper() {
+    return createElement(LayoutComp, null, createElement(Outlet));
+  }
+  LayoutWrapper.displayName = "Layout(" + (dir || "root") + ")";
+  return LayoutWrapper;
+}
+
+// \u2500\u2500\u2500 Generate the <Routes> tree \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+function buildRouteElements() {
+  const allDirs = getAllDirs();
+
+  // Build a tree structure: each dir can have child routes and child layout dirs
+  // dirChildren[dir] = array of Route elements (pages + nested layout routes)
+  const dirChildren = {};
+  for (const dir of allDirs) {
+    dirChildren[dir] = [];
+  }
+
+  // First, add page routes to their directory
+  for (const dir of allDirs) {
+    const dirPages = pages[dir] || [];
+    for (const { routePath, Component: PageComp } of dirPages) {
+      // Compute the path relative to the directory's base
+      const dirBase = dir ? "/" + dir : "";
+      let relativePath = routePath;
+      if (dirBase && relativePath.startsWith(dirBase)) {
+        relativePath = relativePath.substring(dirBase.length);
+      }
+      if (relativePath.startsWith("/")) relativePath = relativePath.substring(1);
+
+      const isIndex = relativePath === "";
+      const routeProps = isIndex
+        ? { index: true, element: createElement(PageComp), key: routePath }
+        : { path: relativePath, element: createElement(PageComp), key: routePath };
+
+      dirChildren[dir].push(createElement(Route, routeProps));
+    }
+  }
+
+  // Now, nest directories bottom-up: child dirs become Route children of parent dirs
+  // Process in reverse order (deepest first)
+  const reversedDirs = allDirs.slice().reverse();
+
+  for (const dir of reversedDirs) {
+    if (dir === "") continue; // root handled last
+
+    const parentDir = getParentDir(dir);
+    if (parentDir === null) continue;
+
+    const hasLayout = !!layouts[dir];
+    const children = dirChildren[dir];
+
+    // Compute path segment for this directory relative to parent
+    const parentBase = parentDir ? parentDir + "/" : "";
+    const segment = dir.startsWith(parentBase) ? dir.substring(parentBase.length) : dir;
+    // Convert [param] to :param in segment
+    const routeSegment = segment.replace(/\\[([^\\]]+)\\]/g, ":$1");
+
+    if (hasLayout) {
+      // This dir has a layout \u2014 create a layout route with children
+      const LayoutWrapper = createLayoutElement(layouts[dir], dir);
+      let layoutElement = createElement(LayoutWrapper);
+      layoutElement = wrapElement(layoutElement, dir);
+
+      const layoutRoute = createElement(
+        Route,
+        { path: routeSegment, element: layoutElement, key: "layout:" + dir },
+        ...children
+      );
+      dirChildren[parentDir].push(layoutRoute);
+    } else if (children.length > 0) {
+      // No layout \u2014 just a path prefix grouping
+      if (routeSegment) {
+        const prefixRoute = createElement(
+          Route,
+          { path: routeSegment, key: "prefix:" + dir },
+          ...children
+        );
+        dirChildren[parentDir].push(prefixRoute);
+      } else {
+        // Empty segment \u2014 push children directly
+        dirChildren[parentDir].push(...children);
+      }
+    }
+  }
+
+  // Build root routes
+  const rootChildren = dirChildren[""];
+
+  // Add not-found catch-all at the end
+  if (notFound) {
+    rootChildren.push(
+      createElement(Route, { path: "*", element: createElement(notFound), key: "not-found" })
+    );
+  }
+
+  // If root has a layout, wrap everything in it
+  if (layouts[""]) {
+    const RootLayout = createLayoutElement(layouts[""], "");
+    let rootElement = createElement(RootLayout);
+    rootElement = wrapElement(rootElement, "");
+
+    return createElement(
+      Routes,
+      null,
+      createElement(Route, { path: "/", element: rootElement }, ...rootChildren)
+    );
+  }
+
+  // No root layout \u2014 wrap with loading/error if present
+  let routesElement = createElement(Routes, null, ...rootChildren);
+  if (errors[""]) {
+    routesElement = createElement(VoltxErrorBoundary, { fallback: errors[""] }, routesElement);
+  }
+  if (loadings[""]) {
+    routesElement = createElement(Suspense, { fallback: createElement(loadings[""]) }, routesElement);
+  }
+
+  return routesElement;
+}
+
+// \u2500\u2500\u2500 Collect flat routes list (for backward compat) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+function collectRoutes() {
+  const result = [];
+  for (const dirPages of Object.values(pages)) {
+    for (const { routePath, Component } of dirPages) {
+      result.push({ path: routePath, Component });
+    }
+  }
+  return result;
+}
+
+const routes = collectRoutes();
 
 export function VoltxRoutes() {
-  return createElement(
-    Routes,
-    null,
-    routes.map(({ path, Component }) =>
-      createElement(Route, { key: path, path, element: createElement(Component) })
-    )
-  );
+  return buildRouteElements();
 }
 
 export { routes };
 
 // Navigation primitives \u2014 single import source
-export { Link, NavLink, useNavigate, useParams, useLocation, useSearchParams } from "react-router";
+export { Link, NavLink, Outlet, useNavigate, useParams, useLocation, useSearchParams, useOutletContext } from "react-router";
+`;
+}
+
+// src/vite-api-plugin.ts
+function voltxAPI(options = {}) {
+  const apiDir = options.apiDir ?? "api";
+  const PUBLIC_ID = "voltx/api";
+  const RESOLVED_ID = "\0voltx/api";
+  return {
+    name: "voltx-api",
+    enforce: "pre",
+    resolveId(id) {
+      if (id === PUBLIC_ID) {
+        return RESOLVED_ID;
+      }
+    },
+    load(id) {
+      if (id === RESOLVED_ID) {
+        return `
+const modules = import.meta.glob("/${apiDir}/**/*.ts", { eager: true });
+
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"];
+
+function fileToRoute(filePath) {
+  let route = filePath
+    .replace("/${apiDir}", "/${apiDir}")
+    .replace(/\\.ts$/, "")
+    .replace(/\\/index$/, "");
+
+  // Convert [param] -> :param
+  route = route.replace(/\\[([^\\]\\.]+)\\]/g, ":$1");
+  // Convert [...slug] -> *
+  route = route.replace(/\\[\\.\\.\\.([^\\]]+)\\]/g, "*");
+
+  if (!route || route === "/${apiDir}") route = "/${apiDir}";
+  return route;
+}
+
+export function registerRoutes(app) {
+  const registered = [];
+
+  // Sort: static routes first, dynamic (:param) second, catch-all (*) last
+  const entries = Object.entries(modules).sort(([a], [b]) => {
+    const ra = fileToRoute(a);
+    const rb = fileToRoute(b);
+    const sa = ra.includes("*") ? 2 : ra.includes(":") ? 1 : 0;
+    const sb = rb.includes("*") ? 2 : rb.includes(":") ? 1 : 0;
+    if (sa !== sb) return sa - sb;
+    return ra.localeCompare(rb);
+  });
+
+  for (const [filePath, mod] of entries) {
+    const route = fileToRoute(filePath);
+
+    for (const method of HTTP_METHODS) {
+      const handler = mod[method];
+      if (typeof handler === "function") {
+        app.on(method, route, handler);
+        registered.push({ method, path: route });
+      }
+    }
+  }
+
+  return registered;
+}
+
+export { modules as apiModules };
 `;
       }
     },
+    // HMR: when a file in api/ is added/removed, invalidate the virtual module
     handleHotUpdate({ file, server }) {
-      if (file.includes(pagesDir.replace(/\//g, "/"))) {
+      if (file.includes(`/${apiDir}/`) || file.endsWith(`/${apiDir}`)) {
         const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
         if (mod) {
           server.moduleGraph.invalidateModule(mod);
@@ -485,7 +804,7 @@ ${cssLinks}
 }
 
 // src/index.ts
-var VERSION = "0.4.5";
+var VERSION = "0.4.7";
 export {
   Hono2 as Hono,
   VERSION,
@@ -498,5 +817,6 @@ export {
   registerSSR,
   registerStaticFiles,
   scanAndRegisterRoutes,
+  voltxAPI,
   voltxRouter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltx/server",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "VoltX Server — Hono-based HTTP server with file-based routing, SSE streaming, and static file serving",
   "type": "module",
   "main": "./dist/index.cjs",