@teamvelix/velix 5.0.2 → 5.0.3

package/README.md

@@ -21,7 +21,11 @@ Velix is a lightweight but powerful React 19 framework featuring file-based rout
 - 📦 **Edge Ready** — Deploy to any edge platform
 - 🤖 **AI Assistant** — Built-in CLI AI for code generation
 
-## 📦 Quick Start
+## 📦 Installation
+
+### Option 1: Create New App (Recommended)
+
+The fastest way to get started:
 
 ```bash
 npx create-velix-app@latest my-app
@@ -30,11 +34,53 @@ npm install
 npm run dev
 ```
 
-Or install manually:
+This will:
+- ✅ Create a new Velix project with your chosen template
+- ✅ Install all dependencies automatically
+- ✅ Set up Tailwind CSS (optional)
+- ✅ Configure TypeScript
+
+### Option 2: Install CLI Globally
+
+For multiple projects or advanced usage:
+
+```bash
+# Install Velix CLI globally
+npm install -g @teamvelix/cli
+
+# Create a new project
+velix create my-app
+cd my-app
+npm install
+
+# Start development
+velix dev
+```
+
+### Option 3: Manual Installation
+
+Add Velix to an existing project:
 
 ```bash
+# Install core framework
 npm install @teamvelix/velix react react-dom
-npm install -D @teamvelix/cli typescript
+
+# Install dev dependencies
+npm install -D @teamvelix/cli typescript @types/react @types/react-dom
+
+# Optional: Tailwind CSS
+npm install -D tailwindcss postcss autoprefixer
+```
+
+Then create a `velix.config.ts` file:
+
+```ts
+import { defineConfig } from "@teamvelix/velix";
+
+export default defineConfig({
+  app: { name: "My App" },
+  server: { port: 3000 },
+});
 ```
 
 ## 📁 Project Structure
