@teamvelix/velix 5.0.2 → 5.0.4

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.