@infodb/revx 0.2.2 → 1.0.0

package/README.md

@@ -1,60 +1,124 @@
 # @infodb/revx
 
-Reverse proxy CLI tool with YAML configuration. Built with Express and http-proxy-middleware.
+**Host multiple Vite projects on a single port with unified routing.**
+
+Perfect for monorepo development - run all your Vite apps, backend APIs, and other dev servers together with native HMR support.
+
+## Why revx?
+
+Development in a monorepo with multiple Vite projects is painful:
+- Each Vite app runs on a different port (3000, 3001, 3002...)
+- Cross-app navigation requires hardcoded ports
+- Cookie/session sharing is complicated
+- CORS issues everywhere
+
+**revx solves this** by using Vite's middleware mode to host everything on one port with path-based routing:
+
+```
+http://localhost:3000/app1   → Vite Project 1 (native HMR)
+http://localhost:3000/app2   → Vite Project 2 (native HMR)
+http://localhost:3000/api    → Your Backend API
+http://localhost:3000/legacy → webpack dev server (via proxy)
+```
 
 ## Features
 
-- YAML-based configuration
-- Simple reverse proxy setup
-- **Automatic route sorting** - Routes are automatically sorted by specificity (longest paths first)
-- Load balancing (Round-robin, Random, IP-hash)
-- WebSocket support
-- Request/Response header transformation
-- CORS configuration
-- SSL/TLS support
-- Health checks
-- Request ID tracking
-- Environment variable expansion
+- **🎯 Primary: Multi-Vite hosting** - Native Vite integration with full HMR support
+- **🔌 Reverse proxy** - Integrate webpack, Parcel, or any other dev server
+- **📁 Static file serving** - Serve built assets or documentation
+- **🎨 YAML configuration** - Simple, declarative routing
+- **⚡ Automatic route sorting** - Routes prioritized by specificity
+- **🌐 CORS & environment variables** - Full control over cross-origin and config
 
 ## Installation
 
+### Option 1: Install as dev dependency (Recommended)
+
+```bash
+npm install -D @infodb/revx
+# or
+pnpm add -D @infodb/revx
+```
+
+Then add to package.json scripts:
+```json
+{
+  "scripts": {
+    "dev": "revx start",
+    "dev:verbose": "revx start --verbose"
+  }
+}
+```
+
+### Option 2: Use with npx/pnpx (No installation)
+
+```bash
+npx @infodb/revx start
+# or
+pnpx @infodb/revx start
+```
+
+Good for trying out revx, but slower on repeated runs.
+
+### Option 3: Global installation
+
 ```bash
 npm install -g @infodb/revx
 # or
 pnpm add -g @infodb/revx
-# or
-npx @infodb/revx
 ```
 
 ## Quick Start
 
-1. Create a configuration file:
+1. Install revx in your monorepo:
 
 ```bash
-revx init
+pnpm add -D @infodb/revx
+```
+
+2. Create a configuration file:
+
+```bash
+pnpm revx init
 ```
 
-This creates a `revx.yaml` file with example configuration.
+This creates a `revx.yaml` file with Vite multi-project configuration.
 
-2. Edit `revx.yaml` to configure your routes:
+3. Edit `revx.yaml` to point to your Vite projects:
 
 ```yaml
 server:
   port: 3000
+  maxSockets: 512  # Important for Vite performance
 
 routes:
+  # Your Vite apps
+  - path: "/app1"
+    vite:
+      root: "./apps/app1"
+      base: "/app1"
+
+  - path: "/app2"
+    vite:
+      root: "./apps/app2"
+      base: "/app2"
+
+  # Backend API
   - path: "/api/*"
     target: "http://localhost:4000"
     pathRewrite:
       "^/api": ""
 ```
 
-3. Start the proxy server:
+4. Start the unified dev server:
 
 ```bash
-revx start
+pnpm revx start
+# or add to package.json scripts and run: pnpm dev
 ```
 
+Now all your apps are available at `http://localhost:3000` with full HMR! 🎉
+
 ## Commands
 
 ### `revx start [config-file]`
