create-aziz-app 2.0.8 → 2.0.10

package/bin/create-aziz-app.js

@@ -197,6 +197,17 @@ function setupCSSFramework(targetDir, framework) {
     
     let html = fs.readFileSync(htmlPath, 'utf8');
     
+    // Ensure cache-control meta tags are present
+    if (!html.includes('http-equiv="Cache-Control"')) {
+        html = html.replace(
+            '<meta name="viewport" content="width=device-width, initial-scale=1.0">',
+            `<meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <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">`
+        );
+    }
+    
     if (framework === 'bootstrap') {
         // Replace globals.css with Bootstrap CDN
         html = html.replace(
@@ -430,8 +441,7 @@ function updatePagesForTailwind(targetDir) {
 function getBootstrapHomePage() {
     return `/** @jsx h */
 
-registerPage("home", HomePage);
-
+// Auto-registered as "home" route
 function HomePage() {
     return (
         <div class="container py-5">
@@ -481,8 +491,7 @@ function HomePage() {
 function getTailwindHomePage() {
     return `/** @jsx h */
 
-registerPage("home", HomePage);
-
+// Auto-registered as "home" route
 function HomePage() {
     return (
         <div class="container mx-auto py-10 px-4">
@@ -528,8 +537,7 @@ function HomePage() {
 function getBootstrapTestPage() {
     return `/** @jsx h */
 
-registerPage("test", TestPage);
-
+// Auto-registered as "test" route
 function TestPage() {
     const [count, setCount] = useState(0);
     const [name, setName] = useState('');
@@ -616,8 +624,7 @@ function TestPage() {
 function getTailwindTestPage() {
     return `/** @jsx h */
 
-registerPage("test", TestPage);
-
+// Auto-registered as "test" route
 function TestPage() {
     const [count, setCount] = useState(0);
     const [name, setName] = useState('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-aziz-app",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "A React-like framework with state management, routing, and API routes - Create apps with auto-import, live reload, and Next.js-like features",
   "keywords": [
     "react",

package/template/README.md

@@ -155,6 +155,7 @@ The CLI will automatically set up your chosen framework!
 - **[API Guide](docs/API-GUIDE.md)** - How to create API routes
 - **[Auto-Import](docs/AUTO-IMPORT.md)** - Auto-import system details
 - **[Dev Server](docs/DEV-SERVER.md)** - Live reload and development
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Fix common issues
 - **[Quick Start](docs/QUICK-START.md)** - Quick examples
 
 ## 🛠️ Commands

package/template/app.html

@@ -3,6 +3,9 @@
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <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">
     <title>My Aziz App</title>
 
     <!-- Global Styles -->

package/template/docs/TROUBLESHOOTING.md

@@ -0,0 +1,282 @@
+# Troubleshooting Guide
+
+## Live Reload Issues
+
+### Indicator Stuck on "Connecting..."
+
+**Symptoms:**
+- Green indicator shows "🔌 Connecting..." and never changes
+- Changes don't show without hard refresh (Ctrl+Shift+R)
+
+**Causes:**
+- Browser cached old version of `app.html` without live reload script
+- SSE connection blocked by browser extension or firewall
+
+**Solutions:**
+
+1. **Hard refresh once** to clear cache:
+   - Windows/Linux: `Ctrl + Shift + R`
+   - Mac: `Cmd + Shift + R`
+
+2. **Check browser console** (F12):
+   - Look for: `"🔌 Connecting to live reload at http://localhost:3000/live-reload"`
+   - Look for: `"✅ Live reload connected"`
+   - If you see errors, note them
+
+3. **Disable browser extensions** temporarily:
+   - Ad blockers can block SSE connections
+   - Try in incognito/private mode
+
+4. **Check terminal output**:
+   - Should show: `"🔌 [time] Browser connected for live reload (1 total)"`
+   - If not showing, SSE connection failed
+
+5. **Restart dev server**:
+   ```bash
+   # Stop with Ctrl+C
+   npm run dev
+   ```
+
+6. **Clear browser cache completely**:
+   - Chrome: Settings → Privacy → Clear browsing data
+   - Firefox: Settings → Privacy → Clear Data
+   - Edge: Settings → Privacy → Clear browsing data
+
+### Changes Not Showing
+
+**Symptoms:**
+- Indicator shows "✅ Live Reload Active"
+- Page reloads but changes don't appear
+
+**Solutions:**
+
+1. **Check file was saved**:
+   - Verify file has no unsaved indicator in editor
+   - Check terminal shows: `"📝 Detected change: pages/Home.jsx"`
+
+2. **Check imports were regenerated**:
+   - Terminal should show: `"🔄 Regenerating imports..."`
+   - Check `app.html` has your file listed
+
+3. **Verify file location**:
+   - Files must be in: `api/`, `components/`, `pages/`, `modules/`, or `styles/`
+   - Files outside these folders won't trigger reload
+
+4. **Check for JavaScript errors**:
+   - Open browser console (F12)
+   - Look for red error messages
+   - Fix any syntax errors in your code
+
+5. **Manual import regeneration**:
+   ```bash
+   npm run build
+   ```
+
+### Indicator Shows "❌ Connection Error"
+
+**Symptoms:**
+- Red indicator with error message
+- Console shows EventSource errors
+
+**Solutions:**
+
+1. **Check dev server is running**:
+   - Terminal should show: `"✅ Dev server running with live reload!"`
+   - If not, run: `npm run dev`
+
+2. **Check port is correct**:
+   - Browser URL should match terminal output
+   - Example: `http://localhost:3000/`
+
+3. **Firewall blocking connection**:
+   - Allow Node.js through firewall
+   - Try different port: `PORT=3001 npm run dev`
+
+4. **Browser doesn't support EventSource**:
+   - Update to latest browser version
+   - Try different browser (Chrome, Firefox, Edge)
+
+## Page Not Found (404)
+
+**Symptoms:**
+- Clicking link shows 404 page
+- URL is correct but page doesn't load
+
+**Solutions:**
+
+1. **Check function name**:
+   ```jsx
+   // ✅ Correct - ends with "Page"
+   function AboutPage() { }
+   
+   // ❌ Wrong - missing "Page"
+   function About() { }
+   ```
+
+2. **Check file is loaded**:
+   - Open `app.html`
+   - Look for: `<script type="text/babel" src="pages/YourPage.jsx"></script>`
+   - If missing, run: `npm run build`
+
+3. **Check browser console**:
+   - Look for: `"📄 Auto-registered: about → AboutPage()"`
+   - If missing, function name is wrong
+
+4. **Manual registration**:
+   ```jsx
+   // Add this if auto-registration fails
+   registerPage("about", AboutPage);
+   ```
+
+## State Not Working
+
+**Symptoms:**
+- `useState` is undefined
+- State doesn't update
+
+**Solutions:**
+
+1. **Check `/** @jsx h */` at top of file**:
+   ```jsx
+   /** @jsx h */
+   
+   function MyPage() {
+       const [count, setCount] = useState(0);
+       // ...
+   }
+   ```
+
+2. **Check state.js is loaded**:
+   - Open `app.html`
+   - Look for: `<script type="text/babel" src="modules/state.js"></script>`
+
+3. **Check browser console for errors**:
+   - Look for: `"useState is not defined"`
+   - If found, state.js didn't load
+
+## Styling Not Applied
+
+**Symptoms:**
+- Page has no styling
+- Looks like plain HTML
+
+**Solutions:**
+
+1. **Check CSS file is linked**:
+   - Open `app.html`
+   - Look for: `<link rel="stylesheet" href="styles/globals.css">`
+
+2. **Check CSS file exists**:
+   - Verify `styles/globals.css` exists
+   - Check file has content
+
+3. **Check class names**:
+   ```jsx
+   // ✅ Correct
+   <div class="card">
+   
+   // ❌ Wrong (React syntax)
+   <div className="card">
+   ```
+
+4. **Hard refresh**:
+   - CSS might be cached
+   - Press: `Ctrl + Shift + R` (Windows) or `Cmd + Shift + R` (Mac)
+
+## API Routes Not Working
+
+**Symptoms:**
+- `fetchApi()` returns 404
+- API endpoint not found
+
+**Solutions:**
+
+1. **Check API file is loaded**:
+   - Open `app.html`
+   - Look for: `<script type="text/babel" src="api/yourfile.js"></script>`
+
+2. **Check route registration**:
+   ```jsx
+   // In api/users.js
+   registerApiRoute('users', async (req, res) => {
+       // handler
+   });
+   ```
+
+3. **Check URL format**:
+   ```jsx
+   // ✅ Correct
+   await fetchApi('/api/users');
+   
+   // ❌ Wrong
+   await fetchApi('api/users');  // missing leading /
+   await fetchApi('/users');     // missing /api/
+   ```
+
+4. **Check browser console**:
+   - Look for network errors
+   - Check request URL is correct
+
+## Port Already in Use
+
+**Symptoms:**
+- Error: `EADDRINUSE: address already in use :::3000`
+
+**Solutions:**
+
+1. **Server auto-finds next port**:
+   - Check terminal for actual port
+   - Example: `"Server running at http://localhost:3001/"`
+
+2. **Kill process on port 3000**:
+   ```bash
+   # Windows
+   netstat -ano | findstr :3000
+   taskkill /PID <PID> /F
+   
+   # Mac/Linux
+   lsof -ti:3000 | xargs kill -9
+   ```
+
+3. **Use different port**:
+   ```bash
+   PORT=3001 npm run dev
+   ```
+
+## General Tips
+
+### Before Asking for Help
+
+1. **Check browser console** (F12) for errors
+2. **Check terminal output** for server errors
+3. **Try hard refresh** (Ctrl+Shift+R)
+4. **Try incognito mode** to rule out extensions
+5. **Restart dev server** (Ctrl+C, then `npm run dev`)
+
+### Debug Checklist
+
+- [ ] Dev server is running
+- [ ] Browser URL matches server URL
+- [ ] File is saved
+- [ ] File is in correct folder
+- [ ] `/** @jsx h */` at top of JSX files
+- [ ] Function name ends with "Page"
+- [ ] No JavaScript errors in console
+- [ ] Live reload indicator is green
+
+### Still Having Issues?
+
+1. **Check documentation**:
+   - [Getting Started](GETTING-STARTED.md)
+   - [Auto-Registration](AUTO-REGISTRATION.md)
+   - [Dev Server](DEV-SERVER.md)
+
+2. **Create minimal reproduction**:
+   - Create new app: `npx create-aziz-app test-app`
+   - Test if issue persists in fresh app
+
+3. **Report issue** with:
+   - Browser console output
+   - Terminal output
+   - Code that's not working
+   - Steps to reproduce

package/template/scripts/dev-server.js

@@ -34,106 +34,128 @@ function notifyClients() {
 }
 
 // Live reload script to inject
-const liveReloadScript = `
+function getLiveReloadScript() {
+    return `
 <script>
     (function() {
         // Create visual indicator
         const indicator = document.createElement('div');
         indicator.id = 'live-reload-indicator';
-        indicator.style.cssText = \`
-            position: fixed;
-            bottom: 20px;
-            right: 20px;
-            background: #4caf50;
-            color: white;
-            padding: 8px 16px;
-            border-radius: 20px;
-            font-size: 12px;
-            font-family: monospace;
-            z-index: 9999;
-            box-shadow: 0 2px 8px rgba(0,0,0,0.2);
-            transition: all 0.3s;
-        \`;
+        indicator.style.cssText = 'position: fixed; bottom: 20px; right: 20px; background: #4caf50; color: white; padding: 8px 16px; border-radius: 20px; font-size: 12px; font-family: monospace; z-index: 9999; box-shadow: 0 2px 8px rgba(0,0,0,0.2); transition: all 0.3s;';
         indicator.textContent = '🔌 Connecting...';
         document.body.appendChild(indicator);
         
         // Live reload client
-        console.log('🔌 Connecting to live reload...');
-        const evtSource = new EventSource('/live-reload');
+        console.log('🔌 Connecting to live reload at ' + window.location.origin + '/live-reload');
         
-        evtSource.onopen = () => {
-            console.log('✅ Live reload connected');
-            indicator.style.background = '#4caf50';
-            indicator.textContent = '✅ Live Reload Active';
-            // Hide after 2 seconds
-            setTimeout(() => {
-                indicator.style.opacity = '0.3';
-            }, 2000);
-        };
+        let evtSource;
+        let reconnectAttempts = 0;
+        const maxReconnectAttempts = 5;
         
-        evtSource.onmessage = (event) => {
-            if (event.data === 'reload') {
-                console.log('🔄 Changes detected, reloading...');
-                indicator.style.opacity = '1';
-                indicator.style.background = '#2196f3';
-                indicator.textContent = '🔄 Reloading...';
-                // Force reload and clear cache
-                setTimeout(() => {
-                    window.location.reload(true);
-                }, 100);
+        function connect() {
+            try {
+                evtSource = new EventSource('/live-reload');
+                
+                evtSource.onopen = function() {
+                    console.log('✅ Live reload connected');
+                    reconnectAttempts = 0;
+                    indicator.style.background = '#4caf50';
+                    indicator.textContent = '✅ Live Reload Active';
+                    setTimeout(function() {
+                        indicator.style.opacity = '0.3';
+                    }, 2000);
+                };
+                
+                evtSource.onmessage = function(event) {
+                    if (event.data === 'reload') {
+                        console.log('🔄 Changes detected, reloading...');
+                        indicator.style.opacity = '1';
+                        indicator.style.background = '#2196f3';
+                        indicator.textContent = '🔄 Reloading...';
+                        setTimeout(function() {
+                            // Add timestamp to force cache bust
+                            var url = window.location.href.split('?')[0];
+                            window.location.href = url + '?t=' + Date.now();
+                        }, 100);
+                    }
+                };
+                
+                evtSource.onerror = function(err) {
+                    console.log('⚠️ Live reload connection error');
+                    indicator.style.background = '#ff9800';
+                    indicator.style.opacity = '1';
+                    indicator.textContent = '⚠️ Connection Lost';
+                    
+                    if (evtSource) {
+                        evtSource.close();
+                    }
+                    
+                    if (reconnectAttempts < maxReconnectAttempts) {
+                        reconnectAttempts++;
+                        console.log('Reconnecting... attempt ' + reconnectAttempts);
+                        setTimeout(connect, 2000);
+                    } else {
+                        indicator.textContent = '❌ Reload Failed';
+                        console.log('Max reconnection attempts reached. Please refresh manually.');
+                    }
+                };
+            } catch (e) {
+                console.error('Failed to create EventSource:', e);
+                indicator.style.background = '#f44336';
+                indicator.textContent = '❌ Connection Error';
             }
-        };
+        }
         
-        evtSource.onerror = (err) => {
-            console.log('⚠️ Live reload disconnected, retrying...');
-            indicator.style.background = '#ff9800';
-            indicator.style.opacity = '1';
-            indicator.textContent = '⚠️ Reconnecting...';
-            evtSource.close();
-            // Retry connection after 2 seconds
-            setTimeout(() => {
-                window.location.reload();
-            }, 2000);
-        };
+        connect();
         
         // Show indicator on hover
-        indicator.addEventListener('mouseenter', () => {
+        indicator.addEventListener('mouseenter', function() {
             indicator.style.opacity = '1';
         });
-        indicator.addEventListener('mouseleave', () => {
-            indicator.style.opacity = '0.3';
+        indicator.addEventListener('mouseleave', function() {
+            if (indicator.textContent.includes('Active')) {
+                indicator.style.opacity = '0.3';
+            }
         });
     })();
 </script>
 `;
+}
 
 // Create HTTP server
 function createServer(port) {
     return http.createServer((req, res) => {
         // Handle live reload SSE endpoint
-        if (req.url === '/live-reload') {
+        if (req.url === '/live-reload' || req.url.startsWith('/live-reload?')) {
             res.writeHead(200, {
                 'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
                 'Connection': 'keep-alive',
-                'Access-Control-Allow-Origin': '*'
+                'Access-Control-Allow-Origin': '*',
+                'X-Accel-Buffering': 'no'
             });
             
+            // Send initial connection message
+            res.write(':ok\n\n');
+            
             clients.push(res);
-            console.log('🔌 Browser connected for live reload');
+            const timestamp = new Date().toLocaleTimeString();
+            console.log(`🔌 [${timestamp}] Browser connected for live reload (${clients.length} total)`);
             
             req.on('close', () => {
                 const index = clients.indexOf(res);
                 if (index !== -1) {
                     clients.splice(index, 1);
                 }
-                console.log('🔌 Browser disconnected from live reload');
+                const closeTime = new Date().toLocaleTimeString();
+                console.log(`🔌 [${closeTime}] Browser disconnected (${clients.length} remaining)`);
             });
             
             return;
         }
 
-        let filePath = '.' + req.url;
+        // Strip query parameters for file serving (cache busting)
+        let filePath = '.' + req.url.split('?')[0];
         if (filePath === './') {
             filePath = './app.html';
         }
@@ -172,7 +194,7 @@ function createServer(port) {
             } else {
                 // Inject live reload script into HTML files
                 if (extname === '.html') {
-                    content = content.toString().replace('</body>', liveReloadScript + '</body>');
+                    content = content.toString().replace('</body>', getLiveReloadScript() + '</body>');
                 }
                 
                 // Add cache control headers to prevent caching during development