@ressjs/vite-router 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @ressjs/vite-router
 
-Advanced Express router with platform detection and Server-Side Rendering (SSR) for RESS.js applications.
+Advanced Express router with **dynamic routes**, platform detection, and Server-Side Rendering (SSR) for RESS.js applications.
 
 ## Installation
 
@@ -10,16 +10,50 @@ npm install @ressjs/vite-router
 
 ## Features
 
-- **Advanced Routing**: Auto-discovers pages with platform-specific entry points
-- **Platform Detection**: Automatic device, OS, and WebView detection
-- **SSR Support**: Complete server-side rendering with proper hydration
-- **Asset Management**: Smart CSS/JS bundle resolution based on platform
-- **Development Mode**: Hot reload with fast refresh and dev server
-- **Production Ready**: Optimized builds with manifest-based asset loading
-- **TypeScript**: Full TypeScript support with comprehensive type definitions
+- **🎯 Dynamic Routes**: Next.js-style routing with `[param]` syntax
+- **🎨 Platform Detection**: Automatic device, OS, and WebView detection
+- **⚡ SSR Support**: Complete server-side rendering with proper hydration
+- **📱 Smart Assets**: Platform-specific CSS/JS bundle resolution
+- **🔧 Middleware System**: File-based middleware with execution order control
+- **🔄 Development Mode**: Hot reload with fast refresh and dev server
+- **🚀 Production Ready**: Optimized builds with manifest-based asset loading
+- **📝 TypeScript**: Full TypeScript support with comprehensive type definitions
 
 ## Quick Start
 
+### Vite Configuration
+
+Create a `vite.config.ts` file in your project root:
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import { getClientEntriesInput, getViteSSRInput } from '@ressjs/vite-router'
+
+const isSSR = !!process.env.VITE_SSR_BUILD
+
+export default defineConfig(async () => ({
+  plugins: [react()],
+  server: {
+    watch: {
+      ignored: ['**/dist/.entries/**']  // Ignore generated entries
+    }
+  },
+  build: {
+    manifest: true,
+    outDir: isSSR ? 'dist/server' : 'dist/client',
+    rollupOptions: {
+      input: isSSR
+        ? getViteSSRInput()                    // SSR entry point
+        : await getClientEntriesInput(),      // Auto-generated client entries
+    },
+    ssr: isSSR,
+  },
+}))
+```
+
+**Important**: The router automatically generates entry files for each page/platform combination in `dist/.entries/`. These are used by Vite for building client bundles.
+
 ### Basic Setup
 
 ```typescript