@@ -119,8 +183,6 @@ routes:
 
 ```yaml
 global:
-  timeout: 30000
-
   # Max concurrent sockets (default: 256)
   # Increase for better performance with dev servers like Vite
   maxSockets: 512
@@ -134,7 +196,6 @@ global:
   logging:
     enabled: true
     format: "combined"  # combined | dev | common | short | tiny
-    level: "info"       # error | warn | info | debug
 ```
 
 ### Performance Tuning
@@ -196,22 +257,50 @@ routes:
       "^/api": ""
 ```
 
-#### Load Balancing
+#### Vite Middleware (NEW!)
+
+Native Vite integration using middleware mode - the best way to serve multiple Vite projects:
 
 ```yaml
 routes:
-  - path: "/balanced/*"
-    targets:
-      - "http://server1.example.com"
-      - "http://server2.example.com"
-      - "http://server3.example.com"
-    strategy: "round-robin"  # round-robin | random | ip-hash
-    pathRewrite:
-      "^/balanced": ""
+  - path: "/app1"
+    vite:
+      root: "./projects/app1"
+      base: "/app1"
+      configFile: "./projects/app1/vite.config.ts"  # optional
+```
+
+**Why use Vite middleware instead of proxy?**
+- Full HMR support without WebSocket configuration
+- No proxy overhead - native Vite performance
+- Multiple Vite projects on a single port
+- Better error messages and development experience
+
+**Requirements:**
+- Vite must be installed: `npm install vite` or `pnpm add vite`
+- Each Vite project must have its own directory with a valid configuration
+
+**Multiple Vite projects example:**
+```yaml
+routes:
+  - path: "/dashboard"
+    vite:
+      root: "./apps/dashboard"
+      base: "/dashboard"
+
+  - path: "/admin"
+    vite:
+      root: "./apps/admin"
+      base: "/admin"
+
+  - path: "/api/*"
+    target: "http://localhost:4000"
 ```
 
 #### WebSocket Proxy
 
+WebSocket support is critical for Hot Module Replacement (HMR) with development servers like Vite:
+
 ```yaml
 routes:
   - path: "/ws"
@@ -220,64 +309,41 @@ routes:
     changeOrigin: true
 ```
 
-#### Header Transformation
+#### Static File Serving
 
-```yaml
-routes:
-  - path: "/transform/*"
-    target: "http://backend.example.com"
-    transform:
-      request:
-        headers:
-          add:
-            X-API-Version: "v2"
-            X-Custom-Header: "value"
-          remove:
-            - "Cookie"
-      response:
-        headers:
-          add:
-            X-Proxy-Server: "revx"
-          remove:
-            - "Server"
-```
-
-#### Custom Options
+Serve static files directly without proxying (useful for `vite build --watch` output):
 
 ```yaml
 routes:
-  - path: "/api/*"
-    target: "http://api.example.com"
-    options:
-      timeout: 5000
-      followRedirects: true
-      headers:
-        X-Forwarded-Host: "${HOST}"
+  - path: "/*"
+    static: "./dist"
 ```
 
-### Middleware
-
+**Combined with API proxy:**
 ```yaml
-middleware:
-  - type: "requestId"
-    enabled: true
-    headerName: "X-Request-ID"
+routes:
+  # API requests go to backend
+  - path: "/api/*"
+    target: "http://localhost:4000"
+    pathRewrite:
+      "^/api": ""
 
-  - type: "compression"
-    enabled: true
-    threshold: 1024
+  # Static files from Vite build
+  - path: "/*"
+    static: "./dist"
 ```
 
-### SSL/TLS
+**Use case: Vite build --watch**
+```bash
+# Terminal 1: Run Vite in build watch mode
+vite build --watch
 
-```yaml
-ssl:
-  enabled: true
-  key: "/path/to/private.key"
-  cert: "/path/to/certificate.crt"
-  ca: "/path/to/ca.crt"  # Optional
+# Terminal 2: Run revx to serve the built files
+revx start
 ```
 
+This serves pre-built static files, avoiding proxy-related errors that can occur with Vite dev server.
+
 ### Environment Variables
 
 Use `${VARIABLE_NAME}` syntax to reference environment variables:
