frontend-hamroun 1.2.77 → 1.2.79

package/templates/complete-app/readme.md

@@ -0,0 +1,188 @@
+# Frontend Hamroun SSR Template
+
+This is a comprehensive server-side rendering (SSR) example using Frontend Hamroun.
+
+## Getting Started
+
+1. Install dependencies:
+   ```
+   npm install
+   ```
+
+2. Start the server:
+   ```
+   npm start
+   ```
+
+3. Open your browser at http://localhost:3000
+
+## Core Features
+
+This template demonstrates:
+
+### Server-Side Rendering
+- Pre-rendering of components on the server
+- Hydration of server-rendered content on the client
+- Data fetching during server rendering
+- AI-powered meta tag generation
+
+### Automatic File-Based Routing
+- Pages are automatically rendered based on their file path in the `pages` directory
+- For example:
+  - `/pages/index.js` → `/` route
+  - `/pages/about.js` → `/about` route
+  - `/pages/blog/index.js` → `/blog` route
+  - `/pages/users/[id].js` → `/users/:id` dynamic route
+
+### API Integration
+- RESTful API endpoints
+- Dynamic API routing
+- API middleware for validation and security
+- File-based API structure
+
+### Database Integration
+- MongoDB, MySQL, and PostgreSQL support
+- ORM-like query interface
+- Connection pooling
+- Transaction support
+
+### Authentication & Authorization
+- JWT-based authentication
+- Role-based access control
+- Password hashing and validation
+- Token refresh mechanism
+
+### Performance Optimization
+- Caching strategies
+- Response compression
+- Static asset optimization
+- Efficient metadata handling
+
+## Implementation Examples
+
+### Creating Components
+
+Use the `jsx` or `createElement` function from 'frontend-hamroun':
+
+```jsx
+import { jsx } from 'frontend-hamroun';
+
+export default function MyComponent(props) {
+  return jsx('div', { className: "container" }, [
+    jsx('h1', {}, "Hello World"),
+    jsx('p', {}, `Props value: ${props.value}`)
+  ]);
+}
+```
+
+### Creating API Routes
+
+Create files in the `api` directory following this pattern:
+
+```typescript
+// api/users/index.ts
+import { Request, Response } from 'express';
+
+export const get = (req: Request, res: Response) => {
+  res.json({ users: [...] });
+};
+
+export const post = (req: Request, res: Response) => {
+  // Create user
+  res.status(201).json({ success: true });
+};
+```
+
+### Database Usage
+
+```typescript
+import { Server } from 'frontend-hamroun/server';
+
+const server = new Server({
+  db: {
+    url: process.env.DATABASE_URL,
+    type: 'mongodb' // or 'mysql', 'postgres'
+  }
+});
+
+// Get typed database instance
+const db = server.getDatabase();
+const users = await db.query('SELECT * FROM users'); // For SQL
+const docs = await db.getMongoDb().collection('users').find().toArray(); // For MongoDB
+```
+
+### Authentication
+
+```typescript
+import { AuthService } from 'frontend-hamroun/server';
+
+const auth = new AuthService({
+  secret: process.env.JWT_SECRET,
+  expiresIn: '24h'
+});
+
+// Protect routes
+app.get('/api/protected', auth.requireAuth(), (req, res) => {
+  res.json({ message: "Authenticated!" });
+});
+
+// Create user & login
+const hashedPassword = await auth.hashPassword(password);
+const token = auth.generateToken(user);
+```
+
+### Advanced Middleware
+
+```typescript
+import { rateLimit, requestLogger, errorHandler } from 'frontend-hamroun/server';
+
+app.use(requestLogger);
+app.use('/api', rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+app.use(errorHandler);
+```
+
+## File-Based Routing Examples
+
+### Static Routes
+Create files in the `pages` directory:
+
+```jsx
+// pages/index.js - Maps to "/"
+export default function HomePage() {
+  return <h1>Home Page</h1>;
+}
+
+// pages/about.js - Maps to "/about"
+export default function AboutPage() {
+  return <h1>About Us</h1>;
+}
+
+// pages/contact/index.js - Maps to "/contact"
+export default function ContactPage() {
+  return <h1>Contact Us</h1>;
+}
+```
+
+### Dynamic Routes
+Use brackets in filenames to define dynamic parameters:
+
+```jsx
+// pages/users/[id].js - Maps to "/users/:id"
+export default function UserPage({ params }) {
+  return <h1>User Profile: {params.id}</h1>;
+}
+
+// pages/blog/[category]/[slug].js - Maps to "/blog/:category/:slug"
+export default function BlogPost({ params }) {
+  return (
+    <div>
+      <h1>Blog Post: {params.slug}</h1>
+      <p>Category: {params.category}</p>
+    </div>
+  );
+}
+```
+
+## Next Steps
+
+Explore the full API documentation for more advanced features and customization options.

