miolo 3.0.0-beta.21 → 3.0.0-beta.210

package/template/.agent/skills/miolo-ssr/SKILL.md

@@ -0,0 +1,433 @@
+---
+name: miolo-ssr
+description: Server-Side Rendering (SSR) patterns for miolo applications. Use when implementing data preloading on the server, configuring SSR loader, or using useSsrData hook for client-side hydration and remote data loading.
+---
+
+# Miolo Server-Side Rendering (SSR)
+
+Server-side data preloading and client-side hydration patterns for miolo applications.
+
+## Backend - SSR Loader
+
+The SSR loader preloads data on the server before sending the initial HTML to the client.
+
+### Loader Configuration
+
+**File:** `src/server/miolo/ssr/loader.mjs`
+
+```javascript
+import { db_todo_read } from '#server/io/db/todos/read.mjs'
+import { db_user_profile } from '#server/io/db/users/read.mjs'
+
+const loader = async (ctx) => {
+  let todos = []
+  let profile = null
+  
+  try {
+    // Load data using database functions
+    todos = await db_todo_read(ctx, {})
+    todos = todos.sort((a, b) => b.created_at - a.created_at)
+  } catch (_) {}
+  
+  try {
+    if (ctx.session.user) {
+      profile = await db_user_profile(ctx, { id: ctx.session.user.id })
+    }
+  } catch (_) {}
+  
+  // Return object with data
+  // Keys are important - they're used in client code
+  const data = {
+    todos,      // Accessible as 'todos' in client
+    profile     // Accessible as 'profile' in client
+  }
+
+  return data
+}
+
+export { loader }
+```
+
+**Key points:**
+- Export async function named `loader`
+- Receives `ctx` with session and request data
+- Returns object with data to preload
+- **Object keys are important** - used as `<key>` in client `useSsrData()`
+- Wrap in try/catch to handle errors gracefully
+
+### URL-Based Loading
+
+Filter data based on current URL:
+
+```javascript
+const loader = async (ctx) => {
+  const url = ctx.request.url
+  
+  let data = {}
+  
+  // Load different data based on route
+  if (url.startsWith('/dashboard')) {
+    try {
+      data.stats = await db_dashboard_stats(ctx)
+      data.recent = await db_recent_activity(ctx)
+    } catch (_) {}
+  } else if (url.startsWith('/profile')) {
+    try {
+      data.profile = await db_user_profile(ctx, { id: ctx.session.user.id })
+      data.settings = await db_user_settings(ctx, { id: ctx.session.user.id })
+    } catch (_) {}
+  }
+  
+  return data
+}
+```
+
+**Access URL:**
+- `ctx.request.url` - Current request URL
+- Load only the data needed for the current page
+- Reduces payload size and improves performance
+
+### User-Specific Loading
+
+Load different data based on authentication:
+
+```javascript
+const loader = async (ctx) => {
+  let data = {
+    publicData: []
+  }
+  
+  // Always load public data
+  try {
+    data.publicData = await db_public_items(ctx)
+  } catch (_) {}
+  
+  // Load user-specific data if authenticated
+  if (ctx.session.authenticated) {
+    try {
+      data.userItems = await db_user_items(ctx, { 
+        user_id: ctx.session.user.id 
+      })
+      data.notifications = await db_user_notifications(ctx, {
+        user_id: ctx.session.user.id
+      })
+    } catch (_) {}
+  }
+  
+  return data
+}
+```
+
+## Client-Side - useSsrData Hook
+
+The `useSsrData` hook manages SSR-preloaded data and provides remote loading fallback.
+
+### Hook Signature
+
+```javascript
+const [data, setData, refreshData] = useSsrData(
+  '<key>',           // Key from SSR loader object
+  defaultValue,      // Default value if no data
+  async (context, fetcher) => {  // Remote loader (fallback)
+    // Load data from API if not in SSR
+    const response = await fetcher.get('/api/data')
+    return processData(response.data)
+  }
+)
+```
+
+**Parameters:**
+1. **`<key>`** (string) - Key name from SSR loader object
+2. **`defaultValue`** (any) - Default value when no data available
+3. **`remoteLoader`** (async function) - Fallback function to load data remotely
+
+**Returns:** `[data, setData, refreshData]`
+- **`data`** - Current data (React state)
+- **`setData`** - Function to set data directly (like setState)
+- **`refreshData`** - Function to re-execute remote loader
+
+### Access useSsrData
+
+Available from two sources:
+
+**1. From useMioloContext:**
+```javascript
+import { useMioloContext } from 'miolo-react'
+
+function MyComponent() {
+  const { useSsrData } = useMioloContext()
+  
+  const [todos, setTodos, refreshTodos] = useSsrData('todos', [], async (context, fetcher) => {
+    const { data } = await fetcher.get('/api/todo/list')
+    return data
+  })
+  
+  return <div>{todos.length} todos</div>
+}
+```
+
+**2. From useSessionContext:**
+```javascript
+import useSessionContext from '#cli/context/session/useSessionContext.mjs'
+
+function MyComponent() {
+  const { useSsrData } = useSessionContext()
+  
+  const [profile, setProfile, refreshProfile] = useSsrData('profile', null, async (context, fetcher) => {
+    const { data } = await fetcher.get('/api/user/profile')
+    return data
+  })
+  
+  return <div>{profile?.name}</div>
+}
+```
+
+### Basic Usage Example
+
+**DataProvider using useSsrData:**
+
+```javascript
+import { useState } from 'react'
+import useSessionContext from '#cli/context/session/useSessionContext.mjs'
+import TodoList from '#ns/models/TodoList.mjs'
+import DataContext from './DataContext.jsx'
+
+const DataProvider = ({ children }) => {
+  const [status, setStatus] = useState('loaded')
+  const { useSsrData } = useSessionContext()
+
+  const [todos, _setTodos, refreshTodos] = useSsrData('todos', [], async (context, fetcher) => {
+    setStatus('loading')
+    const { data: nTodos } = await fetcher.get('/api/todo/list')
+    setStatus('loaded')
+    return new TodoList(nTodos)
+  })
+  
+  return (
+    <DataContext.Provider value={{
+      todos,
+      refreshTodos,
+      loading: status !== 'loaded',
+      loaded: status === 'loaded'
+    }}>
+      {children}
+    </DataContext.Provider>
+  )
+}
+
+export default DataProvider
+```
+
+**How it works:**
+1. **SSR hit** - Miolo finds `'todos'` in SSR loader, uses that data
+2. **SSR miss** - Key not found in SSR, executes remote loader
+3. **Client refresh** - Calling `refreshTodos()` re-executes remote loader
+
+### Remote Loader Function
+
+The third parameter to `useSsrData` is only executed when:
+- Data is not available in SSR loader (no matching key)
+- User calls `refreshData()` to reload
+
+```javascript
+const [items, setItems, refreshItems] = useSsrData(
+  'items',
+  [],
+  async (context, fetcher) => {
+    // This runs ONLY if:
+    // 1. SSR loader didn't provide 'items' data
+    // 2. User calls refreshItems()
+    
+    const { data } = await fetcher.get('/api/items/list')
+    
+    // Can transform data before returning
+    return data.map(item => new ItemModel(item))
+  }
+)
+```
+
+**Remote loader parameters:**
+- **`context`** - Application context
+- **`fetcher`** - Authenticated fetch wrapper (see miolo-fetcher skill)
+
+### Setting Data Manually
+
+Use `setData` to update state directly:
+
+```javascript
+const [todos, setTodos, refreshTodos] = useSsrData('todos', [], remoteLoader)
+
+const handleAddTodo = async (newTodo) => {
+  // Optimistic update
+  setTodos([...todos, newTodo])
+  
+  // Save to backend
+  const response = await fetcher.post('/api/todo/save', newTodo)
+  
+  if (!response.ok) {
+    // Rollback on error
+    await refreshTodos()
+  }
+}
+```
+
+### Refreshing Data
+
+Call `refreshData` to re-execute the remote loader:
+
+```javascript
+const [notifications, setNotifications, refreshNotifications] = useSsrData(
+  'notifications',
+  [],
+  async (context, fetcher) => {
+    const { data } = await fetcher.get('/api/notifications')
+    return data
+  }
+)
+
+// Manually refresh
+const handleRefresh = () => {
+  refreshNotifications()  // Re-executes remote loader
+}
+
+// Auto-refresh every 30 seconds
+useEffect(() => {
+  const interval = setInterval(refreshNotifications, 30000)
+  return () => clearInterval(interval)
+}, [])
+```
+
+### Complex Data Transformations
+
+Transform data in remote loader:
+
+```javascript
+import TodoList from '#ns/models/TodoList.mjs'
+
+const [todos, setTodos, refreshTodos] = useSsrData(
+  'todos',
+  new TodoList([]),
+  async (context, fetcher) => {
+    const { data: rawTodos } = await fetcher.get('/api/todo/list')
+    
+    // Transform to model class
+    const todoList = new TodoList(rawTodos)
+    
+    // Apply filters
+    todoList.filterByStatus('active')
+    
+    // Sort
+    todoList.sortByDate('desc')
+    
+    return todoList
+  }
+)
+```
+
+### Multiple Data Sources
+
+Load multiple independent data sources:
+
+```javascript
+const DataProvider = ({ children }) => {
+  const { useSsrData } = useSessionContext()
+
+  const [todos, setTodos, refreshTodos] = useSsrData('todos', [], loadTodos)
+  const [profile, setProfile, refreshProfile] = useSsrData('profile', null, loadProfile)
+  const [stats, setStats, refreshStats] = useSsrData('stats', {}, loadStats)
+  
+  return (
+    <DataContext.Provider value={{
+      todos, refreshTodos,
+      profile, refreshProfile,
+      stats, refreshStats
+    }}>
+      {children}
+    </DataContext.Provider>
+  )
+}
+```
+
+## Best Practices
+
+### Backend (SSR Loader)
+
+1. **Wrap in try/catch** - Always handle errors gracefully, don't crash SSR
+2. **Return default values** - Provide sensible defaults (empty arrays, null, etc.)
+3. **Use meaningful keys** - Choose clear, descriptive names for data keys
+4. **Load only needed data** - Filter by URL to reduce payload size
+5. **Check authentication** - Load user-specific data only if authenticated
+6. **Keep it fast** - SSR loader blocks initial render, optimize queries
+
+### Client (useSsrData)
+
+1. **Provide default values** - Always specify sensible defaults
+2. **Transform in remote loader** - Process data before returning
+3. **Handle loading states** - Track loading status in remote loader
+4. **Use setData for optimistic updates** - Update UI immediately, sync later
+5. **Refresh on mutations** - Call refreshData after creating/updating data
+6. **Don't over-refresh** - Only refresh when data might have changed
+
+## Common Patterns
+
+### Loading State Management
+
+```javascript
+const DataProvider = ({ children }) => {
+  const [status, setStatus] = useState('loaded')
+  const { useSsrData } = useSessionContext()
+
+  const [data, setData, refreshData] = useSsrData('data', [], async (context, fetcher) => {
+    setStatus('loading')
+    try {
+      const response = await fetcher.get('/api/data')
+      setStatus('loaded')
+      return response.data
+    } catch (error) {
+      setStatus('error')
+      return []
+    }
+  })
+  
+  return (
+    <DataContext.Provider value={{
+      data,
+      refreshData,
+      loading: status === 'loading',
+      loaded: status === 'loaded',
+      error: status === 'error'
+    }}>
+      {children}
+    </DataContext.Provider>
+  )
+}
+```
+
+### Conditional Loading
+
+```javascript
+const loader = async (ctx) => {
+  const data = {}
+  
+  // Only load heavy data for specific routes
+  if (ctx.request.url.includes('/admin')) {
+    try {
+      data.adminStats = await db_admin_stats(ctx)
+    } catch (_) {}
+  }
+  
+  return data
+}
+```
+
+## Related Skills
+
+- **miolo-session-context** - Access `useSsrData` from session context
+- **miolo-fetcher** - Fetcher usage in remote loaders (future skill)
+- **miolo-react-patterns** - Context provider patterns
+
+## Examples from miolo-sample
+
+See actual implementations:
+- `src/server/miolo/ssr/loader.mjs` - SSR loader configuration
+- `src/cli/context/data/DataProvider.jsx` - useSsrData usage