@@ -36,55 +70,368 @@ app.use('/', router)
 app.listen(3000, () => console.log('Server running on port 3000'))
 ```
 
-### Development Server
+### Development Server Setup
+
+Create a `server.js` file for development:
+
+```typescript
+import { createServer } from 'vite'
+import { createViteRouter } from '@ressjs/vite-router'
+import express from 'express'
+
+async function createDevServer() {
+  const app = express()
+  
+  // Create Vite server in middleware mode
+  const vite = await createServer({
+    server: { middlewareMode: true },
+    appType: 'custom'
+  })
+  
+  // Use vite's connect instance as middleware
+  app.use(vite.ssrLoadModule)
+  
+  // Create router with Vite instance
+  const router = createViteRouter({
+    vite,
+    enablePlatformDetection: true,
+    isProduction: false
+  })
+  
+  app.use('/', router)
+  app.listen(3000, () => console.log('Dev server running on port 3000'))
+}
+
+createDevServer()
+```
+
+### Package.json Scripts
+
+Add these scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "node server.js",
+    "build": "npm run build:client && npm run build:server",
+    "build:client": "vite build",
+    "build:server": "VITE_SSR_BUILD=true vite build",
+    "preview": "NODE_ENV=production node server.js",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ressjs/vite-router": "^0.5.0",
+    "express": "^4.18.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "vite": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+```
+
+### TypeScript Backend Integration
+
+For full-stack TypeScript projects with backend APIs, use this enhanced configuration:
+
+```json
+{
+  "name": "my-fullstack-app",
+  "type": "module",
+  "scripts": {
+    "dev": "PORT=3000 vite-node server.ts",
+    "build": "npm run build:client && npm run build:server",
+    "build:client": "vite build --outDir dist/client",
+    "build:server": "cross-env VITE_SSR_BUILD=1 vite build --ssr --outDir dist/server",
+    "preview": "cross-env NODE_ENV=production PORT=3000 tsx server.ts",
+    "start": "npm run build && npm run preview"
+  },
+  "dependencies": {
+    "@ressjs/vite-router": "^0.5.0",
+    "cross-env": "^7.0.3",
+    "express": "^4.18.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsx": "^4.7.1",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "vite-node": "^3.2.0"
+  }
+}
+```
+
+**Key differences for TypeScript backends**:
+- **`vite-node server.ts`**: Direct TypeScript execution in development
+- **`tsx server.ts`**: Fast TypeScript runner for production
+- **`type: "module"`**: Enable ES modules in Node.js
+- **`cross-env`**: Cross-platform environment variables
+
+**When to use this setup**:
+- Building APIs alongside your frontend
+- Need database connections, authentication, file uploads
+- Want full TypeScript integration across the stack
+- Require additional Express middleware and routes
+
+**Key Points**:
+- **`VITE_SSR_BUILD=true`**: Environment variable that tells Vite config to build for SSR
+- **Separate builds**: Client and server are built separately with different entry points
+- **Auto-generated entries**: `getClientEntriesInput()` discovers all page/platform combinations
+
+### Auto Server (WIP)
 
 ```typescript
 import { createAutoViteServer } from '@ressjs/vite-router'
 
-// Automatically configures Vite dev server with SSR
-const server = await createAutoViteServer({
+// Automatically configures Vite dev server with SSR (Work In Progress)
+const { start } = await createAutoViteServer({
   port: 3000,
   enablePlatformDetection: true
 })
+
+start()
+```
+
+## 🎯 Dynamic Routes
+
+Create pages with parameters using Next.js-style bracket syntax:
+
+### File Structure
+```
+app/pages/
+├── index.tsx                    # / route
+├── about.tsx                    # /about route
+├── users/
+│   ├── index.tsx               # /users route
+│   └── [id].tsx                # /users/:id route
+├── products/
+│   ├── [category].tsx          # /products/:category route
+│   └── [category]/
+│       └── [id].tsx            # /products/:category/:id route
+└── blog/
+    └── [...slug].tsx           # /blog/* route (coming soon)
 ```
 
-## Platform Detection
+### Route Examples
 
-The router automatically detects:
+| File | Route | Express Route | URL Example |
+|------|-------|---------------|-------------|
+| `users/[id].tsx` | `/users/[id]` | `/users/:id` | `/users/123` |
+| `products/[category]/[id].tsx` | `/products/[category]/[id]` | `/products/:category/:id` | `/products/phones/iphone` |
+| `photocard/[photoId].tsx` | `/photocard/[photoId]` | `/photocard/:photoId` | `/photocard/abc123xyz` |
+
+### Accessing Parameters
+
+```typescript
+// app/pages/users/[id].tsx
+export default function UserPage({ id, user }) {
+  return (
+    <div>
+      <h1>User {id}</h1>
+      <p>Name: {user.name}</p>
+    </div>
+  )
+}
 
-- **Device Type**: mobile, tablet, desktop
-- **Operating System**: iOS, Android, Windows, macOS, Linux
-- **Environment**: webview, browser
-- **Category**: webview.android, webview.ios, mobile, etc.
+export async function getServerSideProps(req, res) {
+  const { id } = req.params  // Access route parameters
+  
+  // Fetch user data
+  const user = await fetchUser(id)
+  
+  return {
+    props: { id, user }
+  }
+}
+```
 
-### Platform-Specific Assets
+### Dynamic Route Styles
 
-Based on detection, the router serves appropriate assets:
+Dynamic routes support platform-specific styles:
 
 ```
-app/pages/home/index.tsx           # Base page
-app/pages/home/index.scss          # Base styles
-app/pages/home/index.mobile.scss   # Mobile-specific styles
-app/pages/home/index.webview.android.scss  # Android WebView styles
+app/pages/products/[id].tsx          # Product page component
+app/pages/products/[id].scss         # Desktop styles
+app/pages/products/[id].mobile.scss  # Mobile styles
+app/pages/products/[id].webview.scss # WebView styles
 ```
 
