create-aziz-app 2.0.15 → 3.0.0

package/template/docs/API-GUIDE.md

@@ -1,196 +0,0 @@
-# API Routes Guide
-
-## Overview
-
-Your app now has a Next.js-like API route system! Create API endpoints in the `api/` folder and call them from your components.
-
-## Creating API Routes
-
-### Basic Example
-
-Create a file in `api/` folder:
-
-```javascript
-// api/myroute.js
-registerApiRoute('myroute', async (req, res) => {
-    return res.status(200).json({ 
-        message: 'Hello from API!' 
-    });
-});
-```
-
-### Request Object (req)
-
-The request object contains:
-- `req.method` - HTTP method (GET, POST, PUT, DELETE)
-- `req.body` - Request body (parsed JSON)
-- `req.query` - Query parameters from URL
-- `req.params` - Route parameters
-
-### Response Object (res)
-
-The response object has methods:
-- `res.status(code)` - Set HTTP status code
-- `res.json(data)` - Send JSON response
-- `res.send(data)` - Send plain response
-
-### Full CRUD Example
-
-```javascript
-// api/todos.js
-const todos = [];
-
-registerApiRoute('todos', async (req, res) => {
-    switch (req.method) {
-        case 'GET':
-            // Get all todos
-            return res.status(200).json(todos);
-
-        case 'POST':
-            // Create new todo
-            const newTodo = {
-                id: Date.now(),
-                title: req.body.title,
-                completed: false
-            };
-            todos.push(newTodo);
-            return res.status(201).json(newTodo);
-
-        case 'PUT':
-            // Update todo
-            const id = req.body.id;
-            const index = todos.findIndex(t => t.id === id);
-            if (index !== -1) {
-                todos[index] = { ...todos[index], ...req.body };
-                return res.status(200).json(todos[index]);
-            }
-            return res.status(404).json({ error: 'Not found' });
-
-        case 'DELETE':
-            // Delete todo
-            const deleteId = req.query.id;
-            const deleteIndex = todos.findIndex(t => t.id === parseInt(deleteId));
-            if (deleteIndex !== -1) {
-                todos.splice(deleteIndex, 1);
-                return res.status(200).json({ message: 'Deleted' });
-            }
-            return res.status(404).json({ error: 'Not found' });
-
-        default:
-            return res.status(405).json({ error: 'Method not allowed' });
-    }
-});
-```
-
-## Using API Routes in Components
-
-### Basic GET Request
-
-```javascript
-const MyComponent = () => {
-    const [data, setData] = useState(null);
-
-    const loadData = async () => {
-        const response = await fetchApi('/api/myroute');
-        const result = await response.json();
-        setData(result);
-    };
-
-    return (
-        <div>
-            <button onClick={loadData}>Load Data</button>
-            {data && <p>{data.message}</p>}
-        </div>
-    );
-};
-```
-
-### POST Request
-
-```javascript
-const addItem = async () => {
-    const response = await fetchApi('/api/todos', {
-        method: 'POST',
-        body: JSON.stringify({
-            title: 'New Todo'
-        })
-    });
-    const result = await response.json();
-    console.log('Created:', result);
-};
-```
-
-### Query Parameters
-
-```javascript
-// Fetch with query params
-const response = await fetchApi('/api/users?id=123&name=John');
-```
-
-### DELETE Request
-
-```javascript
-const deleteItem = async (id) => {
-    const response = await fetchApi(`/api/todos?id=${id}`, {
-        method: 'DELETE'
-    });
-    const result = await response.json();
-    console.log(result.message);
-};
-```
-
-## Available API Routes
-
-### /api/hello
-Simple hello world endpoint
-- **GET** `/api/hello?name=YourName`
-- Returns: `{ message: "Hello, YourName!", timestamp: "...", method: "GET" }`
-
-### /api/users
-User management endpoint
-- **GET** `/api/users` - Get all users
-- **GET** `/api/users?id=1` - Get specific user
-- **POST** `/api/users` - Create user (body: `{ name, email }`)
-- **PUT** `/api/users?id=1` - Update user (body: `{ name, email }`)
-- **DELETE** `/api/users?id=1` - Delete user
-
-## Tips
-
-1. **Mock Data**: Currently, API routes use in-memory data. Replace with real backend calls when ready.
-
-2. **Error Handling**: Always wrap API calls in try-catch:
-```javascript
-try {
-    const response = await fetchApi('/api/myroute');
-    const data = await response.json();
-} catch (error) {
-    console.error('API Error:', error);
-}
-```
-
-3. **Loading States**: Use loading state for better UX:
-```javascript
-const [loading, setLoading] = useState(false);
-
-const loadData = async () => {
-    setLoading(true);
-    try {
-        const response = await fetchApi('/api/data');
-        const data = await response.json();
-        setData(data);
-    } finally {
-        setLoading(false);
-    }
-};
-```
-
-4. **Real Backend**: To connect to a real backend, modify `fetchApi` in `api.js` to use `fetch()` instead of the mock system.
-
-## Demo
-
-Visit `#/api-demo` in your app to see a live demo of the API system with:
-- GET requests
-- POST requests (create users)
-- DELETE requests
-- Loading states
-- Error handling

package/template/docs/API-ROUTES.md

@@ -1,538 +0,0 @@
-# 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!