package/template/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+charset = utf-8
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+
+[*.{js,jsx}]
+indent_style = space
+indent_size = 2
+
+[*.{css,scss}]
+indent_style = space
+indent_size = 2
+
+[{package.json,.travis.yml}]
+indent_style = space
+indent_size = 2

package/template/.env

@@ -0,0 +1,120 @@
+#
+# General
+#
+
+MIOLO_NAME=miolo-sample
+MIOLO_INTRE_LOCALE=es
+
+#
+# HTTP
+#
+
+MIOLO_PORT=8001
+MIOLO_HOSTNAME=localhost
+MIOLO_HOSTNAME_DOCKER=0.0.0.0
+MIOLO_HTTP_CORS=simple # true | false | simple. For {options}, use JS
+MIOLO_HTTP_PROXY=false # true | false. For {options}, use JS
+
+MIOLO_RATELIMIT_WHITELIST_IPS=172.22.0.1
+MIOLO_REQUEST_LAZY=2 # seconds to consider lazy a request
+MIOLO_REQUEST_SLOW=4 # seconds to consider slow a request
+MIOLO_GEOIP_ENABLED=true
+MIOLO_GEOIP_LOCAL_IPS=127.0.0.1,172.22.0.1,172.19.0.1
+
+#
+# If google auth
+#
+MIOLO_AUTH_GOOGLE_CLIENT_ID=123456
+MIOLO_AUTH_GOOGLE_CLIENT_SECRET=123456
+MIOLO_AUTH_GOOGLE_CALLBACK_URL=/auth/google/callback
+
+#
+# Session
+#
+
+MIOLO_SESSION_KEY='miolo-sample.sess'
+MIOLO_SESSION_SALT=00000000-0000-0000-0000-000000000000
+MIOLO_SESSION_SECRET=00000000-0000-0000-0000-000000000000
+MIOLO_SESSION_MAX_AGE=864000000
+MIOLO_SESSION_SECURE=false
+MIOLO_SESSION_RENEW=true
+MIOLO_SESSION_SAME_SITE=lax # lax | strict
+
+#
+# Database
+#
+
+MIOLO_DB_DIALECT=postgres
+MIOLO_DB_DATABASE=miolo-sample
+MIOLO_DB_DOCKER_HOST=postgres
+MIOLO_DB_HOST=localhost
+MIOLO_DB_PORT=5432
+MIOLO_DB_USER=postgres
+MIOLO_DB_PASSWORD=postgres
+MIOLO_DB_POOL_MAX=5
+MIOLO_DB_POOL_MIN=0
+MIOLO_DB_POOL_IDLE_TIMEOUT_MS=10000
+
+#
+# Logging
+#
+
+MIOLO_LOG_LEVEL=verbose
+MIOLO_LOG_CONSOLE_ENABLED=true
+MIOLO_LOG_FILE_ENABLED=false
+MIOLO_LOG_MAIL_ENABLED=false
+#MIOLO_LOG_MAIL_LEVEL=warn
+MIOLO_LOG_MAIL_FROM=miolo-sample@miolo-sample.com
+MIOLO_LOG_MAIL_TO=miolo-sample@miolo-sample.com
+
+#
+# Mailer
+#
+
+MIOLO_MAILER_SILENT=true
+MIOLO_MAILER_HOST=mail.miolo-sample.com
+MIOLO_MAILER_PORT=25
+MIOLO_MAILER_FROM=miolo-sample@miolo-sample.com
+MIOLO_MAILER_TO=miolo-sample@miolo-sample.com
+
+# MIOLO_MAILER_AUTH_METHOD=PLAIN # PLAIN / LOGIN
+# # If LOGIN, you need to specify:
+# MIOLO_MAILER_SMTP_USER=noreply@mail.com
+# MIOLO_MAILER_SMTP_PASS=****
+
+#
+# Cache
+#
+
+MIOLO_REDIS_HOSTNAME=127.0.0.1
+MIOLO_REDIS_HOSTNAME_DOCKER=redis
+MIOLO_REDIS_PORT=6379
+
+MIOLO_CACHE_TYPE=redis
+MIOLO_CACHE_VERSION=1
+MIOLO_CACHE_CALUSTRA_VERSION=1
+MIOLO_CACHE_CALUSTRA_TTL=86400000
+MIOLO_CACHE_SESSION_VERSION=1
+MIOLO_CACHE_SESSION_TTL=864000000
+
+#
+# Others
+#
+
+MIOLO_DOTENVX_DEBUG=false
+
+#
+# Build
+#
+
+MIOLO_BUILD_HTML_FILE=./src/cli/index.html
+MIOLO_BUILD_CLIENT_ENTRY=./src/cli/entry-cli.jsx
+MIOLO_BUILD_CLIENT_DEST=./build/cli
+MIOLO_BUILD_CLIENT_SUFFIX=iife.bundle.min
+MIOLO_BUILD_SERVER_SSR_ENTRY=./src/server/miolo/ssr/entry-server.jsx
+MIOLO_BUILD_SERVER_ENTRY=./src/server/server.mjs
+MIOLO_BUILD_SERVER_DEST=./build/server
+MIOLO_BUILD_SERVER_EXT=node.bundle.mjs
+MIOLO_BUILD_CONFIG_ENTRY=./src/server/miolo/index.mjs
+MIOLO_DEV_WATCH_ENABLED=true
+MIOLO_DEV_WATCH_DIRS=./src/server

package/template/biome.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json",
+  "files": {
+    "includes": [
+      "**/*",
+      "!dist",
+      "!build",
+      "!lib",
+      "!libs",
+      "!arredemo"
+    ]
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "complexity": {
+        "noStaticOnlyClass": "off"
+      },
+      "suspicious": {
+        "noVar": "warn",
+        "noConsole": "off",
+        "noAssignInExpressions": "off"
+      },
+      "style": {
+        "useTemplate": "off"
+      },
+      "correctness": {
+        "noUnusedVariables": "warn",
+        "useExhaustiveDependencies": "warn",
+        "useHookAtTopLevel": "error"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "parser": {
+      "unsafeParameterDecoratorsEnabled": true
+    },
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "asNeeded",
+      "trailingCommas": "none"
+    }
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}

package/template/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": false,
+  "tailwind": {
+    "config": "",
+    "css": "src/public/style/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "#cli/components",
+    "utils": "#cli/lib/utils.mjs",
+    "ui": "#cli/components/ui",
+    "lib": "#cli/lib",
+    "hooks": "#cli/hooks"
+  },
+  "iconLibrary": "lucide"
+}