@@ -83,24 +129,51 @@ export default defineConfig({
 
 ## 🛠️ CLI Commands
 
+### Development
+
 ```bash
-velix dev          # Start dev server
+velix dev          # Start development server with hot reload
 velix build        # Build for production
 velix start        # Start production server
-velix doctor       # Health check
+velix doctor       # Health check & diagnostics
+velix info         # Framework & environment info
+```
 
-velix g page <name>        # Generate a page
+### Generators
+
+```bash
+velix g page <name>        # Generate a new page
 velix g component <name>   # Generate a component
 velix g api <name>         # Generate an API route
 velix g layout <name>      # Generate a layout
+velix g action <name>      # Generate a server action
 velix g middleware <name>  # Generate middleware
+velix g hook <name>        # Generate a custom hook
+velix g context <name>     # Generate a React context
+```
+
+### Project Creation
 
-velix ai start     # Launch AI assistant
-velix analyze      # Bundle analysis
-velix info         # Framework info
+```bash
+velix create <name>                    # Create new project (interactive)
+velix create <name> --template=minimal # Use minimal template
+velix create <name> --no-tailwind      # Skip Tailwind CSS
 ```
 
-## � Documentation
+### UI Components (Shadcn-style)
+
+```bash
+velix ui add button        # Add button component
+# More components coming soon
+```
+
+### Other
+
+```bash
+velix analyze      # Bundle analysis (coming soon)
+```
+
+## 📚 Documentation
 
 Comprehensive guides and API references:
 
@@ -110,6 +183,52 @@ Comprehensive guides and API references:
 - **[Best Practices](./docs/best-practices.md)** - Development guidelines
 - **[Roadmap](./docs/roadmap.md)** - Upcoming features and plugins
 
+## 🔧 Troubleshooting
+
+### Common Issues
+
+**Module not found errors:**
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+**Tailwind CSS not working:**
+```bash
+# Ensure Tailwind is installed
+npm install -D tailwindcss postcss autoprefixer
+
+# Check that velix.config.ts includes tailwindPlugin
+import { defineConfig, tailwindPlugin } from "@teamvelix/velix";
+
+export default defineConfig({
+  plugins: [tailwindPlugin()]
+});
+```
+
+**Port already in use:**
+```bash
+# Change port in velix.config.ts
+export default defineConfig({
+  server: { port: 3001 }
+});
+```
+
+### Getting Help
+
+- 📖 Check the [documentation](./docs/README.md)
+- 💬 Join our [Discord community](https://discord.gg/velix)
+- 🐛 Report bugs on [GitHub Issues](https://github.com/Velixteam/velix/issues)
+
+## 📦 NPM Packages
+
+| Package | Version | Description |
+|---------|---------|-------------|
+| [@teamvelix/velix](https://npmjs.com/package/@teamvelix/velix) | ![npm](https://img.shields.io/npm/v/@teamvelix/velix) | Core framework |
+| [create-velix-app](https://npmjs.com/package/create-velix-app) | ![npm](https://img.shields.io/npm/v/create-velix-app) | Project scaffolding |
+| [@teamvelix/cli](https://npmjs.com/package/@teamvelix/cli) | ![npm](https://img.shields.io/npm/v/@teamvelix/cli) | Command-line interface |
+
 ## 🤝 Contributing
 
 We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

package/dist/index.js

@@ -22,8 +22,8 @@ var image_optimizer_exports = {};
 __export(image_optimizer_exports, {
   handleImageOptimization: () => handleImageOptimization
 });
-import fs6 from "fs";
-import path7 from "path";
+import fs7 from "fs";
+import path8 from "path";
 async function handleImageOptimization(req, res, projectRoot) {
   let sharp;
   try {
@@ -48,14 +48,14 @@ async function handleImageOptimization(req, res, projectRoot) {
       if (!response.ok) throw new Error(`Failed to fetch ${imageUrl}`);
       imageBuffer = Buffer.from(await response.arrayBuffer());
     } else {
-      const publicDir = path7.join(projectRoot, "public");
-      const resolvedPath = path7.join(publicDir, imageUrl.startsWith("/") ? imageUrl.slice(1) : imageUrl);
-      if (!resolvedPath.startsWith(publicDir) || !fs6.existsSync(resolvedPath)) {
+      const publicDir = path8.join(projectRoot, "public");
+      const resolvedPath = path8.join(publicDir, imageUrl.startsWith("/") ? imageUrl.slice(1) : imageUrl);
+      if (!resolvedPath.startsWith(publicDir) || !fs7.existsSync(resolvedPath)) {
         res.writeHead(404);
         res.end("Image not found");
         return;
       }
-      imageBuffer = fs6.readFileSync(resolvedPath);
+      imageBuffer = fs7.readFileSync(resolvedPath);
     }
     if (!sharp) {
       res.writeHead(200, {
@@ -715,8 +715,8 @@ function buildTree(routes) {
 // server/index.ts
 init_esm_shims();
 import http from "http";
-import fs7 from "fs";
-import path8 from "path";
+import fs8 from "fs";
+import path9 from "path";
 import { fileURLToPath as fileURLToPath2, pathToFileURL as pathToFileURL3 } from "url";
 import React2 from "react";
 import { renderToString } from "react-dom/server";
@@ -1026,6 +1026,8 @@ var builtinPlugins = {
 // plugins/tailwind.ts
 init_esm_shims();
 import { spawnSync, spawn } from "child_process";
+import fs6 from "fs";
+import path7 from "path";
 
 // logger.ts
 init_esm_shims();
@@ -1077,14 +1079,14 @@ var logger = {
     if (pagesDir) console.log(`  ${c.bold}App:${c.reset}        ${c.dim}${pagesDir}${c.reset}`);
     console.log("");
   },
-  request(method, path10, status, time, extra = {}) {
+  request(method, path11, status, time, extra = {}) {
     const statusColor = getStatusColor(status);
     const timeStr = fmtTime(time);
     let badge = `${c.dim}\u25CB${c.reset}`;
     if (extra.type === "dynamic" || extra.type === "ssr") badge = `${c.white}\u0192${c.reset}`;
     else if (extra.type === "api") badge = `${c.cyan}\u03BB${c.reset}`;
     const statusStr = `${statusColor}${status}${c.reset}`;
-    console.log(`  ${badge} ${c.white}${method}${c.reset} ${path10} ${statusStr} ${c.dim}${timeStr}${c.reset}`);
+    console.log(`  ${badge} ${c.white}${method}${c.reset} ${path11} ${statusStr} ${c.dim}${timeStr}${c.reset}`);
   },
   info(msg) {
     console.log(`  ${c.cyan}\u2139${c.reset} ${msg}`);
@@ -1112,10 +1114,10 @@ var logger = {
   plugin(name) {
     console.log(`  ${c.cyan}\u25C6${c.reset} Plugin ${c.dim}${name}${c.reset}`);
   },
-  route(path10, type) {
+  route(path11, type) {
     const typeLabel = type === "api" ? "\u03BB" : type === "dynamic" ? "\u0192" : "\u25CB";
     const color = type === "api" ? c.cyan : type === "dynamic" ? c.white : c.dim;
-    console.log(`  ${color}${typeLabel}${c.reset} ${path10}`);
+    console.log(`  ${color}${typeLabel}${c.reset} ${path11}`);
   },
   divider() {
     console.log(`${c.dim}  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${c.reset}`);
@@ -1173,10 +1175,39 @@ function tailwindPlugin(options = {}) {
       },
       [PluginHooks.SERVER_START]: async (server, isDev) => {
         if (!isDev) return;
+        if (!fs6.existsSync(input)) {
+          logger_default.warn(`Tailwind input file not found: ${input}`);
+          return;
+        }
+        const outputDir = path7.dirname(output);
+        if (!fs6.existsSync(outputDir)) {
+          fs6.mkdirSync(outputDir, { recursive: true });
+        }
+        logger_default.info("Building initial Tailwind CSS...");
+        try {
+          const buildResult = spawnSync("npx", ["tailwindcss", "-i", input, "-o", output], {
+            cwd: process.cwd(),
+            stdio: "pipe"
+          });
+          if (buildResult.error) {
+            logger_default.error("Tailwind CSS not installed. Run: npm install -D tailwindcss");
+            return;
+          }
+          if (buildResult.status !== 0) {
+            const errorMsg = buildResult.stderr?.toString() || "Unknown error";
+            logger_default.error(`Tailwind build failed: ${errorMsg}`);
+            return;
+          }
+          logger_default.success("Tailwind CSS built successfully");
+        } catch (err) {
+          logger_default.error("Failed to build Tailwind CSS", err);
+          return;
+        }
         logger_default.info("Starting Tailwind CSS watcher...");
         const watcher = spawn("npx", ["tailwindcss", "-i", input, "-o", output, "--watch"], {
           stdio: "pipe",
-          cwd: process.cwd()
+          cwd: process.cwd(),
+          shell: false
         });
         watcher.stdout.on("data", (data) => {
           const msg = data.toString().trim();
@@ -1186,7 +1217,7 @@ function tailwindPlugin(options = {}) {
         });
         watcher.stderr.on("data", (data) => {
           const msg = data.toString().trim();
-          if (msg) {
+          if (msg && !msg.includes("warn")) {
             logger_default.warn(`Tailwind: ${msg}`);
           }
         });
@@ -1198,9 +1229,14 @@ function tailwindPlugin(options = {}) {
             logger_default.error(`Tailwind watcher exited with code ${code}`);
           }
         });
-        process.on("exit", () => watcher.kill());
-        process.on("SIGINT", () => watcher.kill());
-        process.on("SIGTERM", () => watcher.kill());
+        const cleanup = () => {
+          if (watcher && !watcher.killed) {
+            watcher.kill();
+          }
+        };
+        process.on("exit", cleanup);
+        process.on("SIGINT", cleanup);
+        process.on("SIGTERM", cleanup);
       }
     }
   });
@@ -2445,7 +2481,7 @@ async function createServer(options = {}) {
   await loadPlugins(projectRoot, config);
   await pluginManager.runHook(PluginHooks.CONFIG, config);
   const middlewareFns = await loadMiddleware(projectRoot);
-  const appDir = config.resolvedAppDir || path8.join(projectRoot, "app");
+  const appDir = config.resolvedAppDir || path9.join(projectRoot, "app");
   const routes = buildRouteTree(appDir);
   await pluginManager.runHook(PluginHooks.ROUTES_LOADED, routes);
   const startTime = Date.now();
@@ -2487,7 +2523,7 @@ async function createServer(options = {}) {
         await serveVelixInternal(pathname, req, res, projectRoot);
         return;
       }
-      const publicDir = config.resolvedPublicDir || path8.join(projectRoot, "public");
+      const publicDir = config.resolvedPublicDir || path9.join(projectRoot, "public");
       if (await serveStaticFile(pathname, publicDir, res, isDev)) {
         if (isDev) logger_default.request(req.method || "GET", pathname, 200, Date.now() - requestStart, { type: "static" });
         return;
@@ -2556,12 +2592,12 @@ async function createServer(options = {}) {
   };
 }
 async function serveStaticFile(pathname, publicDir, res, isDev = false) {
-  const filePath = path8.join(publicDir, pathname);
+  const filePath = path9.join(publicDir, pathname);
   if (!filePath.startsWith(publicDir)) return false;
-  if (!fs7.existsSync(filePath) || fs7.statSync(filePath).isDirectory()) return false;
-  const ext = path8.extname(filePath);
+  if (!fs8.existsSync(filePath) || fs8.statSync(filePath).isDirectory()) return false;
+  const ext = path9.extname(filePath);
   const contentType = MIME_TYPES[ext] || "application/octet-stream";
-  const content = fs7.readFileSync(filePath);
+  const content = fs8.readFileSync(filePath);
   res.writeHead(200, {
     "Content-Type": contentType,
     "Content-Length": content.length,
@@ -2641,8 +2677,8 @@ async function handlePageRoute(route, routes, req, res, url, config, isDev, proj
     let LayoutComponent = ({ children }) => React2.createElement(React2.Fragment, null, children);
     let layoutParams = route.params;
     try {
-      const layoutPath = path8.join(path8.dirname(route.filePath), "layout.tsx");
-      if (fs7.existsSync(layoutPath)) {
+      const layoutPath = path9.join(path9.dirname(route.filePath), "layout.tsx");
+      if (fs8.existsSync(layoutPath)) {
         const layoutMod = await import(`${pathToFileURL3(layoutPath).href}?t=${Date.now()}`);
         if (layoutMod.metadata) {
           metadata = { ...layoutMod.metadata, ...metadata };
@@ -2762,12 +2798,12 @@ async function serveVelixInternal(pathname, req, res, projectRoot) {
   }
   if (pathname === "/__velix/logo.webp") {
     const __filename2 = fileURLToPath2(import.meta.url);
-    const __dirname2 = path8.dirname(__filename2);
-    const fallbackPath = path8.join(path8.dirname(pathToFileURL3(__dirname2).pathname), "..", "assets", "logo.webp");
-    const logoPath = fs7.existsSync(fallbackPath) ? fallbackPath : path8.join(process.cwd(), "node_modules", "velix", "assets", "logo.webp");
-    if (fs7.existsSync(logoPath)) {
+    const __dirname2 = path9.dirname(__filename2);
+    const fallbackPath = path9.join(path9.dirname(pathToFileURL3(__dirname2).pathname), "..", "assets", "logo.webp");
+    const logoPath = fs8.existsSync(fallbackPath) ? fallbackPath : path9.join(process.cwd(), "node_modules", "velix", "assets", "logo.webp");
+    if (fs8.existsSync(logoPath)) {
       res.writeHead(200, { "Content-Type": "image/webp", "Cache-Control": "public, max-age=31536000, immutable" });
-      res.end(fs7.readFileSync(logoPath));
+      res.end(fs8.readFileSync(logoPath));
     } else {
       res.writeHead(404);
       res.end();
@@ -2778,17 +2814,17 @@ async function serveVelixInternal(pathname, req, res, projectRoot) {
     const componentName = pathname.replace("/__velix/islands/", "").replace(".js", "");
     try {
       const searchDirs = [
-        path8.join(projectRoot, "components"),
-        path8.join(projectRoot, "app"),
-        path8.join(projectRoot, "islands")
+        path9.join(projectRoot, "components"),
+        path9.join(projectRoot, "app"),
+        path9.join(projectRoot, "islands")
       ];
       let componentPath = "";
       for (const dir of searchDirs) {
-        if (!fs7.existsSync(dir)) continue;
-        const files = fs7.readdirSync(dir, { recursive: true });
+        if (!fs8.existsSync(dir)) continue;
+        const files = fs8.readdirSync(dir, { recursive: true });
         const found = files.find((f) => f.replace(/\\/g, "/").endsWith(`${componentName}.tsx`) || f.replace(/\\/g, "/").endsWith(`${componentName}.jsx`));
         if (found) {
-          componentPath = path8.join(dir, found);
+          componentPath = path9.join(dir, found);
           break;
         }
       }
@@ -2868,32 +2904,32 @@ init_esm_shims();
 var CacheManager = class {
   cache = /* @__PURE__ */ new Map();
   tagIndex = /* @__PURE__ */ new Map();
-  set(path10, data, tags = []) {
+  set(path11, data, tags = []) {
     const entry = {
-      path: path10,
+      path: path11,
       tags: new Set(tags),
       timestamp: Date.now(),
       data
     };
-    this.cache.set(path10, entry);
+    this.cache.set(path11, entry);
     tags.forEach((tag) => {
       if (!this.tagIndex.has(tag)) {
         this.tagIndex.set(tag, /* @__PURE__ */ new Set());
       }
-      this.tagIndex.get(tag).add(path10);
+      this.tagIndex.get(tag).add(path11);
     });
   }
-  get(path10) {
-    const entry = this.cache.get(path10);
+  get(path11) {
+    const entry = this.cache.get(path11);
     return entry ? entry.data : null;
   }
-  revalidatePath(path10) {
-    this.cache.delete(path10);
+  revalidatePath(path11) {
+    this.cache.delete(path11);
   }
   revalidateTag(tag) {
     const paths = this.tagIndex.get(tag);
     if (paths) {
-      paths.forEach((path10) => this.cache.delete(path10));
+      paths.forEach((path11) => this.cache.delete(path11));
       this.tagIndex.delete(tag);
     }
   }
@@ -2901,17 +2937,17 @@ var CacheManager = class {
     this.cache.clear();
     this.tagIndex.clear();
   }
-  has(path10) {
-    return this.cache.has(path10);
+  has(path11) {
+    return this.cache.has(path11);
   }
 };
 var cacheManager = new CacheManager();
-function revalidatePath(path10, type = "path") {
-  cacheManager.revalidatePath(path10);
+function revalidatePath(path11, type = "path") {
+  cacheManager.revalidatePath(path11);
   if (typeof global !== "undefined" && global.__VELIX_HMR_SERVER__) {
     global.__VELIX_HMR_SERVER__.broadcast(JSON.stringify({
       type: "revalidate",
-      path: path10,
+      path: path11,
       revalidationType: type
     }));
   }
@@ -3179,8 +3215,8 @@ Image.displayName = "Image";
 // build/index.ts
 init_esm_shims();
 import esbuild2 from "esbuild";
-import fs8 from "fs";
-import path9 from "path";
+import fs9 from "fs";
+import path10 from "path";
 async function build(options = {}) {
   const projectRoot = options.projectRoot || process.cwd();
   const config = await loadConfig(projectRoot);
@@ -3199,7 +3235,7 @@ async function build(options = {}) {
     return;
   }
   try {
-    const serverOutDir = path9.join(outDir, "server");
+    const serverOutDir = path10.join(outDir, "server");
     ensureDir(serverOutDir);
     await esbuild2.build({
       entryPoints: sourceFiles,
@@ -3219,10 +3255,10 @@ async function build(options = {}) {
     process.exit(1);
   }
   try {
-    const clientOutDir = path9.join(outDir, "client");
+    const clientOutDir = path10.join(outDir, "client");
     ensureDir(clientOutDir);
     const clientFiles = sourceFiles.filter((f) => {
-      const content = fs8.readFileSync(f, "utf-8");
+      const content = fs9.readFileSync(f, "utf-8");
       const firstLine = content.split("\n")[0]?.trim();
       return firstLine === "'use client'" || firstLine === '"use client"' || firstLine === "'use island'" || firstLine === '"use island"';
     });
@@ -3248,8 +3284,8 @@ async function build(options = {}) {
     process.exit(1);
   }
   const publicDir = resolved.resolvedPublicDir;
-  if (fs8.existsSync(publicDir)) {
-    const publicOutDir = path9.join(outDir, "public");
+  if (fs9.existsSync(publicDir)) {
+    const publicOutDir = path10.join(outDir, "public");
     ensureDir(publicOutDir);
     copyDirRecursive(publicDir, publicOutDir);
     logger_default.success("Static assets copied");
@@ -3263,7 +3299,7 @@ async function build(options = {}) {
     })),
     api: routes.api.map((r) => ({ path: r.path }))
   };
-  fs8.writeFileSync(path9.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  fs9.writeFileSync(path10.join(outDir, "manifest.json"), JSON.stringify(manifest, null, 2));
   const elapsed = Date.now() - startTime;
   const totalSize = getDirSize(outDir);
   logger_default.blank();
@@ -3281,22 +3317,22 @@ async function build(options = {}) {
 }
 function copyDirRecursive(src, dest) {
   ensureDir(dest);
-  const entries = fs8.readdirSync(src, { withFileTypes: true });
+  const entries = fs9.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path9.join(src, entry.name);
-    const destPath = path9.join(dest, entry.name);
+    const srcPath = path10.join(src, entry.name);
+    const destPath = path10.join(dest, entry.name);
     if (entry.isDirectory()) copyDirRecursive(srcPath, destPath);
-    else fs8.copyFileSync(srcPath, destPath);
+    else fs9.copyFileSync(srcPath, destPath);
   }
 }
 function getDirSize(dir) {
   let size = 0;
-  if (!fs8.existsSync(dir)) return size;
-  const entries = fs8.readdirSync(dir, { withFileTypes: true });
+  if (!fs9.existsSync(dir)) return size;
+  const entries = fs9.readdirSync(dir, { withFileTypes: true });
   for (const entry of entries) {
-    const fullPath = path9.join(dir, entry.name);
+    const fullPath = path10.join(dir, entry.name);
     if (entry.isDirectory()) size += getDirSize(fullPath);
-    else size += fs8.statSync(fullPath).size;
+    else size += fs9.statSync(fullPath).size;
   }
   return size;
 }