-Generated entry-clients:
+## 🔧 Middleware System
+
+**Important**: Dynamic routes `[param].tsx` do **NOT** support dedicated middleware files. Use page-level or directory-level middleware instead.
+
+### Middleware Execution Order
+
 ```
-dist/.entries/home__index__entry-client.tsx                    # Base
-dist/.entries/home__index__entry-client.mobile.tsx             # Mobile
-dist/.entries/home__index__entry-client.webview.android.tsx    # Android WebView
+app/pages/
+├── middlewares.ts                      # --> Executes 1st (global)
+├── products/
+│   ├── middlewares.ts                 # --> Executes 2nd (directory-level)
+│   ├── index.tsx
+│   ├── index.middlewares.ts           # --> Executes 3rd (page-specific)
+│   └── [id].tsx                       # --> No middleware support for dynamic routes
+├── users/
+│   ├── [id].tsx                       # --> Uses directory and global middleware only
+│   └── middlewares.ts                 # --> Executes for all /users/* routes
+└── checkout/
+    ├── middlewares.ts                 # --> Executes 2nd for /checkout/*
+    ├── step1.tsx
+    ├── step1.middlewares.ts           # --> Executes 3rd for /checkout/step1
+    ├── step2.tsx
+    └── step2.middlewares.ts           # --> Executes 3rd for /checkout/step2
 ```
 
-## API Reference
+### Middleware Types
 
-### createViteRouter(options)
+#### 1. Global Middleware
+```typescript
+// app/pages/middlewares.ts --> Executes 1st for ALL routes
+export default function globalMiddleware(req, res, next) {
+  console.log('Global middleware for:', req.url)
+  req.startTime = Date.now()
+  next()
+}
+```
 
-Creates an Express router with SSR capabilities.
+#### 2. Directory Middleware
+```typescript
+// app/pages/products/middlewares.ts --> Executes 2nd for /products/*
+export default function productsMiddleware(req, res, next) {
+  console.log('Products middleware for:', req.url)
+  req.section = 'products'
+  next()
+}
+```
+
+#### 3. Page-Specific Middleware
+```typescript
+// app/pages/products/index.middlewares.ts --> Executes 3rd for /products only
+export default function productListMiddleware(req, res, next) {
+  console.log('Product list middleware')
+  req.page = 'product-list'
+  next()
+}
+```
+
+#### ❌ Not Supported for Dynamic Routes
+```typescript
+// ❌ app/pages/products/[id].middlewares.ts - NOT supported
+// Dynamic routes cannot have dedicated middleware files
+```
+
+### Complete Execution Flow Example
+
+For URL `/products/123`:
+
+1. **Global**: `app/pages/middlewares.ts` (if exists)
+2. **Directory**: `app/pages/products/middlewares.ts` (if exists)  
+3. **Page**: Built-in `getServerSideProps` from `[id].tsx`
+4. **Render**: Component render and HTML generation
+
+## 📱 Platform Detection
+
+The router automatically detects and serves platform-specific assets:
+
+### Detection Capabilities
+
+- **Device Type**: `phone`, `tablet`, `desktop`
+- **Operating System**: `ios`, `android`, `windows`, `macos`, `linux`
+- **Environment**: `webview`, `web`, `native`
+- **Category**: `webview.android`, `webview.ios`, `mobile`, etc.
+
+### Platform Headers (React Native)
+
+React Native clients should send these headers:
+
+```javascript
+{
+  'x-ressjs-platform': 'webview',           // Required
+  'x-ressjs-os': 'ios',                     // Required  
+  'x-ressjs-device': 'phone',               // Required
+  'x-ressjs-version': Platform.Version,     // Optional
+  'x-ressjs-app-version': '1.0.0'          // Optional
+}
+```
+
+### Asset Resolution Priority
+
+For a page like `app/pages/home/index.tsx`:
+
+1. **Device + OS Specific**: `index.phone.ios.scss`
+2. **Device Specific**: `index.phone.scss`  
+3. **Category Specific**: `index.mobile.scss`
+4. **WebView Specific**: `index.webview.scss`
+5. **Base Fallback**: `index.scss`
+
+### Platform CSS Examples
+
+```
+app/pages/home/
+├── index.tsx                           # React component
+├── index.scss                          # Desktop/base styles
+├── index.mobile.scss                   # Phone + tablet
+├── index.phone.scss                    # Phone only
+├── index.tablet.scss                   # Tablet only
+├── index.webview.scss                  # All WebView
+├── index.webview.ios.scss             # iOS WebView
+├── index.webview.android.scss         # Android WebView
+└── index.desktop.linux.scss           # Linux desktop
+```
+
+## 🎨 getServerSideProps
+
+Every page can export a `getServerSideProps` function for server-side data fetching:
+
+```typescript
+export async function getServerSideProps(req, res) {
+  // Access route parameters (for dynamic routes)
+  const { id, category } = req.params
+  
+  // Access query parameters  
+  const { search, filter } = req.query
+  
+  // Access request headers
+  const userAgent = req.headers['user-agent']
+  
+  // Return props for the component
+  return {
+    props: {
+      id,
+      data: await fetchData(id),
+      timestamp: new Date().toISOString()
+    },
+    // Optional: HTML modifications
+    title: `Product ${id}`,
+    html: {
+      head: {
+        title: `Custom Title`,
+        extraTags: ['<meta name="description" content="...">']
+      }
+    }
+  }
+}
+```
+
+## 🚀 API Reference
+
+### createViteRouter(options)
 
 ```typescript
 interface ViteRouterOptions {
   enablePlatformDetection?: boolean  // Enable platform detection (default: true)
-  vite?: any                        // Vite dev server instance
+  vite?: any                        // Vite dev server instance  
   manifest?: any                    // Production manifest
   templateHtml?: string             // HTML template
   isProduction?: boolean            // Production mode
@@ -96,61 +443,89 @@ interface ViteRouterOptions {
 }
 ```
 
