frontend-hamroun 1.1.47 → 1.1.48

package/README.md

@@ -95,12 +95,222 @@ function ThemedButton() {
 }
 ```
 
-### Server-Side Rendering
+## Server-Side Rendering
 
+### Quick Start
 ```tsx
+// server.ts
 import { renderToString } from 'frontend-hamroun';
 
-const html = await renderToString(<App />);
+const html = await renderToString(<App />, {
+  title: 'My SSR App',
+  description: 'A server-rendered application',
+  scripts: ['/client.js'],
+  initialState: {
+    user: { id: 1, name: 'John' }
+  }
+});
+```
+
+### Complete SSR Setup
+
+1. Server Setup:
+```typescript
+// server.ts
+import express from 'express';
+import { renderToString } from 'frontend-hamroun';
+
+const app = express();
+
+app.get('*', async (req, res) => {
+  try {
+    const html = await renderToString(<App />, {
+      title: 'My App',
+      description: 'Server-rendered app',
+      scripts: ['/client.js'],
+      styles: ['/styles.css'],
+      meta: {
+        'og:title': 'My App',
+        'theme-color': '#ffffff'
+      },
+      initialState: {
+        url: req.url,
+        user: req.user
+      },
+      bodyAttrs: { class: 'app-root' },
+      htmlAttrs: { lang: 'en' }
+    });
+    
+    res.send(html);
+  } catch (error) {
+    res.status(500).send('Server Error');
+  }
+});
+```
+
+2. Client Hydration:
+```typescript
+// client.tsx
+import { hydrate } from 'frontend-hamroun';
+
+// Type-safe state access
+declare global {
+  interface Window {
+    __INITIAL_STATE__: {
+      url: string;
+      user?: { id: number; name: string };
+    }
+  }
+}
+
+const { url, user } = window.__INITIAL_STATE__;
+
+hydrate(<App url={url} user={user} />, document.getElementById('root')!);
+```
+
+3. Template Customization:
+```typescript
+// Custom template options
+interface TemplateOptions {
+  title: string;
+  description?: string;
+  scripts?: string[];
+  styles?: string[];
+  meta?: Record<string, string>;
+  initialState?: any;
+  bodyAttrs?: Record<string, string>;
+  htmlAttrs?: Record<string, string>;
+}
+```
+
+### SSR Features
+
+- ✨ Full HTML document generation
+- 🔄 Automatic state hydration
+- 🎨 Customizable templates
+- 📱 Meta tags for SEO
+- 🛡️ XSS protection
+- 🚀 Streaming support
+- 📦 Asset optimization
+- 🔍 Error handling
+
+### Best Practices
+
+1. State Management:
+```typescript
+// Shared types between server and client
+interface AppState {
+  url: string;
+  user?: UserData;
+  settings: AppSettings;
+}
+
+// Server
+const state: AppState = {
+  url: req.url,
+  user: await getUser(req),
+  settings: await getSettings()
+};
+
+// Client
+const { url, user, settings } = window.__INITIAL_STATE__ as AppState;
+```
+
+2. Error Handling:
+```typescript
+// Server-side error boundary
+try {
+  const html = await renderToString(<App />, options);
+  res.send(html);
+} catch (error) {
+  const errorHtml = await renderToString(
+    <ErrorPage error={error} />,
+    { title: 'Error' }
+  );
+  res.status(500).send(errorHtml);
+}
+```
+
+3. Performance Optimization:
+```typescript
+// Caching
+const cached = await cache.get(cacheKey);
+if (cached) return cached;
+
+const html = await renderToString(<App />, {
+  ...options,
+  scripts: [
+    { src: '/client.js', async: true, defer: true }
+  ]
+});
+
+await cache.set(cacheKey, html, '1h');
+```
+
+### Basic SSR Setup
+
+```typescript
+// Server-side rendering with customization
+const html = await renderToString(<App />, {
+  title: 'My App',
+  description: 'Server-rendered application',
+  scripts: ['/assets/client.js'],
+  styles: ['/assets/styles.css'],
+  meta: {
+    'theme-color': '#ffffff',
+    'og:title': 'My App',
+    'og:description': 'My awesome app'
+  },
+  initialState: {
+    user: { name: 'John' }
+  },
+  bodyAttrs: { class: 'dark-mode' },
+  htmlAttrs: { lang: 'en', dir: 'ltr' }
+});
+```
+
+### Express Server Integration
+
+```typescript
+import express from 'express';
+import { renderToString } from 'frontend-hamroun';
+
+const app = express();
+
+app.get('*', async (req, res) => {
+  const initialState = {
+    url: req.url,
+    user: req.user // From your auth middleware
+  };
+
+  const html = await renderToString(<App />, {
+    title: 'My App',
+    scripts: ['/client.js'],
+    initialState
+  });
+
+  res.send(html);
+});
+```
+
+### Client-Side Hydration
+
+```typescript
+import { hydrate } from 'frontend-hamroun';
+
+// Access the server-provided state
+declare global {
+  interface Window {
+    __INITIAL_STATE__: any;
+  }
+}
+
+const initialState = window.__INITIAL_STATE__;
+
+hydrate(
+  <App initialState={initialState} />, 
+  document.getElementById('root')!
+);
 ```
 
 ## CLI Tools
@@ -140,6 +350,49 @@ npx create-frontend-app my-app
 - Error boundaries
 - Performance monitoring
 
+## Advanced Features
+
+### Template Customization
+```typescript
+interface TemplateOptions {
+  title: string;
+  description?: string;
+  scripts?: string[];
+  styles?: string[];
+  meta?: Record<string, string>;
+  initialState?: any;
+  bodyAttrs?: Record<string, string>;
+  htmlAttrs?: Record<string, string>;
+}
+
+// Usage with custom template
+const html = await renderToString(<App />, {
+  title: 'Custom Template',
+  styles: ['/styles.css'],
+  bodyAttrs: { 'data-theme': 'dark' }
+});
+```
+
+### Error Handling
+```typescript
+// Error boundary component
+function ErrorBoundary({ children }) {
+  const [error, resetError] = useErrorBoundary();
+
+  if (error) {
+    return (
+      <div role="alert">
+        <h2>Something went wrong</h2>
+        <pre>{error.message}</pre>
+        <button onClick={resetError}>Try again</button>
+      </div>
+    );
+  }
+
+  return children;
+}
+```
+
 ## Contributing
 
 1. Fork the repository

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontend-hamroun",
-  "version": "1.1.47",
+  "version": "1.1.48",
   "description": "A lightweight frontend framework with hooks and virtual DOM",
   "type": "module",
   "main": "./dist/index.js",

package/templates/ssr-template/src/App.tsx

@@ -1,26 +1,36 @@
-import { useState } from 'frontend-hamroun';
+import { useState, useEffect } from 'frontend-hamroun';
+
+interface AppProps {
+  initialUrl?: string;
+  initialSettings?: {
+    theme: string;
+  };
+  user?: any;
+}
+
+export function App({ 
+  initialUrl = '/',
+  initialSettings = { theme: 'light' },
+  user = null 
+}: AppProps) {
+  const [theme, setTheme] = useState(initialSettings.theme);
+
+  useEffect(() => {
+    document.body.dataset.theme = theme;
+  }, [theme]);
 
-export function App() {
-  // Initialize with a default state that works on both server and client
-  const [count, setCount] = useState(0);
-  
   return (
-    <div>
-      <h1>Server-Side Rendered App</h1>
-      <div>
-        <button 
-          onClick={() => setCount(count - 1)}
-          data-action="decrement"
-        >-</button>
-        <span style={{ margin: '0 10px' }}>{count}</span>
-        <button 
-          onClick={() => setCount(count + 1)}
-          data-action="increment"
-        >+</button>
-      </div>
-      <script dangerouslySetInnerHTML={{
-        __html: `window.__INITIAL_STATE__ = ${JSON.stringify({ count: 0 })};`
-      }} />
+    <div className="app">
+      <header>
+        <h1>My SSR App</h1>
+        <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>
+          Toggle Theme
+        </button>
+      </header>
+      <main>
+        <p>Current URL: {initialUrl}</p>
+        {user && <p>Welcome, {user.name}!</p>}
+      </main>
     </div>
   );
 }

package/templates/ssr-template/src/client.tsx

@@ -1,11 +1,29 @@
 import { hydrate } from 'frontend-hamroun';
 import { App } from './App';
 
+// Type-safe initial state access
+declare global {
+  interface Window {
+    __INITIAL_STATE__: {
+      url: string;
+      user: any;
+      settings: {
+        theme: string;
+      };
+    };
+  }
+}
 
+// Get state from server
+const initialState = window.__INITIAL_STATE__;
 
 document.addEventListener('DOMContentLoaded', () => {
   hydrate(
-    <App  />, 
+    <App 
+      initialUrl={initialState.url}
+      initialSettings={initialState.settings}
+      user={initialState.user}
+    />, 
     document.getElementById('root')!
   );
 });

package/templates/ssr-template/src/server.ts

@@ -1,43 +1,38 @@
 import express from 'express';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { renderToString, jsx } from 'frontend-hamroun';
-import { App } from './App.js';
-import fs from 'fs';
-import { title } from 'process';
+import { renderToString } from 'frontend-hamroun';
+import { App } from './App';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const app = express();
 const port = 3000;
 
-// Find the client entry file
-function getClientEntry(): string {
-  const assetsDir = path.join(__dirname, './');
-  const files = fs.readdirSync(assetsDir);
-  const entry = files.find(file => file.startsWith("client") && file.endsWith('.js'));
-  if (!entry) {
-    throw new Error('Client entry file not found');
-  }
-  return entry;
-}
-
-// Static file serving
-app.use('/assets', express.static(path.join(__dirname, './')));
-app.use(express.static(path.join(__dirname, 'dist')));
+// Static files
+app.use('/assets', express.static(path.join(__dirname, './assets')));
 
-// Main route handler
-app.get('/', async (_req: any, res: { send: (arg0: string) => void; status: (arg0: number) => { (): any; new(): any; send: { (arg0: string): void; new(): any; }; }; }) => {
+// All routes handler
+app.get('*', async (req, res) => {
   try {
-    const clientEntry = getClientEntry();
-    const html = await renderToString({
-      element: jsx(App, null),
-      title: 'SSR App',
-      scripts: [`/assets/${clientEntry}`],
-      initialState: {
-        // Add any initial state here
-      },
+    // Get initial state based on route
+    const initialState = {
+      url: req.url,
+      user: null, // Add your user data here
+      settings: { theme: 'light' }
+    };
+
+    const html = await renderToString(<App />, {
+      title: 'My SSR App',
+      description: 'Server-side rendered application',
+      scripts: ['/assets/client.js'],
+      styles: ['/assets/styles.css'],
+      initialState,
       meta: {
-        'viewport': 'width=device-width, initial-scale=1.0',
+        'theme-color': '#ffffff',
+        'og:title': 'My SSR App'
+      },
+      bodyAttrs: { 
+        'data-theme': initialState.settings.theme 
       }
     });
     
@@ -49,5 +44,5 @@ app.get('/', async (_req: any, res: { send: (arg0: string) => void; status: (arg
 });
 
 app.listen(port, () => {
-  console.log(`Server running at http://localhost:${port}`);
+  console.log(`✓ Server running at http://localhost:${port}`);
 });