create-aziz-app 2.0.15 → 3.0.0

package/template/docs/DEV-SERVER.md

@@ -1,184 +0,0 @@
-# Dev Server Guide
-
-## Overview
-
-The dev server provides a smooth development experience with live reload using WebSocket, automatic import generation, and file watching.
-
-## Features
-
-### 🔄 Live Reload (WebSocket-based)
-- **Automatic browser refresh** when you save files
-- **Visual indicator** in bottom-right corner shows connection status
-- **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:
-- `api/` - API route files
-- `components/` - React-like components
-- `pages/` - Page components
-- `modules/` - Core system modules
-- `styles/` - CSS files
-
-### 🚀 Auto Import Generation
-- Automatically generates script tags in `app.html`
-- Runs on startup and whenever JS/JSX files change
-- No need to manually add imports
-
-### 🎯 Smart Port Selection
-- Defaults to port 3000
-- Automatically finds next available port if 3000 is busy
-- Shows the actual URL in console
-
-## Usage
-
-```bash
-npm run dev
-```
-
-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 (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 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
-
-The dev server sends these headers to prevent caching:
-```
-Cache-Control: no-cache, no-store, must-revalidate
-Pragma: no-cache
-Expires: 0
-```
-
-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 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 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
-- **WebSocket** is lightweight and efficient
-- **Multiple browsers** can connect simultaneously
-- **Automatic reconnection** if connection drops
-
-## Development Tips
-
-1. Keep the terminal visible to see file change notifications
-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.
-

package/template/docs/GETTING-STARTED.md

@@ -1,205 +0,0 @@
-# Getting Started
-
-## 🎉 Your App is Now Super Clean!
-
-The app now uses an **auto-import system** - you only need to edit one file to add new pages, components, or API routes!
-
-## 📁 Project Structure
-
-```
-template/
-├── app.html              # Main HTML (super clean - only 5 script tags!)
-├── app.config.js         # ⭐ Configure what files to load here
-├── modules/              # Core system modules
-│   ├── router.js         # Routing & rendering
-│   ├── state.js          # State management
-│   ├── api.js            # API system
-│   └── auto-import.js    # Auto-import magic
-├── api/                  # API route handlers
-│   ├── hello.js
-│   └── users.js
-├── components/           # Reusable components
-│   ├── Navbar.jsx
-│   ├── Footer.jsx
-│   └── Counter.jsx
-└── pages/                # Page components
-    ├── Home.jsx
-    ├── About.jsx
-    ├── Contact.jsx
-    ├── test.jsx
-    └── ApiDemo.jsx
-```
-
-## 🚀 Adding New Files
-
-### Add a New Page
-
-1. **Create the page file:**
-```javascript
-// pages/MyNewPage.jsx
-/** @jsx h */
-
-registerPage("mynewpage", MyNewPage);
-
-function MyNewPage() {
-    const [count, setCount] = useState(0);
-    
-    return (
-        <div>
-            <h1>My New Page</h1>
-            <p>Count: {count}</p>
-            <button onClick={() => setCount(count + 1)}>
-                Increment
-            </button>
-        </div>
-    );
-}
-```
-
-2. **Add to config:**
-```javascript
-// app.config.js
-window.APP_CONFIG = {
-    pages: [
-        'pages/Home.jsx',
-        'pages/About.jsx',
-        'pages/MyNewPage.jsx'  // ← Add this line
-    ]
-};
-```
-
-3. **That's it!** Refresh the page and navigate to `#/mynewpage`
-
-### Add a New Component
-
-1. **Create the component:**
-```javascript
-// components/Button.jsx
-/** @jsx h */
-
-function Button({ label, onClick }) {
-    return (
-        <button class="btn btn-primary" onClick={onClick}>
-            {label}
-        </button>
-    );
-}
-```
-
-2. **Add to config:**
-```javascript
-// app.config.js
-window.APP_CONFIG = {
-    components: [
-        'components/Navbar.jsx',
-        'components/Button.jsx'  // ← Add this line
-    ]
-};
-```
-
-3. **Use it in pages:**
-```javascript
-<Button label="Click me" onClick={() => alert('Clicked!')} />
-```
-
-### Add a New API Route
-
-1. **Create the API route:**
-```javascript
-// api/todos.js
-/** @jsx h */
-
-const todos = [];
-
-registerApiRoute('todos', async (req, res) => {
-    if (req.method === 'GET') {
-        return res.status(200).json(todos);
-    }
-    if (req.method === 'POST') {
-        const newTodo = { id: Date.now(), ...req.body };
-        todos.push(newTodo);
-        return res.status(201).json(newTodo);
-    }
-});
-```
-
-2. **Add to config:**
-```javascript
-// app.config.js
-window.APP_CONFIG = {
-    apiRoutes: [
-        'api/hello.js',
-        'api/todos.js'  // ← Add this line
-    ]
-};
-```
-
-3. **Use it:**
-```javascript
-const response = await fetchApi('/api/todos');
-const data = await response.json();
-```
-
-## 🎨 Key Features
-
-### State Management (React-like)
-```javascript
-const [count, setCount] = useState(0);
-const [name, setName] = useState('');
-```
-
-### Routing
-```javascript
-// Register a page
-registerPage("about", AboutPage);
-
-// Navigate
-navigate("about");
-
-// Get current path
-const path = getCurrentPath();
-```
-
-### API Routes
-```javascript
-// Register
-registerApiRoute('users', async (req, res) => {
-    return res.status(200).json({ users: [] });
-});
-
-// Call
-const response = await fetchApi('/api/users');
-```
-
-## 📝 Important Notes
-
-1. **Always use `/** @jsx h */`** at the top of JSX files
-2. **Load order matters** - config → modules → auto-import
-3. **Check console** - auto-import logs what it's loading
-4. **One config file** - `app.config.js` is the only place to add files
-
-## 🔧 Troubleshooting
-
-**Page not loading?**
-- Check if it's added to `app.config.js`
-- Check browser console for errors
-- Make sure file path is correct
-
-**State not working?**
-- Make sure you're using `useState()` not `window.useState()`
-- Check that `modules/state.js` is loaded
-
-**API route not found?**
-- Check if it's added to `app.config.js`
-- Make sure you used `registerApiRoute()`
-- Check the route path matches your `fetchApi()` call
-
-## 🎯 Next Steps
-
-1. Open `app.html` in your browser
-2. Check the console to see auto-import in action
-3. Navigate to different pages
-4. Try the API Demo page at `#/api-demo`
-5. Create your own pages and components!
-
-Enjoy your clean, auto-importing app! 🚀