@voltx/cli 0.3.4 → 0.3.6

package/README.md

@@ -11,18 +11,12 @@
 
 ---
 
-Command-line tools for the [VoltX](https://github.com/codewithshail/voltx) framework. Scaffold projects, run the dev server, build for production, and generate code.
+Command-line tools for the [VoltX](https://github.com/codewithshail/voltx) framework. Full-stack dev server (Vite + Hono), production build with SSR, code generation, and project scaffolding.
 
 ## Installation
 
 ```bash
-npm install -g @voltx/cli
-```
-
-Or use directly with npx:
-
-```bash
-npx @voltx/cli dev
+npm install @voltx/cli
 ```
 
 ## Commands
@@ -30,21 +24,23 @@ npx @voltx/cli dev
 ### Development
 
 ```bash
-voltx dev          # Start dev server with hot reload
-voltx build        # Build for production
+voltx dev          # Start Vite dev server with HMR + backend
+voltx build        # Build for production (client + SSR + server)
 voltx start        # Start production server
 ```
 
+`voltx dev` starts a single process that serves both the React frontend and Hono API backend with hot module replacement. No separate frontend/backend servers needed.
+
 ### Create a New Project
 
 ```bash
 voltx create my-app
 voltx create my-app --template chatbot
-voltx create my-app --template rag-app
-voltx create my-app --template agent-app
+voltx create my-app --template agent-app --shadcn
+voltx create my-app --template rag-app --auth jwt
 ```
 
-> For the full interactive experience with tool selection, RAG toggle, and API key management, use `npx create-voltx-app` instead.
+> For the full interactive experience with tool selection, RAG toggle, shadcn/ui, and API key management, use `npx create-voltx-app` instead.
 
 ### Code Generation
 
@@ -52,19 +48,54 @@ voltx create my-app --template agent-app
 voltx generate route api/users      # New API route
 voltx generate agent assistant       # New agent definition
 voltx generate tool search           # New tool for agents
-voltx generate job cleanup           # New background job
 ```
 
-## Templates
+## Build Pipeline
+
+`voltx build` runs a 3-phase build when SSR is detected:
+
+1. **Client build** — Vite builds `src/entry-client.tsx` → `dist/client/`
+2. **SSR build** — Vite builds `src/entry-server.tsx` → `dist/server/`
+3. **Server build** — tsup bundles `server.ts` → `dist/index.js`
+
+Falls back to a 2-phase build (client + server) if no `src/entry-server.tsx` exists.
+
+## Project Structure
+
+All templates generate a full-stack project:
+
+```
+my-app/
+├── api/                    # Backend API routes (file-based routing)
+│   ├── index.ts            # GET /api — health check
+│   ├── chat.ts             # POST /api/chat (chatbot/agent-app)
+│   └── agent.ts            # POST /api/agent (agent-app)
+├── src/                    # Frontend (React + Vite)
+│   ├── app.tsx             # Root component
+│   ├── layout.tsx          # Layout wrapper
+│   ├── globals.css         # Tailwind CSS v4
+│   ├── entry-client.tsx    # Client hydration
+│   ├── entry-server.tsx    # SSR rendering
+│   ├── components/         # React components
+│   ├── hooks/              # Custom hooks
+│   └── lib/                # Utilities (cn() if shadcn enabled)
+├── agents/                 # AI agents (agent-app)
+├── tools/                  # Agent tools (agent-app)
+├── public/                 # Static assets (favicon, robots.txt, manifest)
+├── server.ts               # Hono app entry
+├── vite.config.ts          # Vite + Tailwind + dev server
+├── components.json         # shadcn/ui config (if enabled)
+├── voltx.config.ts         # VoltX config
+└── tsconfig.json           # TypeScript (with @/* path alias)
+```
 
-| Template | What you get | Frontend UI |
-|----------|-------------|-------------|
-| `blank` | Minimal server with file-based routing | — |
-| `chatbot` | Streaming chat + memory | Chat interface |
-| `rag-app` | Document Q&A + vector search | Ingest + query split view |
-| `agent-app` | AI agent with calculator + datetime tools | Chat with tool steps |
+## What's Included
 
-All non-blank templates include a `public/index.html` with a dark-theme Tailwind CSS UI that connects to the backend API routes.
+- **Tailwind CSS v4** — native Vite plugin, no PostCSS config needed
+- **Path aliases** — `@/*` maps to `src/*` in both TypeScript and Vite
+- **shadcn/ui** (optional) — `--shadcn` flag pre-configures `components.json`, `cn()` utility, and CSS variables
+- **React SSR** — streaming server-side rendering via `@voltx/server`
+- **Auto .env loading** — `@voltx/core` loads `.env` files automatically
 
 ## Programmatic Usage
 
@@ -75,6 +106,7 @@ await createProject({
   name: "my-app",
   template: "chatbot",
   auth: "jwt",
+  shadcn: true,
 });
 ```
 

package/dist/build.d.mts

@@ -1,5 +1,5 @@
 interface BuildOptions {
-    /** Entry file (default: src/index.ts) */
+    /** Entry file (default: server.ts or src/index.ts) */
     entry?: string;
     /** Output directory (default: dist) */
     outDir?: string;
@@ -11,8 +11,9 @@ interface BuildOptions {
 /**
  * Build the VoltX app for production.
  *
- * Uses tsup to bundle the server-side TypeScript into a single optimized JS file.
- * If a frontend directory exists (src/frontend), also builds it with Vite.
+ * Detects whether the project is full-stack (has vite.config.ts or server.ts).
+ * - Full-stack: builds client bundle, SSR bundle, and server bundle
+ * - API-only: builds server bundle only (existing behavior)
  */
 declare function runBuild(options?: BuildOptions): Promise<void>;
 

package/dist/build.d.ts

@@ -1,5 +1,5 @@
 interface BuildOptions {
-    /** Entry file (default: src/index.ts) */
+    /** Entry file (default: server.ts or src/index.ts) */
     entry?: string;
     /** Output directory (default: dist) */
     outDir?: string;
@@ -11,8 +11,9 @@ interface BuildOptions {
 /**
  * Build the VoltX app for production.
  *
- * Uses tsup to bundle the server-side TypeScript into a single optimized JS file.
- * If a frontend directory exists (src/frontend), also builds it with Vite.
+ * Detects whether the project is full-stack (has vite.config.ts or server.ts).
+ * - Full-stack: builds client bundle, SSR bundle, and server bundle
+ * - API-only: builds server bundle only (existing behavior)
  */
 declare function runBuild(options?: BuildOptions): Promise<void>;
 

package/dist/build.js

@@ -26,6 +26,7 @@ module.exports = __toCommonJS(build_exports);
 var import_node_child_process = require("child_process");
 var import_node_path = require("path");
 var import_node_fs = require("fs");
+var import_core = require("@voltx/core");
 async function runBuild(options = {}) {
   const cwd = process.cwd();
   const {
@@ -35,7 +36,7 @@ async function runBuild(options = {}) {
     sourcemap = false
   } = options;
   if (!entry) {
-    console.error("[voltx] Could not find entry point. Expected src/index.ts");
+    console.error("[voltx] Could not find entry point. Expected server.ts or src/index.ts");
     process.exit(1);
   }
   const entryPath = (0, import_node_path.resolve)(cwd, entry);
@@ -43,59 +44,87 @@ async function runBuild(options = {}) {
     console.error(`[voltx] Entry file not found: ${entry}`);
     process.exit(1);
   }
+  (0, import_core.loadEnv)("production", cwd);
+  const hasViteConfig = (0, import_node_fs.existsSync)((0, import_node_path.resolve)(cwd, "vite.config.ts"));
+  const hasServerEntry = (0, import_node_fs.existsSync)((0, import_node_path.resolve)(cwd, "server.ts"));
+  const isFullStack = hasViteConfig || hasServerEntry;
   console.log("");
   console.log("  \u26A1 VoltX Build");
   console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   console.log(`  Entry:   ${entry}`);
   console.log(`  Output:  ${outDir}/`);
+  console.log(`  Mode:    ${isFullStack ? "full-stack" : "API-only"}`);
   console.log(`  Minify:  ${minify}`);
   console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   console.log("");
   (0, import_node_fs.mkdirSync)((0, import_node_path.resolve)(cwd, outDir), { recursive: true });
-  console.log("  [1/2] Building server...");
+  if (isFullStack) {
+    await buildFullStack(cwd, entry, outDir, minify, sourcemap);
+  } else {
+    await buildApiOnly(cwd, entry, outDir, minify, sourcemap);
+  }
+  console.log("");
+  console.log("  \u26A1 Build complete!");
+  console.log(`  Run \`voltx start\` to start the production server.`);
+  console.log("");
+}
+async function buildFullStack(cwd, entry, outDir, minify, sourcemap) {
+  const ssrEntry = (0, import_node_fs.existsSync)((0, import_node_path.join)(cwd, "src", "entry-server.tsx")) ? "src/entry-server.tsx" : null;
+  const totalSteps = ssrEntry ? 3 : 2;
+  console.log(`  [1/${totalSteps}] Building client...`);
+  const viteBin = findBin(cwd, "vite");
+  const clientOutDir = (0, import_node_path.join)(outDir, "client");
+  await runCommand(
+    viteBin ?? "npx",
+    viteBin ? ["build", "--outDir", clientOutDir] : ["vite", "build", "--outDir", clientOutDir],
+    cwd
+  );
+  console.log("  \u2713 Client built");
+  if (ssrEntry) {
+    console.log(`  [2/${totalSteps}] Building SSR bundle...`);
+    const serverOutDir = (0, import_node_path.join)(outDir, "server");
+    await runCommand(
+      viteBin ?? "npx",
+      viteBin ? ["build", "--ssr", ssrEntry, "--outDir", serverOutDir] : ["vite", "build", "--ssr", ssrEntry, "--outDir", serverOutDir],
+      cwd
+    );
+    console.log("  \u2713 SSR bundle built");
+  }
+  const serverStep = ssrEntry ? 3 : 2;
+  console.log(`  [${serverStep}/${totalSteps}] Building server...`);
+  await buildServer(cwd, entry, outDir, minify, sourcemap, false);
+  console.log("  \u2713 Server built");
+}
+async function buildApiOnly(cwd, entry, outDir, minify, sourcemap) {
+  console.log("  [1/1] Building server...");
+  await buildServer(cwd, entry, outDir, minify, sourcemap);
+  console.log("  \u2713 Server built");
+}
+async function buildServer(cwd, entry, outDir, minify, sourcemap, clean = true) {
+  const tsupBin = findBin(cwd, "tsup");
   const tsupArgs = [
     entry,
     "--format",
     "esm",
     "--out-dir",
     outDir,
-    "--clean",
     "--target",
-    "node20"
+    "node20",
+    "--no-splitting"
   ];
+  if (clean) tsupArgs.push("--clean");
   if (minify) tsupArgs.push("--minify");
   if (sourcemap) tsupArgs.push("--sourcemap");
-  tsupArgs.push("--no-splitting");
-  const tsupBin = findBin(cwd, "tsup");
   await runCommand(
     tsupBin ?? "npx",
     tsupBin ? tsupArgs : ["tsup", ...tsupArgs],
     cwd
   );
-  console.log("  \u2713 Server built successfully");
-  const frontendDir = (0, import_node_path.resolve)(cwd, "src", "frontend");
-  const viteConfig = (0, import_node_path.resolve)(cwd, "vite.config.ts");
-  const hasFrontend = (0, import_node_fs.existsSync)(frontendDir) || (0, import_node_fs.existsSync)(viteConfig);
-  if (hasFrontend) {
-    console.log("  [2/2] Building frontend...");
-    const viteBin = findBin(cwd, "vite");
-    const viteArgs = ["build", "--outDir", (0, import_node_path.join)(outDir, "public")];
-    await runCommand(
-      viteBin ?? "npx",
-      viteBin ? viteArgs : ["vite", ...viteArgs],
-      cwd
-    );
-    console.log("  \u2713 Frontend built successfully");
-  } else {
-    console.log("  [2/2] No frontend found, skipping...");
-  }
-  console.log("");
-  console.log("  \u26A1 Build complete!");
-  console.log(`  Run \`voltx start\` to start the production server.`);
-  console.log("");
 }
 function findEntryPoint(cwd) {
   const candidates = [
+    "server.ts",
+    "server.js",
     "src/index.ts",
     "src/index.js",
     "src/index.mts",

package/dist/build.mjs

@@ -1,7 +1,6 @@
 import {
   runBuild
-} from "./chunk-ZB2F3WTS.mjs";
-import "./chunk-Y6FXYEAI.mjs";
+} from "./chunk-H2DTIOEO.mjs";
 export {
   runBuild
 };