create-aziz-app 2.0.11 → 2.0.13

package/template/docs/NEXTJS-COMPARISON.md

@@ -0,0 +1,473 @@
+# Next.js Comparison
+
+## Overview
+
+Aziz App is a **lightweight Next.js clone** with all the core benefits but zero dependencies and minimal complexity.
+
+## Feature Comparison
+
+| Feature | Aziz App | Next.js | Notes |
+|---------|----------|---------|-------|
+| **React Hooks** | ✅ | ✅ | useState, useEffect, useMemo, useCallback, useRef, useReducer |
+| **File-based Routing** | ✅ | ✅ | pages/ folder → routes |
+| **API Routes** | ✅ | ✅ | api/ folder → endpoints |
+| **Server-side API** | ✅ | ✅ | Real Node.js backend |
+| **Hot Reload** | ✅ | ✅ | WebSocket-based |
+| **Auto Import** | ✅ | ✅ | No manual imports needed |
+| **Zero Config** | ✅ | ❌ | No config files needed |
+| **Bundle Size** | **~50KB** | ~300KB+ | 6x smaller! |
+| **Dependencies** | **0** | 20+ | No node_modules bloat |
+| **Build Time** | **Instant** | Slow | No build step |
+| **SSR** | ❌ | ✅ | Client-side only |
+| **SSG** | ❌ | ✅ | Client-side only |
+| **Image Optimization** | ❌ | ✅ | Use CDN instead |
+| **TypeScript** | ❌ | ✅ | Pure JavaScript |
+| **Middleware** | ❌ | ✅ | Keep it simple |
+
+## React Hooks - Identical API
+
+### useState
+
+```javascript
+// Next.js
+import { useState } from 'react';
+const [count, setCount] = useState(0);
+
+// Aziz App - EXACTLY THE SAME!
+const [count, setCount] = useState(0);
+```
+
+### useEffect
+
+```javascript
+// Next.js
+import { useEffect } from 'react';
+useEffect(() => {
+    console.log('Mounted!');
+    return () => console.log('Cleanup!');
+}, [dependency]);
+
+// Aziz App - EXACTLY THE SAME!
+useEffect(() => {
+    console.log('Mounted!');
+    return () => console.log('Cleanup!');
+}, [dependency]);
+```
+
+### useMemo
+
+```javascript
+// Next.js
+import { useMemo } from 'react';
+const value = useMemo(() => expensiveCalc(), [dep]);
+
+// Aziz App - EXACTLY THE SAME!
+const value = useMemo(() => expensiveCalc(), [dep]);
+```
+
+### useCallback
+
+```javascript
+// Next.js
+import { useCallback } from 'react';
+const callback = useCallback(() => doSomething(), [dep]);
+
+// Aziz App - EXACTLY THE SAME!
+const callback = useCallback(() => doSomething(), [dep]);
+```
+
+### useRef
+
+```javascript
+// Next.js
+import { useRef } from 'react';
+const ref = useRef(null);
+
+// Aziz App - EXACTLY THE SAME!
+const ref = useRef(null);
+```
+
+### useReducer
+
+```javascript
+// Next.js
+import { useReducer } from 'react';
+const [state, dispatch] = useReducer(reducer, initialState);
+
+// Aziz App - EXACTLY THE SAME!
+const [state, dispatch] = useReducer(reducer, initialState);
+```
+
+## API Routes - Identical API
+
+### Basic Route
+
+```javascript
+// Next.js (pages/api/hello.js)
+export default async function handler(req, res) {
+    res.status(200).json({ message: 'Hello' });
+}
+
+// Aziz App (api/hello.js) - EXACTLY THE SAME!
+export default async function handler(req, res) {
+    res.status(200).json({ message: 'Hello' });
+}
+```
+
+### Request Object
+
+```javascript
+// Both Next.js and Aziz App
+{
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+    body: {},      // Parsed JSON
+    query: {},     // URL parameters
+    headers: {},   // Request headers
+    url: string    // Full URL
+}
+```
+
+### Response Methods
+
+```javascript
+// Both Next.js and Aziz App
+res.status(200)                    // Set status
+res.json({ data: 'value' })        // Send JSON
+res.send('text')                   // Send text
+res.setHeader('X-Custom', 'value') // Set header
+```
+
+### CRUD Example
+
+```javascript
+// Works identically in both!
+export default async function handler(req, res) {
+    switch (req.method) {
+        case 'GET':
+            return res.status(200).json({ users: [] });
+        case 'POST':
+            return res.status(201).json({ created: true });
+        case 'PUT':
+            return res.status(200).json({ updated: true });
+        case 'DELETE':
+            return res.status(200).json({ deleted: true });
+        default:
+            return res.status(405).json({ error: 'Method not allowed' });
+    }
+}
+```
+
+## File-based Routing
+
+### Pages
+
+```
+// Next.js
+pages/
+├── index.js      → /
+├── about.js      → /about
+└── contact.js    → /contact
+
+// Aziz App - Same concept!
+pages/
+├── Home.jsx      → #/home
+├── About.jsx     → #/about
+└── Contact.jsx   → #/contact
+```
+
+### Auto-Registration
+
+```javascript
+// Next.js - Automatic
+// Just create the file
+
+// Aziz App - Automatic too!
+// Just name your function: AboutPage()
+function AboutPage() {
+    return <div><h1>About</h1></div>;
+}
+```
+
+## Data Fetching
+
+### Client-side Fetching
+
+```javascript
+// Next.js
+import { useState, useEffect } from 'react';
+
+function Page() {
+    const [data, setData] = useState(null);
+    
+    useEffect(() => {
+        fetch('/api/users')
+            .then(res => res.json())
+            .then(setData);
+    }, []);
+    
+    return <div>{data?.message}</div>;
+}
+
+// Aziz App - EXACTLY THE SAME!
+function Page() {
+    const [data, setData] = useState(null);
+    
+    useEffect(() => {
+        fetch('/api/users')
+            .then(res => res.json())
+            .then(setData);
+    }, []);
+    
+    return <div>{data?.message}</div>;
+}
+```
+
+### Custom Hook
+
+```javascript
+// Both Next.js and Aziz App
+function useFetch(url) {
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    
+    useEffect(() => {
+        fetch(url)
+            .then(res => res.json())
+            .then(data => {
+                setData(data);
+                setLoading(false);
+            });
+    }, [url]);
+    
+    return { data, loading };
+}
+```
+
+## JSX Syntax
+
+### Components
+
+```jsx
+// Next.js
+export default function Button({ onClick, children }) {
+    return <button onClick={onClick}>{children}</button>;
+}
+
+// Aziz App - Same JSX!
+function Button({ onClick, children }) {
+    return <button onClick={onClick}>{children}</button>;
+}
+```
+
+### Props
+
+```jsx
+// Both support the same props
+<div 
+    class="container"
+    style={{ color: 'red' }}
+    onClick={() => alert('Hi')}
+>
+    Content
+</div>
+```
+
+## Development Experience
+
+### Hot Reload
+
+```
+// Next.js
+1. Save file
+2. Fast Refresh
+3. State preserved
+
+// Aziz App
+1. Save file
+2. WebSocket reload
+3. Full page reload (state reset)
+```
+
+### Error Messages
+
+```
+// Next.js
+- Detailed error overlay
+- Stack traces
+- Suggestions
+
+// Aziz App
+- Browser console errors
+- Simpler debugging
+- Less magic
+```
+
+## When to Use Each
+
+### Use Aziz App When:
+
+✅ Building simple SPAs
+✅ Learning React concepts
+✅ Prototyping quickly
+✅ Want zero dependencies
+✅ Don't need SSR/SSG
+✅ Want instant startup
+✅ Prefer simplicity
+
+### Use Next.js When:
+
+✅ Need SEO (SSR/SSG)
+✅ Building large apps
+✅ Need image optimization
+✅ Want TypeScript
+✅ Need middleware
+✅ Want edge functions
+✅ Building production apps
+
+## Migration Path
+
+### From Aziz App to Next.js
+
+1. **Pages** - Rename files, adjust exports
+2. **API Routes** - Copy as-is (same API!)
+3. **Hooks** - No changes needed (same API!)
+4. **Components** - Minor adjustments
+5. **Styling** - Add CSS modules if needed
+
+### From Next.js to Aziz App
+
+1. **Remove SSR/SSG** - Convert to client-side
+2. **Pages** - Adjust file names
+3. **API Routes** - Copy as-is (same API!)
+4. **Hooks** - No changes needed (same API!)
+5. **Remove dependencies** - Delete node_modules
+
+## Performance
+
+### Bundle Size
+
+```
+Next.js Production Build:
+- Framework: ~300KB
+- Runtime: ~100KB
+- Total: ~400KB+
+
+Aziz App:
+- Framework: ~50KB
+- Runtime: 0KB (browser native)
+- Total: ~50KB
+```
+
+### Startup Time
+
+```
+Next.js:
+- npm install: 2-5 minutes
+- npm run dev: 10-30 seconds
+- First load: 2-5 seconds
+
+Aziz App:
+- npm install: 5 seconds
+- npm run dev: <1 second
+- First load: <1 second
+```
+
+### Build Time
+
+```
+Next.js:
+- Development: 10-30 seconds
+- Production: 1-5 minutes
+
+Aziz App:
+- Development: Instant
+- Production: No build needed
+```
+
+## Code Examples
+
+### Counter Component
+
+```jsx
+// Works identically in both!
+function Counter() {
+    const [count, setCount] = useState(0);
+    
+    return (
+        <div>
+            <p>Count: {count}</p>
+            <button onClick={() => setCount(count + 1)}>
+                Increment
+            </button>
+        </div>
+    );
+}
+```
+
+### Form with Validation
+
+```jsx
+// Works identically in both!
+function ContactForm() {
+    const [name, setName] = useState('');
+    const [email, setEmail] = useState('');
+    const [error, setError] = useState('');
+    
+    const handleSubmit = async (e) => {
+        e.preventDefault();
+        
+        if (!name || !email) {
+            setError('All fields required');
+            return;
+        }
+        
+        const res = await fetch('/api/contact', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name, email })
+        });
+        
+        if (res.ok) {
+            alert('Sent!');
+        }
+    };
+    
+    return (
+        <form onSubmit={handleSubmit}>
+            <input 
+                value={name}
+                onChange={(e) => setName(e.target.value)}
+                placeholder="Name"
+            />
+            <input 
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+                placeholder="Email"
+            />
+            {error && <p>{error}</p>}
+            <button type="submit">Submit</button>
+        </form>
+    );
+}
+```
+
+## Summary
+
+Aziz App is a **lightweight Next.js clone** that provides:
+
+- ✅ **Same React Hooks API** - useState, useEffect, etc.
+- ✅ **Same API Routes** - Identical req/res objects
+- ✅ **Same JSX Syntax** - Write components the same way
+- ✅ **Same Development Flow** - File-based routing, hot reload
+- ✅ **Zero Dependencies** - No node_modules bloat
+- ✅ **Instant Startup** - No build step
+- ✅ **6x Smaller** - Minimal bundle size
+
+Perfect for:
+- 🎓 Learning React/Next.js concepts
+- 🚀 Rapid prototyping
+- 📱 Simple SPAs
+- 🎨 Portfolio sites
+- 🧪 Experiments
+
+**It's Next.js, but lightweight!** 🎉