@@ -289,15 +355,12 @@ server:
 routes:
   - path: "/api/*"
     target: "${API_URL}"
-    options:
-      headers:
-        Authorization: "Bearer ${API_TOKEN}"
 ```
 
 Then run:
 
 ```bash
-PORT=3000 API_URL=http://api.example.com API_TOKEN=secret revx start
+PORT=3000 API_URL=http://api.example.com revx start
 ```
 
 ## Examples
@@ -371,62 +434,195 @@ routes:
   # Proxy everything else to Vite dev server
   - path: "/*"
     target: "http://localhost:5173"
-    ws: true
+    ws: true  # Enable WebSocket for HMR
     changeOrigin: true
 ```
 
-### Production Load Balancer
+### Multi-Vite Project Setup (Recommended)
 
 ```yaml
 server:
-  port: 443
-  name: "Production Load Balancer"
+  port: 3000
+  name: "Multi-App Dev Server"
+  maxSockets: 512
 
-ssl:
-  enabled: true
-  key: "/etc/ssl/private/server.key"
-  cert: "/etc/ssl/certs/server.crt"
+global:
+  cors:
+    enabled: true
+    origin: "*"
+
+routes:
+  # App 1 - Customer Portal (Vite)
+  - path: "/portal"
+    vite:
+      root: "./apps/portal"
+      base: "/portal"
+
+  # App 2 - Admin Dashboard (Vite)
+  - path: "/admin"
+    vite:
+      root: "./apps/admin"
+      base: "/admin"
+
+  # Shared API backend
+  - path: "/api/*"
+    target: "http://localhost:4000"
+    pathRewrite:
+      "^/api": ""
+```
+
+This setup allows you to:
+- Run multiple Vite projects on one port
+- Share a single backend API across all apps
+- Get full HMR support for all apps
+- Develop in a monorepo-friendly way
+
+### Mixed Development Servers (Vite + webpack)
+
+Migrate gradually or mix different build tools:
+
+```yaml
+server:
+  port: 3000
+  maxSockets: 512
+
+routes:
+  # New app - using Vite
+  - path: "/new-app"
+    vite:
+      root: "./apps/new-app"
+      base: "/new-app"
+
+  # Legacy app - still on webpack dev server
+  - path: "/legacy/*"
+    target: "http://localhost:8080"
+    ws: true  # Enable WebSocket for webpack HMR
+    changeOrigin: true
+
+  # Another legacy app - using Parcel
+  - path: "/old-dashboard/*"
+    target: "http://localhost:1234"
+    ws: true
+    changeOrigin: true
+
+  # Backend API
+  - path: "/api/*"
+    target: "http://localhost:4000"
+    pathRewrite:
+      "^/api": ""
+
+  # Static documentation
+  - path: "/docs"
+    static: "./public/docs"
+```
+
+**Usage:**
+```bash
+# Terminal 1: Start webpack dev server
+cd apps/legacy && npm run dev  # runs on :8080
+
+# Terminal 2: Start Parcel
+cd apps/old-dashboard && npm run dev  # runs on :1234
+
+# Terminal 3: Start backend
+cd api && npm run dev  # runs on :4000
+
+# Terminal 4: Start revx (unifies everything)
+npx revx start
+```
+
+Now access everything at `http://localhost:3000`:
+- `/new-app` - Vite with native HMR ⚡
+- `/legacy` - webpack via proxy 🔌
+- `/old-dashboard` - Parcel via proxy 🔌
+- `/api` - Backend API 🔌
+- `/docs` - Static files 📁
+
+### Vite Build Watch Mode
+
+```yaml
+server:
+  port: 3000
 
 routes:
+  # Proxy API requests to backend
+  - path: "/api/*"
+    target: "http://localhost:4000"
+    pathRewrite:
+      "^/api": ""
+
+  # Serve static files built by Vite
   - path: "/*"
-    targets:
-      - "http://app-server-1:8080"
-      - "http://app-server-2:8080"
-      - "http://app-server-3:8080"
-    strategy: "round-robin"
-    healthCheck:
-      enabled: true
-      interval: 30000
-      path: "/health"
-      timeout: 3000
+    static: "./dist"
+```
+
+Run with:
+```bash
+# Terminal 1: Build and watch
+vite build --watch
+
+# Terminal 2: Serve with revx
+revx start
 ```
 
 ## Troubleshooting
 
