create-aziz-app 2.0.10 → 2.0.12

package/template/docs/API-ROUTES.md

@@ -0,0 +1,538 @@
+# API Routes Guide
+
+## Overview
+
+API routes run on the **SERVER** (Node.js), just like Next.js! They're real backend endpoints, not client-side mocks.
+
+## How It Works
+
+```
+Browser                    Dev Server (Node.js)
+   │                              │
+   │  GET /api/users              │
+   ├─────────────────────────────►│
+   │                              │ Loads api/users.js
+   │                              │ Executes handler()
+   │                              │
+   │  { users: [...] }            │
+   │◄─────────────────────────────┤
+   │                              │
+```
+
+## Creating an API Route
+
+### File Structure
+
+```
+api/
+├── hello.js       → /api/hello
+├── users.js       → /api/users
+└── posts.js       → /api/posts
+```
+
+Each file in `api/` becomes an endpoint!
+
+### Basic Example
+
+```javascript
+// api/hello.js
+
+module.exports = async function handler(req, res) {
+    return res.status(200).json({
+        message: 'Hello from the server!'
+    });
+};
+```
+
+### Request Object
+
+The `req` object contains:
+
+```javascript
+{
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    body: {},           // Parsed JSON body
+    query: {},          // URL query parameters
+    headers: {},        // Request headers
+    url: '/api/users?id=1'
+}
+```
+
+### Response Object
+
+The `res` object has these methods:
+
+```javascript
+// Set status code
+res.status(200)
+
+// Send JSON response
+res.json({ data: 'value' })
+
+// Send text response
+res.send('Hello')
+
+// Set custom header
+res.setHeader('X-Custom', 'value')
+
+// Chain methods
+res.status(201).json({ created: true })
+```
+
+## Examples
+
+### GET Request
+
+```javascript
+// api/users.js
+
+const users = [
+    { id: 1, name: 'Aziz' },
+    { id: 2, name: 'John' }
+];
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'GET') {
+        // Get specific user
+        if (req.query.id) {
+            const user = users.find(u => u.id === parseInt(req.query.id));
+            if (user) {
+                return res.status(200).json(user);
+            }
+            return res.status(404).json({ error: 'User not found' });
+        }
+        
+        // Get all users
+        return res.status(200).json(users);
+    }
+    
+    return res.status(405).json({ error: 'Method not allowed' });
+};
+```
+
+**Usage:**
+```javascript
+// Get all users
+const response = await fetchApi('/api/users');
+const users = await response.json();
+
+// Get specific user
+const response = await fetchApi('/api/users?id=1');
+const user = await response.json();
+```
+
+### POST Request
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'POST') {
+        const { name, email } = req.body;
+        
+        // Validate
+        if (!name || !email) {
+            return res.status(400).json({ 
+                error: 'Name and email are required' 
+            });
+        }
+        
+        // Create user
+        const newUser = {
+            id: Date.now(),
+            name,
+            email
+        };
+        
+        return res.status(201).json(newUser);
+    }
+};
+```
+
+**Usage:**
+```javascript
+const response = await fetchApi('/api/users', {
+    method: 'POST',
+    body: JSON.stringify({
+        name: 'Aziz',
+        email: 'aziz@example.com'
+    })
+});
+const user = await response.json();
+```
+
+### PUT Request
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'PUT') {
+        const userId = req.query.id;
+        const updates = req.body;
+        
+        // Update user logic here
+        
+        return res.status(200).json({ 
+            message: 'User updated',
+            user: updatedUser 
+        });
+    }
+};
+```
+
+**Usage:**
+```javascript
+const response = await fetchApi('/api/users?id=1', {
+    method: 'PUT',
+    body: JSON.stringify({
+        name: 'New Name'
+    })
+});
+```
+
+### DELETE Request
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'DELETE') {
+        const userId = req.query.id;
+        
+        // Delete user logic here
+        
+        return res.status(200).json({ 
+            message: 'User deleted' 
+        });
+    }
+};
+```
+
+**Usage:**
+```javascript
+const response = await fetchApi('/api/users?id=1', {
+    method: 'DELETE'
+});
+```
+
+### Multiple Methods
+
+```javascript
+// api/users.js
+
+module.exports = async function handler(req, res) {
+    switch (req.method) {
+        case 'GET':
+            // Handle GET
+            return res.status(200).json({ method: 'GET' });
+            
+        case 'POST':
+            // Handle POST
+            return res.status(201).json({ method: 'POST' });
+            
+        case 'PUT':
+            // Handle PUT
+            return res.status(200).json({ method: 'PUT' });
+            
+        case 'DELETE':
+            // Handle DELETE
+            return res.status(200).json({ method: 'DELETE' });
+            
+        default:
+            return res.status(405).json({ 
+                error: 'Method not allowed' 
+            });
+    }
+};
+```
+
+## Using in Components
+
+### Basic Fetch
+
+```jsx
+function MyComponent() {
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(false);
+    
+    const loadData = async () => {
+        setLoading(true);
+        try {
+            const response = await fetchApi('/api/users');
+            const users = await response.json();
+            setData(users);
+        } catch (error) {
+            console.error('Error:', error);
+        }
+        setLoading(false);
+    };
+    
+    return (
+        <div>
+            <button onClick={loadData}>Load Users</button>
+            {loading && <p>Loading...</p>}
+            {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+        </div>
+    );
+}
+```
+
+### With Error Handling
+
+```jsx
+const [error, setError] = useState(null);
+
+const loadData = async () => {
+    try {
+        const response = await fetchApi('/api/users');
+        
+        if (!response.ok) {
+            throw new Error('Failed to fetch');
+        }
+        
+        const users = await response.json();
+        setData(users);
+        setError(null);
+    } catch (err) {
+        setError(err.message);
+        setData(null);
+    }
+};
+```
+
+## Database Integration
+
+### Using a Real Database
+
+```javascript
+// api/users.js
+
+// Example with a database (you need to install the package)
+// npm install better-sqlite3
+
+const Database = require('better-sqlite3');
+const db = new Database('mydb.sqlite');
+
+module.exports = async function handler(req, res) {
+    if (req.method === 'GET') {
+        const users = db.prepare('SELECT * FROM users').all();
+        return res.status(200).json(users);
+    }
+    
+    if (req.method === 'POST') {
+        const { name, email } = req.body;
+        const result = db.prepare(
+            'INSERT INTO users (name, email) VALUES (?, ?)'
+        ).run(name, email);
+        
+        return res.status(201).json({ 
+            id: result.lastInsertRowid,
+            name,
+            email
+        });
+    }
+};
+```
+
+### Using External APIs
+
+```javascript
+// api/weather.js
+
+module.exports = async function handler(req, res) {
+    const city = req.query.city || 'London';
+    
+    try {
+        const response = await fetch(
+            `https://api.openweathermap.org/data/2.5/weather?q=${city}&appid=YOUR_KEY`
+        );
+        const data = await response.json();
+        
+        return res.status(200).json(data);
+    } catch (error) {
+        return res.status(500).json({ 
+            error: 'Failed to fetch weather' 
+        });
+    }
+};
+```
+
+## Environment Variables
+
+```javascript
+// api/config.js
+
+module.exports = async function handler(req, res) {
+    // Access environment variables
+    const apiKey = process.env.API_KEY;
+    const dbUrl = process.env.DATABASE_URL;
+    
+    return res.status(200).json({
+        hasApiKey: !!apiKey,
+        hasDbUrl: !!dbUrl
+    });
+};
+```
+
+Set environment variables:
+```bash
+# Windows
+set API_KEY=your_key
+npm run dev
+
+# Mac/Linux
+API_KEY=your_key npm run dev
+```
+
+## Hot Reload
+
+API routes support hot reload! When you save an API file:
+
+1. Dev server detects the change
+2. Reloads the API handler
+3. Next request uses the new code
+4. No server restart needed!
+
+## CORS
+
+CORS is automatically enabled for all API routes:
+```
+Access-Control-Allow-Origin: *
+Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
+Access-Control-Allow-Headers: Content-Type
+```
+
+## Error Handling
+
+### Server Errors
+
+```javascript
+module.exports = async function handler(req, res) {
+    try {
+        // Your code here
+        const data = await someAsyncOperation();
+        return res.status(200).json(data);
+    } catch (error) {
+        console.error('API Error:', error);
+        return res.status(500).json({ 
+            error: 'Internal server error',
+            message: error.message
+        });
+    }
+};
+```
+
+### Validation Errors
+
+```javascript
+module.exports = async function handler(req, res) {
+    if (req.method === 'POST') {
+        const { name, email } = req.body;
+        
+        if (!name) {
+            return res.status(400).json({ 
+                error: 'Name is required' 
+            });
+        }
+        
+        if (!email || !email.includes('@')) {
+            return res.status(400).json({ 
+                error: 'Valid email is required' 
+            });
+        }
+        
+        // Process valid data
+    }
+};
+```
+
+## Status Codes
+
+Common HTTP status codes:
+
+- `200` - OK (successful GET, PUT, DELETE)
+- `201` - Created (successful POST)
+- `400` - Bad Request (validation error)
+- `401` - Unauthorized (authentication required)
+- `403` - Forbidden (no permission)
+- `404` - Not Found (resource doesn't exist)
+- `405` - Method Not Allowed (wrong HTTP method)
+- `500` - Internal Server Error (server error)
+
+## Best Practices
+
+### 1. Always Handle Methods
+
+```javascript
+module.exports = async function handler(req, res) {
+    if (req.method === 'GET') {
+        // Handle GET
+    } else {
+        return res.status(405).json({ 
+            error: 'Method not allowed' 
+        });
+    }
+};
+```
+
+### 2. Validate Input
+
+```javascript
+if (!req.body.name || typeof req.body.name !== 'string') {
+    return res.status(400).json({ error: 'Invalid name' });
+}
+```
+
+### 3. Use Try-Catch
+
+```javascript
+try {
+    const data = await database.query();
+    return res.status(200).json(data);
+} catch (error) {
+    return res.status(500).json({ error: error.message });
+}
+```
+
+### 4. Return Early
+
+```javascript
+if (!user) {
+    return res.status(404).json({ error: 'Not found' });
+}
+
+// Continue with logic
+```
+
+### 5. Use Async/Await
+
+```javascript
+module.exports = async function handler(req, res) {
+    const data = await fetchData();
+    return res.status(200).json(data);
+};
+```
+
+## Comparison with Next.js
+
+| Feature | Aziz App | Next.js |
+|---------|----------|---------|
+| File-based routing | ✅ | ✅ |
+| Server-side execution | ✅ | ✅ |
+| Hot reload | ✅ | ✅ |
+| Request/Response API | ✅ | ✅ |
+| Dynamic routes | ❌ | ✅ |
+| Middleware | ❌ | ✅ |
+| Edge runtime | ❌ | ✅ |
+
+## Summary
+
+- API routes run on the **server** (Node.js)
+- Each file in `api/` becomes an endpoint
+- Use `module.exports` to export the handler
+- Access via `fetchApi('/api/routename')`
+- Supports GET, POST, PUT, DELETE
+- Hot reload enabled
+- CORS enabled by default
+- Just like Next.js API routes!

package/template/docs/DEV-SERVER.md

@@ -2,15 +2,16 @@
 
 ## Overview
 
-The dev server provides a smooth development experience with live reload, automatic import generation, and file watching.
+The dev server provides a smooth development experience with live reload using WebSocket, automatic import generation, and file watching.
 
 ## Features
 
-### 🔄 Live Reload
+### 🔄 Live Reload (WebSocket-based)
 - **Automatic browser refresh** when you save files
 - **Visual indicator** in bottom-right corner shows connection status
-- **Smart caching** - forces cache clear on reload to always show latest changes
+- **WebSocket connection** - reliable, fast, no caching issues
 - **CSS hot reload** - instant updates without regenerating imports
+- **Always loaded** - script is part of your HTML, not injected
 
 ### 👀 File Watching
 The dev server watches these directories:
@@ -41,22 +42,36 @@ Then open the URL shown in console (usually `http://localhost:3000/`)
 ## Visual Indicators
 
 The live reload indicator in the bottom-right corner shows:
-- 🔌 **Connecting...** - Initial connection
-- ✅ **Live Reload Active** - Connected and watching (fades after 2s)
-- 🔄 **Reloading...** - Changes detected, refreshing page
-- ⚠️ **Reconnecting...** - Connection lost, attempting to reconnect
+- 🔌 **Connecting...** - Initial connection (gray/green)
+- ✅ **Live Reload** - Connected and watching (green, fades to 30%)
+- 🔄 **Reloading...** - Changes detected, refreshing page (blue)
+- ⚠️ **Disconnected** - Connection lost, attempting to reconnect (orange)
+- ❌ **Offline** - Max reconnection attempts reached (red)
+
+**Click the indicator** to manually reload the page.
 
 Hover over the indicator to make it fully visible.
 
 ## How It Works
 
 1. **Server starts** and generates initial imports
-2. **Browser connects** via Server-Sent Events (SSE)
-3. **File watcher** detects changes in watched directories
-4. **Debouncing** prevents multiple rapid reloads (300ms for CSS, 500ms for JS)
-5. **Import regeneration** (for JS/JSX changes only)
-6. **Browser notification** via SSE
-7. **Page reload** with cache busting
+2. **Browser loads** `live-reload-client.js` (always in HTML)
+3. **WebSocket connects** to dev server
+4. **File watcher** detects changes in watched directories
+5. **Debouncing** prevents multiple rapid reloads (300ms for CSS, 500ms for JS)
+6. **Import regeneration** (for JS/JSX changes only)
+7. **WebSocket message** sent to all connected browsers
+8. **Page reload** happens immediately
+
+## Why WebSocket?
+
+Previous versions used Server-Sent Events (SSE) with runtime injection, which had caching issues. The new approach:
+
+- ✅ **Always loaded** - Script is in HTML, not injected at runtime
+- ✅ **No caching issues** - Browser always has the script
+- ✅ **Bidirectional** - WebSocket allows two-way communication
+- ✅ **Reliable** - Built-in reconnection logic
+- ✅ **Fast** - Instant notifications, no polling
 
 ## Cache Control
 
@@ -67,28 +82,52 @@ Pragma: no-cache
 Expires: 0
 ```
 
-This ensures you always see the latest changes without needing Ctrl+Shift+R.
+Plus, `app.html` has meta tags:
+```html
+<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
+<meta http-equiv="Pragma" content="no-cache">
+<meta http-equiv="Expires" content="0">
+```
 
 ## Troubleshooting
 
+### Indicator stuck on "Connecting..."?
+
+1. **Check dev server is running** - Terminal should show "✅ Dev server running"
+2. **Check browser console** (F12) - Look for WebSocket errors
+3. **Check port** - Browser URL should match server URL
+4. **Firewall** - Allow Node.js through firewall
+5. **Try different browser** - Rule out browser-specific issues
+
 ### Changes not showing?
-1. Check the visual indicator - is it green?
-2. Open browser console - look for "✅ Live reload connected"
-3. Check terminal - does it show "🔄 Notifying X browser(s) to reload..."?
-4. Try hard refresh once: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
+
+1. **Check indicator is green** - "✅ Live Reload"
+2. **Check terminal** - Should show "📝 Detected change: ..."
+3. **Check file was saved** - No unsaved indicator in editor
+4. **Check file location** - Must be in watched directories
+5. **Check for errors** - Browser console (F12) for JavaScript errors
+
+### WebSocket connection failed?
+
+1. **Port mismatch** - Check browser URL matches server port
+2. **Proxy/VPN** - May block WebSocket connections
+3. **Browser extension** - Ad blockers can interfere
+4. **Try incognito mode** - Rule out extensions
 
 ### Port already in use?
-The server will automatically try the next port (3001, 3002, etc.)
 
-### Live reload disconnected?
-The page will automatically try to reconnect after 2 seconds.
+The server automatically tries the next port. Check terminal for actual port:
+```
+🌐 Server running at http://localhost:3001/
+```
 
 ## Performance
 
 - **Debouncing** prevents reload spam when saving multiple files
 - **CSS-only changes** skip import regeneration for faster updates
-- **SSE connection** is lightweight and efficient
+- **WebSocket** is lightweight and efficient
 - **Multiple browsers** can connect simultaneously
+- **Automatic reconnection** if connection drops
 
 ## Development Tips
 
@@ -96,3 +135,50 @@ The page will automatically try to reconnect after 2 seconds.
 2. The visual indicator helps confirm live reload is working
 3. CSS changes are faster than JS changes (no import regeneration)
 4. Multiple browser tabs will all reload simultaneously
+5. Click the indicator to manually reload if needed
+
+## Production
+
+The live reload script only runs in development (localhost). In production:
+- Script detects non-localhost hostname
+- Exits immediately without connecting
+- No performance impact
+- No visual indicator
+
+## Technical Details
+
+### WebSocket Protocol
+
+The dev server implements a simple WebSocket server without external dependencies:
+- Uses Node.js `http` module's `upgrade` event
+- Performs WebSocket handshake manually
+- Sends text frames to connected clients
+- Handles connection cleanup automatically
+
+### Message Format
+
+Server sends a single message type:
+- `"reload"` - Triggers browser reload
+
+### Reconnection Logic
+
+Client attempts to reconnect:
+- Max 10 attempts
+- 2-second delay between attempts
+- Exponential backoff could be added if needed
+
+## Comparison with Other Tools
+
+| Feature | Aziz App | Live Server | Vite |
+|---------|----------|-------------|------|
+| Setup | Zero config | Zero config | Config file |
+| Speed | Fast | Fast | Very fast |
+| WebSocket | ✅ | ✅ | ✅ |
+| Auto-import | ✅ | ❌ | ✅ |
+| Visual indicator | ✅ | ❌ | ❌ |
+| Dependencies | None | None | Many |
+
+## Summary
+
+The dev server provides a reliable, fast live reload experience using WebSocket. The script is always loaded (not injected), eliminating caching issues. File watching, debouncing, and automatic reconnection make development smooth and efficient.
+