-### generateHTML(template, rendered, page, manifest, platform, isProduction, platformInfo)
-
-Generates complete HTML with proper asset injection and hydration.
+### createAutoViteServer(options)
 
 ```typescript
-export async function generateHTML(
-  template: string,
-  rendered: any,
-  page: any,
-  manifest: any,
-  platform: string,
-  isProduction: boolean,
-  platformInfo: any = null
-): Promise<string>
+interface AutoViteServerOptions {
+  port?: number                     // Server port (default: 5173)
+  base?: string                     // Base path (default: '/')  
+  enablePlatformDetection?: boolean // Enable platform detection (default: true)
+}
 ```
 
 ### Utility Functions
 
 ```typescript
-// Get all discovered pages
-import { getPages, listDetectedPages } from '@ressjs/vite-router'
-
-const pages = await getPages()
-const pageList = listDetectedPages()
+import { 
+  getPages, 
+  listDetectedPages,
+  convertRouteToExpress 
+} from '@ressjs/vite-router'
+
+// Get all discovered pages with route info
+const pages = getPages()
+// [{ route: '/users/[id]', expressRoute: '/users/:id', file: '...', abs: '...' }]
+
+// Convert Next.js route to Express route
+const expressRoute = convertRouteToExpress('/users/[id]')  // '/users/:id'
 ```
 
-## File Structure
+## 🔧 Production Build
 
-The router expects the following structure:
+### Build Process
 
-```
-app/
-  pages/
-    index.tsx                    # Home page
-    about/
-      index.tsx                 # About page
-      index.mobile.scss         # Mobile styles
-    products/
-      [id].tsx                  # Dynamic route
-      [id].webview.ios.scss     # iOS WebView styles
+```bash
+# 1. Build client assets
+vite build --outDir dist/client
+
+# 2. Build server bundle  
+vite build --ssr --outDir dist/server
+
+# 3. Start production server
+NODE_ENV=production node server.js
 ```
 
-## Development
+### Example Production Server
 
-```bash
-# Build the package
-npm run build
+```typescript
+import express from 'express'
+import { createViteRouter } from '@ressjs/vite-router'
+
+const app = express()
 
-# Run tests
-npm test
+// Serve static assets
+app.use('/assets', express.static('dist/client/assets'))
 
-# Watch mode
-npm run dev
+// Create router with production settings
+const router = createViteRouter({
+  isProduction: true,
+  enablePlatformDetection: true
+})
+
+app.use('/', router)
+app.listen(3000)
 ```
 
-## License
+## 🐛 Troubleshooting
+
+### Dynamic Route Not Working
+
+1. **Check file naming**: Use `[param].tsx`, not `{param}.tsx`
+2. **Verify parameters**: Access via `req.params.param` in `getServerSideProps`
+3. **Build order**: Run `npm run build` after adding new dynamic routes
+
+### Middleware Not Executing  
+
+1. **File naming**: Use `middlewares.ts` (plural) or `page.middlewares.ts`
+2. **Dynamic routes**: Don't create `[param].middlewares.ts` - not supported
+3. **Export**: Use `export default function` format
+
+### Platform Detection Issues
+
+1. **Headers**: Ensure React Native sends required `x-ressjs-*` headers
+2. **CSS files**: Create platform-specific CSS files if needed
+3. **Case sensitivity**: Use lowercase for OS names (`ios`, `android`)
+
+## 📄 License
 
 MIT

package/dist/helpers/html-generator.d.ts