-### CONTENT_LENGTH_MISMATCH Error
+### When to use each route type?
+
+**Vite middleware (`vite` config) - RECOMMENDED for Vite projects:**
+```yaml
+- path: "/app"
+  vite:
+    root: "./apps/myapp"
+```
+- ✅ Best for: Your own Vite projects in the monorepo
+- ✅ Native HMR with no configuration
+- ✅ No proxy overhead
+- ✅ Full Vite dev server features
+
+**Reverse proxy (`target` config) - For external/non-Vite servers:**
+```yaml
+- path: "/legacy"
+  target: "http://localhost:8080"
+  ws: true
+```
+- ✅ Best for: webpack, Parcel, external APIs, legacy apps
+- ✅ Preserve HMR via WebSocket proxy
+- ✅ Don't need to modify the target server
+
+**Static files (`static` config) - For built assets:**
+```yaml
+- path: "/docs"
+  static: "./dist"
+```
+- ✅ Best for: Documentation, pre-built assets, `vite build --watch` output
+- ✅ No processing overhead
+- ✅ Production-like serving
 
-The proxy automatically handles `CONTENT_LENGTH_MISMATCH` errors (common with Vite dev server) by:
+### Common Issues
 
-- **Silently ignoring these errors** in the error handler
-- CONTENT_LENGTH_MISMATCH errors are typically benign with streaming responses
-- The content is usually already successfully delivered to the client
+**Error: "Vite root directory not found"**
+- Check that the `root` path in your config exists
+- Use relative paths from where you run `revx start`
+- Example: If config is in project root, use `./apps/myapp` not `/apps/myapp`
 
-This is especially important for Vite, which dynamically transforms content (ESM conversion, HMR, etc.), causing the actual response size to differ from the original Content-Length header.
+**Multiple Vite servers slow to start**
+- This is normal - each Vite server initializes independently
+- Use `--verbose` to see progress
+- First startup is slower (dependency pre-bundling)
 
-**Technical details:**
-- The error handler checks for `CONTENT_LENGTH_MISMATCH` in error messages
-- These errors are logged only in verbose mode and don't interrupt the response
-- The response has usually completed successfully before the error is detected
-- Works transparently without configuration needed
+**HMR not working for proxied webpack app**
+- Make sure `ws: true` is set in the route config
+- Check that the webpack dev server is actually running
+- Verify WebSocket connection in browser dev tools
+- No additional webpack configuration needed - revx handles WebSocket upgrade automatically
 
-**Why this works:**
-- Vite sends Content-Length based on original file size
-- Vite then transforms the content (ESM imports, HMR injection)
-- The transformed content has a different size
-- By the time the mismatch is detected, the client has already received the content
-- Ignoring the error prevents unnecessary 502 responses
+**Does webpack need special configuration?**
+- No! Just add `ws: true` in revx config
+- revx automatically handles WebSocket upgrade requests
+- Your existing webpack dev server config works as-is
 
-### Performance Issues with Vite or Dev Servers
+### Performance Issues with Dev Servers
 
 If you experience slow loading or timeouts when proxying to Vite or similar dev servers:
 
@@ -454,7 +650,7 @@ If you experience slow loading or timeouts when proxying to Vite or similar dev
 - Only use `pathRewrite` when you need to modify the path
 
 **Q: CORS errors**
-- Enable CORS in global config or per-route
+- Enable CORS in global config
 - Check the `origin` setting matches your client URL
 
 ## Development

package/dist/commands/init.d.ts

@@ -1,5 +1,6 @@
 export declare function initCommand(options: {
     simple?: boolean;
+    proxy?: boolean;
     output?: string;
     verbose?: boolean;
 }): Promise<void>;

package/dist/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA4HA,wBAAsB,WAAW,CAAC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,iBAwBlG"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAuHA,wBAAsB,WAAW,CAAC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,iBAiCnH"}