package/template/modules/api.js

@@ -1,96 +1,12 @@
 /** @jsx h */
 
 // ============================================================
-//  API ROUTE SYSTEM
-//  Next.js-like API routes for client-side
-//  Can be easily replaced with real backend calls
+//  API CLIENT
+//  Fetch-like API for making requests to backend API routes
+//  API routes run on the SERVER (Node.js), not in the browser
 // ============================================================
 
-// API routes registry
-const apiRoutes = {};
-
-// Register an API route
-function registerApiRoute(path, handler) {
-    apiRoutes[path] = handler;
-    console.log(`Registered API route: /api/${path}`);
-}
-
-// API request/response helpers
-class ApiRequest {
-    constructor(method, body, query, params) {
-        this.method = method;
-        this.body = body;
-        this.query = query;
-        this.params = params;
-    }
-}
-
-class ApiResponse {
-    constructor() {
-        this.statusCode = 200;
-        this.headers = {};
-        this.data = null;
-    }
-
-    status(code) {
-        this.statusCode = code;
-        return this;
-    }
-
-    json(data) {
-        this.data = data;
-        this.headers['Content-Type'] = 'application/json';
-        return this;
-    }
-
-    send(data) {
-        this.data = data;
-        return this;
-    }
-}
-
-// Execute an API route
-async function callApi(path, options = {}) {
-    const {
-        method = 'GET',
-        body = null,
-        query = {},
-        params = {}
-    } = options;
-
-    // Find the route handler
-    const handler = apiRoutes[path];
-    
-    if (!handler) {
-        return {
-            status: 404,
-            data: { error: 'API route not found' }
-        };
-    }
-
-    // Create request and response objects
-    const req = new ApiRequest(method, body, query, params);
-    const res = new ApiResponse();
-
-    try {
-        // Call the handler
-        await handler(req, res);
-
-        return {
-            status: res.statusCode,
-            data: res.data,
-            headers: res.headers
-        };
-    } catch (error) {
-        console.error(`API Error on ${path}:`, error);
-        return {
-            status: 500,
-            data: { error: error.message }
-        };
-    }
-}
-
-// Fetch-like API for making requests
+// Fetch-like API for making requests to backend
 async function fetchApi(path, options = {}) {
     const {
         method = 'GET',
@@ -98,51 +14,31 @@ async function fetchApi(path, options = {}) {
         headers = {}
     } = options;
 
-    // Parse query params from path
-    const [routePath, queryString] = path.split('?');
-    const query = {};
-    if (queryString) {
-        queryString.split('&').forEach(param => {
-            const [key, value] = param.split('=');
-            query[decodeURIComponent(key)] = decodeURIComponent(value);
-        });
-    }
-
-    // Parse body if it's JSON
-    let parsedBody = body;
-    if (body && typeof body === 'string') {
-        try {
-            parsedBody = JSON.parse(body);
-        } catch (e) {
-            parsedBody = body;
+    const fetchOptions = {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            ...headers
         }
-    }
+    };
 
-    const result = await callApi(routePath.replace('/api/', ''), {
-        method,
-        body: parsedBody,
-        query
-    });
+    if (body) {
+        fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
 
-    // Return a fetch-like response
-    return {
-        ok: result.status >= 200 && result.status < 300,
-        status: result.status,
-        statusText: result.status === 200 ? 'OK' : 'Error',
-        headers: result.headers,
-        json: async () => result.data,
-        text: async () => JSON.stringify(result.data)
-    };
+    try {
+        const response = await fetch(path, fetchOptions);
+        return response;
+    } catch (error) {
+        console.error('API Error:', error);
+        throw error;
+    }
 }
 
 // Export to global scope
-window.registerApiRoute = registerApiRoute;
 window.fetchApi = fetchApi;
-window.callApi = callApi;
 
 // Also make available without window prefix
 if (typeof globalThis !== 'undefined') {
-    globalThis.registerApiRoute = registerApiRoute;
     globalThis.fetchApi = fetchApi;
-    globalThis.callApi = callApi;
 }