package/templates/complete-app/server.js

@@ -0,0 +1,417 @@
+import express from 'express';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import { 
+  renderToString, 
+  jsx, 
+  Server, 
+  createServer,
+  rateLimit,
+  requestLogger,
+  errorHandler,
+  notFoundHandler,
+  loadGoWasmFromFile
+} from 'frontend-hamroun';
+import dotenv from 'dotenv';
+import compression from 'compression';
+import cors from 'cors';
+
+// Load environment variables
+dotenv.config();
+
+// Get __dirname equivalent in ESM
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Create Express app
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// Middleware
+app.use(compression()); // Compress responses
+app.use(express.json()); // Parse JSON requests
+app.use(express.urlencoded({ extended: true })); // Parse URL-encoded requests
+app.use(cors()); // Enable CORS
+app.use(requestLogger); // Log all requests
+
+// Add rate limiting to prevent abuse
+app.use(rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100 // limit each IP to 100 requests per windowMs
+}));
+
+// Serve static files from the public directory
+app.use(express.static(path.join(__dirname, 'public')));
+
+// Add correct MIME type for client.js module
+app.get('/client.js', (req, res) => {
+  res.type('application/javascript').sendFile(path.join(__dirname, 'public', 'client.js'));
+});
+
+// Serve WebAssembly files with correct MIME type
+app.get('*.wasm', (req, res, next) => {
+  res.type('application/wasm');
+  next();
+});
+
+// Add API routes example with authentication
+app.get('/api/hello', (req, res) => {
+  res.json({
+    message: 'Hello from the API!',
+    serverTime: new Date().toISOString()
+  });
+});
+
+// Load WebAssembly modules if available
+async function loadWasmModules() {
+  const wasmDir = path.join(__dirname, 'wasm');
+  
+  if (fs.existsSync(wasmDir)) {
+    try {
+      const wasmFiles = fs.readdirSync(wasmDir).filter(file => file.endsWith('.wasm'));
+      
+      for (const wasmFile of wasmFiles) {
+        const wasmPath = path.join(wasmDir, wasmFile);
+        const wasmModule = await loadGoWasmFromFile(wasmPath, { debug: true });
+        
+        console.log(`Loaded WASM module: ${wasmFile}`);
+        console.log(`Available functions:`, Object.keys(wasmModule.functions));
+        
+        // Store modules globally for API routes to use
+        global.wasmModules = global.wasmModules || {};
+        global.wasmModules[wasmFile.replace('.wasm', '')] = wasmModule;
+      }
+    } catch (error) {
+      console.error('Failed to load WASM modules:', error);
+    }
+  }
+}
+
+// Find the pages directory
+const getPagesDirectory = () => {
+  return path.join(__dirname, 'pages');
+};
+
+// Helper to check if a file exists
+const fileExists = async (filePath) => {
+  try {
+    await fs.promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// Generate meta tags for SEO
+async function generateMetaTags(content, title = '') {
+  // Extract title from content or use provided title
+  const pageTitle = title || 'Frontend Hamroun App';
+  
+  // Generate description from content
+  const plainText = content.replace(/<[^>]*>/g, ' ').trim();
+  const description = plainText.substring(0, 160) + (plainText.length > 160 ? '...' : '');
+  
+  // Extract keywords
+  const keywords = plainText
+    .toLowerCase()
+    .replace(/[^\w\s]/g, '')
+    .split(/\s+/)
+    .filter(w => w.length > 3)
+    .slice(0, 5)
+    .join(', ');
+  
+  return {
+    title: pageTitle,
+    description,
+    keywords
+  };
+}
+
+// Map URL path to component path
+const getComponentPath = async (urlPath) => {
+  const pagesDir = getPagesDirectory();
+  
+  // Handle root path
+  if (urlPath === '/') {
+    const indexPath = path.join(pagesDir, 'index.js');
+    if (await fileExists(indexPath)) {
+      return { 
+        componentPath: indexPath,
+        params: {}
+      };
+    }
+  }
+  
+  // Try direct match (e.g., /about -> /pages/about.js)
+  // Only look for .js files since Node.js ESM doesn't support .jsx directly
+  const possibleExtensions = ['.js']; // Remove .jsx, .ts, .tsx
+  
+  for (const ext of possibleExtensions) {
+    const directPath = path.join(pagesDir, `${urlPath.slice(1)}${ext}`);
+    if (await fileExists(directPath)) {
+      return { 
+        componentPath: directPath,
+        params: {}
+      };
+    }
+  }
+  
+  // Try directory index (e.g., /about -> /pages/about/index.js)
+  for (const ext of possibleExtensions) {
+    const dirIndexPath = path.join(pagesDir, urlPath.slice(1), `index${ext}`);
+    if (await fileExists(dirIndexPath)) {
+      return { 
+        componentPath: dirIndexPath,
+        params: {}
+      };
+    }
+  }
+  
+  // Look for dynamic routes (with [param] in filename)
+  const segments = urlPath.split('/').filter(Boolean);
+  const dynamicRoutes = [];
+  
+  // Recursively scan pages directory for all files
+  const scanDir = (dir, basePath = '') => {
+    const items = fs.readdirSync(dir, { withFileTypes: true });
+    
+    for (const item of items) {
+      const itemPath = path.join(dir, item.name);
+      const routePath = path.join(basePath, item.name);
+      
+      if (item.isDirectory()) {
+        scanDir(itemPath, routePath);
+      } else if (item.name.endsWith('.js')) {
+        if (item.name.includes('[')) {
+          // This is a dynamic route file
+          const urlPattern = routePath
+            .replace(/\.js$/, '')
+            .replace(/\[([^\]]+)\]/g, ':$1');
+          
+          dynamicRoutes.push({
+            pattern: urlPattern,
+            componentPath: itemPath
+          });
+        }
+      }
+    }
+  };
+  
+  scanDir(pagesDir);
+  
+  // Check if any dynamic routes match
+  for (const route of dynamicRoutes) {
+    const routeSegments = route.pattern.split('/').filter(Boolean);
+    if (routeSegments.length !== segments.length) continue;
+    
+    const params = {};
+    let matches = true;
+    
+    for (let i = 0; i < segments.length; i++) {
+      const routeSeg = routeSegments[i];
+      const urlSeg = segments[i];
+      
+      if (routeSeg.startsWith(':')) {
+        // This is a parameter
+        const paramName = routeSeg.slice(1);
+        params[paramName] = urlSeg;
+      } else if (routeSeg !== urlSeg) {
+        matches = false;
+        break;
+      }
+    }
+    
+    if (matches) {
+      return {
+        componentPath: route.componentPath,
+        params
+      };
+    }
+  }
+  
+  // No match found
+  return null;
+};
+
+// Handle all routes with SSR
+app.get('*', async (req, res, next) => {
+  try {
+    // Skip static assets and API routes
+    if (req.path.match(/\.(js|css|ico|png|jpg|jpeg|gif|svg|wasm)$/) || req.path.startsWith('/api/')) {
+      return next();
+    }
+    
+    const routeResult = await getComponentPath(req.path);
+    
+    if (!routeResult) {
+      return res.status(404).send(`
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>404 - Page Not Found</title>
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <link href="/styles.css" rel="stylesheet" type="text/css">
+          </head>
+          <body>
+            <div id="app">
+              <div class="container">
+                <h1>404 - Page Not Found</h1>
+                <p>The page you requested could not be found.</p>
+                <a href="/" class="button">Go to Home</a>
+              </div>
+            </div>
+            <script id="__APP_DATA__" type="application/json">${JSON.stringify({
+              path: req.path,
+              error: 'not_found'
+            })}</script>
+            <script type="module" src="/client.js"></script>
+          </body>
+        </html>
+      `);
+    }
+    
+    // Fixed component loading to use file:// URL scheme for Windows
+    const componentUrl = new URL(`file://${routeResult.componentPath}`).href;
+    
+    try {
+      // Import the component - handle both module.default and direct module exports
+      const moduleImport = await import(componentUrl);
+      const PageComponent = moduleImport.default || moduleImport;
+      
+      if (!PageComponent || typeof PageComponent !== 'function') {
+        throw new Error(`Invalid component in ${routeResult.componentPath}: component is not a function`);
+      }
+
+      // Create props with route data
+      const initialProps = {
+        params: routeResult.params,
+        path: req.path,
+        query: req.query,
+        api: {
+          serverTime: new Date().toISOString()
+        }
+      };
+      
+      // Use a simpler rendering approach for more reliability
+      let html;
+      try {
+        // Create a simple HTML structure based on the component's output
+        const result = PageComponent(initialProps);
+        
+        // Create a fallback HTML if the result is not valid
+        if (!result || typeof result !== 'object' || !result.type) {
+          html = `
+            <div class="error-container">
+              <h1>Frontend Hamroun App</h1>
+              <p>This is a simple fallback page.</p>
+              <p>Path: ${req.path}</p>
+              <p>Server time: ${initialProps.api.serverTime}</p>
+            </div>
+          `;
+        } else {
+          // Use renderToString with error handling
+          html = renderToString(result) || '<div>Rendering failed</div>';
+        }
+      } catch (err) {
+        console.error("Error with renderToString:", err);
+        html = `
+          <div class="error-container">
+            <h1>Rendering Error</h1>
+            <p>There was an error rendering this page: ${err.message}</p>
+            <p>Path: ${req.path}</p>
+          </div>
+        `;
+      }
+      
+      // Generate meta tags
+      const metaTags = await generateMetaTags(html, 
+        typeof PageComponent.getTitle === 'function' ? PageComponent.getTitle(initialProps) : 'Frontend Hamroun App');
+      
+      // Send complete HTML with hydration data
+      res.send(`
+        <!DOCTYPE html>
+        <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            
+            <!-- Generated Meta Tags -->
+            <title>${metaTags.title}</title>
+            <meta name="description" content="${metaTags.description}">
+            <meta name="keywords" content="${metaTags.keywords}">
+            
+            <!-- Open Graph Meta Tags -->
+            <meta property="og:title" content="${metaTags.title}">
+            <meta property="og:description" content="${metaTags.description}">
+            <meta property="og:type" content="website">
+            <meta property="og:url" content="${req.protocol}://${req.get('host')}${req.originalUrl}">
+            
+            <!-- Import styles -->
+            <link href="/styles.css" rel="stylesheet" type="text/css">
+          </head>
+          <body>
+            <div id="app">${html}</div>
+            
+            <!-- Add initial state for hydration -->
+            <script id="__APP_DATA__" type="application/json">${JSON.stringify(initialProps)}</script>
+            <script type="module" src="/client.js"></script>
+          </body>
+        </html>
+      `);
+    } catch (importError) {
+      console.error(`Error importing component from ${componentUrl}:`, importError);
+      throw new Error(`Failed to import component: ${importError.message}`);
+    }
+  } catch (error) {
+    console.error('Rendering error:', error);
+    res.status(500).send(`
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <title>500 - Server Error</title>
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <link href="/styles.css" rel="stylesheet" type="text/css">
+        </head>
+        <body>
+          <div id="app">
+            <div class="container">
+              <h1>500 - Server Error</h1>
+              <p>Something went wrong on the server.</p>
+              ${process.env.NODE_ENV === 'development' ? `<pre>${error.stack}</pre>` : ''}
+              <a href="/" class="button">Go to Home</a>
+            </div>
+          </div>
+          <script id="__APP_DATA__" type="application/json">${JSON.stringify({
+            path: req.path,
+            error: 'server_error'
+          })}</script>
+          <script type="module" src="/client.js"></script>
+        </body>
+      </html>
+    `);
+  }
+});
+
+// Add error handler middleware
+app.use(errorHandler);
+
+// Add 404 handler for API routes
+app.use(notFoundHandler);
+
+// Start the server
+const startServer = async () => {
+  // Load WebAssembly modules if available
+  await loadWasmModules();
+  
+  // Start the server
+  app.listen(PORT, () => {
+    console.log(`Server running at http://localhost:${PORT}`);
+    console.log(`Mode: ${process.env.NODE_ENV || 'development'}`);
+  });
+};
+
+startServer().catch(err => {
+  console.error('Failed to start server:', err);
+  process.exit(1);
+});