@@ -7,6 +7,7 @@ export interface HTMLGenerationContext {
     platform: string;
     isProduction: boolean;
     platformInfo: PlatformInfo | null;
+    serverSideResult?: any;
 }
 export declare function generateClientScript(pageFile: string, platformInfo: PlatformInfo | null, manifest: any, isProduction: boolean): Promise<string | null>;
 export declare function generateClientCSS(pageFile: string, platformInfo: PlatformInfo | null, manifest: any, isProduction: boolean): string;

package/dist/helpers/html-generator.js

@@ -8,7 +8,12 @@ exports.generateClientCSS = generateClientCSS;
 exports.generateCompleteHTML = generateCompleteHTML;
 const promises_1 = __importDefault(require("node:fs/promises"));
 async function generateClientScript(pageFile, platformInfo, manifest, isProduction) {
-    const rel = pageFile.replace(/^app\/pages\//, '').replace(/\.tsx$|\.jsx$/, '').replace(/\//g, '__');
+    // Sanitizar nombre: convertir [id] a _id_ para nombres de archivo (igual que en pages.ts)
+    const rel = pageFile
+        .replace(/^app\/pages\//, '')
+        .replace(/\.tsx$|\.jsx$/, '')
+        .replace(/\//g, '__')
+        .replace(/\[([^\]]+)\]/g, '_$1_');
     let entryKey = `${rel}__entry-client.tsx`;
     if (platformInfo && platformInfo.device !== 'desktop') {
         // Priority order (from highest to lowest):
@@ -59,7 +64,12 @@ function generateClientCSS(pageFile, platformInfo, manifest, isProduction) {
     if (!isProduction || !pageFile) {
         return '';
     }
-    const rel = pageFile.replace(/^app\/pages\//, '').replace(/\.tsx$|\.jsx$/, '').replace(/\//g, '__');
+    // Sanitizar nombre: convertir [id] a _id_ para nombres de archivo (igual que en pages.ts)
+    const rel = pageFile
+        .replace(/^app\/pages\//, '')
+        .replace(/\.tsx$|\.jsx$/, '')
+        .replace(/\//g, '__')
+        .replace(/\[([^\]]+)\]/g, '_$1_');
     let entryKey = `dist/.entries/${rel}__entry-client.tsx`;
     if (platformInfo && platformInfo.device !== 'desktop') {
         // Priority order (from highest to lowest):
@@ -90,12 +100,40 @@ function generateClientCSS(pageFile, platformInfo, manifest, isProduction) {
     return '';
 }
 async function generateCompleteHTML(context) {
-    const { template, rendered, page, manifest, isProduction, platformInfo } = context;
+    const { template, rendered, page, manifest, isProduction, platformInfo, serverSideResult } = context;
     const scriptSrc = await generateClientScript(page.file, platformInfo, manifest, isProduction);
     const scriptTag = scriptSrc ? `<script type="module" src="${scriptSrc}"></script>` : '';
     const cssLinks = page?.file ? generateClientCSS(page.file, platformInfo, manifest, isProduction) : '';
-    const html = template
-        .replace('<!--app-head-->', cssLinks)
+    // Construir contenido HEAD extra y atributos desde serverSideResult
+    let headContent = cssLinks;
+    let htmlAttributes = '';
+    let bodyAttributes = '';
+    let pageTitle = '';
+    if (serverSideResult?.html) {
+        if (serverSideResult.html.head?.attributes) {
+            htmlAttributes = Object.entries(serverSideResult.html.head.attributes)
+                .map(([k, v]) => `${k}="${v}"`).join(' ');
+        }
+        if (serverSideResult.html.body?.attributes) {
+            bodyAttributes = Object.entries(serverSideResult.html.body.attributes)
+                .map(([k, v]) => `${k}="${v}"`).join(' ');
+        }
+        if (serverSideResult.html.head?.extraTags) {
+            headContent += '\n' + serverSideResult.html.head.extraTags.join('\n');
+        }
+        if (serverSideResult.title || serverSideResult.html.head?.title) {
+            pageTitle = `<title>${serverSideResult.title || serverSideResult.html.head?.title}</title>`;
+        }
+    }
+    let html = template;
+    if (htmlAttributes)
+        html = html.replace('<html', `<html ${htmlAttributes}`);
+    if (bodyAttributes)
+        html = html.replace('<body', `<body ${bodyAttributes}`);
+    if (pageTitle)
+        html = html.replace(/<title>.*?<\/title>/i, pageTitle);
+    html = html
+        .replace('<!--app-head-->', headContent)
         .replace('<!--app-html-->', rendered.html)
         .replace('</body>', `<script>
         window.__INITIAL_PROPS__=${JSON.stringify(rendered.props || {})};