@ressjs/vite-router 0.6.0-experimental.0 → 0.6.0-rc.1

package/LICENSE

@@ -0,0 +1,69 @@
+ress.js Proprietary License
+
+Copyright (c) 2025-2026 gabrielspisso. All rights reserved.
+
+This license applies to the ress.js packages (the "Software"), published on npm
+under the @ressjs and @gzzy scopes, in every version released from 0.6.0-rc.0
+onwards. Earlier versions were released under the MIT License and remain
+available under those terms.
+
+1. GRANT
+   Subject to this license, the Licensor grants you a worldwide, non-exclusive,
+   non-transferable, non-sublicensable, royalty-free license to install and use
+   the Software, as distributed by the Licensor, to build, run and deploy your
+   own applications and services, including commercial ones, and to charge your
+   own customers for them.
+
+2. RESTRICTIONS
+   You may not:
+   a) fork, copy, or redistribute the Software, in whole or in part, except for
+      the portions that are necessarily included in the build output of your own
+      application in order to run it;
+   b) publish, distribute or make available a modified version of the Software
+      or any work derived from it. Modifications for your own internal use are
+      allowed, but they remain subject to this license;
+   c) use the Software, or any part of it, to build, offer or support a
+      framework, library, tool or service that competes with the Software;
+   d) sell, sublicense, rent or host the Software itself as a product or service
+      for third parties, as opposed to hosting your own application built with
+      it;
+   e) remove or alter copyright, license or attribution notices;
+   f) use the name "ress.js" or the Licensor's names or marks to endorse or
+      promote your products without written permission.
+
+3. SCAFFOLDING OUTPUT
+   Files that @ressjs/create-ress-app copies into your project (templates and
+   generated configuration) are yours: you may use, modify and distribute them
+   without restriction. This does not extend to the Software packages that the
+   generated project installs as dependencies.
+
+4. SUPPORT
+   The Software is provided without any obligation of support, maintenance or
+   updates. The Licensor may offer support, maintenance, training or consulting
+   under a separate paid agreement; that agreement does not change this license
+   unless it says so explicitly and is signed by the Licensor.
+
+5. OWNERSHIP
+   The Software is licensed, not sold. The Licensor retains all rights not
+   expressly granted here. Feedback and suggestions you send may be used by the
+   Licensor without obligation to you.
+
+6. TERMINATION
+   This license ends automatically if you breach it. On termination you must
+   stop using the Software and delete your copies. Sections 4 to 8 survive
+   termination.
+
+7. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR WILL NOT BE LIABLE FOR
+   ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR LOSS OF
+   PROFITS, DATA OR BUSINESS, ARISING FROM THE USE OF OR INABILITY TO USE THE
+   SOFTWARE. THE LICENSOR'S TOTAL LIABILITY IS LIMITED TO THE AMOUNT YOU PAID
+   FOR THE SOFTWARE, WHICH MAY BE ZERO.
+
+For other uses, including exceptions to section 2, contact the Licensor to
+agree a separate license.

package/README.md

@@ -1,6 +1,8 @@
 # @ressjs/vite-router
 
-Advanced Express router with **dynamic routes**, platform detection, and Server-Side Rendering (SSR) for RESS.js applications.
+Express router for ress.js applications: file-based pages, dynamic routes and server-side rendering on top of Vite.
+
+> Pre-release (`0.6.0-rc`). The API may still change before `0.6.0`.
 
 ## Installation
 
@@ -8,534 +10,16 @@ Advanced Express router with **dynamic routes**, platform detection, and Server-
 npm install @ressjs/vite-router
 ```
 
-## Features
-
-- **🎯 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
-
-### Platform CSS and inline styles
-
-Style variants use the same filename convention for every supported format. The
-catalog and the inline components are provided by `@ressjs/assets`:
-
-```text
-app/pages/home/index.css
-app/pages/home/index.phone.css
-app/pages/home/index.webview.android.css
-```
-
-The matching stylesheet is selected from the detected platform. For CSS that is
-part of the rendered page, use the small `Style` component:
-
-```jsx
-import { Style } from '@ressjs/assets/client'
-
-export default function Home() {
-  return <><Style>{'.notice { color: red; }'}</Style><main className="notice">Hello</main></>
-}
-```
-
-`@ressjs/vite-router/client` remains a compatibility alias. `Script` is also
-available from `@ressjs/assets/client` for inline code or an explicit `src`.
-The router consumes `resolvePageAssets` from `@ressjs/assets`; request handling
-only reads the in-memory catalog and artifact index.
-
-## Quick Start
-
-### Vite Configuration
-
-Create a `vite.config.ts` file in your project root:
-
-```ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import { ressPlugin } from '@ressjs/vite-router/plugin'
-
-export default defineConfig({
-  plugins: [react(), ressPlugin()],
-})
-```
-
-**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
-import express from 'express'
-import { createViteRouter } from '@ressjs/vite-router'
-
-const app = express()
-const router = createViteRouter({
-  enablePlatformDetection: true,
-  isProduction: process.env.NODE_ENV === 'production'
-})
-
-app.use('/', router)
-app.listen(3000, () => console.log('Server running on port 3000'))
-```
-
-### 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": "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": "vite build",
-            "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**:
-- **Un solo `vite build`**: el plugin declara los entornos de cliente y servidor, y ambos se construyen en una sola invocación.
-- **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 (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)
-```
-
-### Route Examples
-
-| 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>
-  )
-}
-
-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 }
-  }
-}
-```
-
-### Dynamic Route Styles
-
-Dynamic routes support platform-specific 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
-```
-
-## 🔧 Middleware System
-
-**Important**: Dynamic routes `[param].tsx` do **NOT** support dedicated middleware files. Use page-level or directory-level middleware instead.
-
-### Middleware Execution Order
-
-```
-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
-```
-
-### Middleware Types
-
-#### 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()
-}
-```
-
-#### 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  
-  manifest?: any                    // Production manifest
-  templateHtml?: string             // HTML template
-  isProduction?: boolean            // Production mode
-  renderFunction?: (options: {      // Custom render function
-    url: string
-    platform: string
-    req: any
-  }) => Promise<string>
-}
-```
-
-### createAutoViteServer(options)
-
-```typescript
-interface AutoViteServerOptions {
-  port?: number                     // Server port (default: 5173)
-  base?: string                     // Base path (default: '/')  
-  enablePlatformDetection?: boolean // Enable platform detection (default: true)
-}
-```
-
-### Utility Functions
-
-```typescript
-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'
-```
-
-## 🔧 Production Build
+## Getting started
 
-### Build Process
+The recommended way to start is to generate an app, which comes already configured:
 
 ```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
-```
-
-### Example Production Server
-
-```typescript
-import express from 'express'
-import { createViteRouter } from '@ressjs/vite-router'
-
-const app = express()
-
-// Serve static assets
-app.use('/assets', express.static('dist/client/assets'))
-
-// Create router with production settings
-const router = createViteRouter({
-  isProduction: true,
-  enablePlatformDetection: true
-})
-
-app.use('/', router)
-app.listen(3000)
+npx @ressjs/create-ress-app my-app
 ```
 
-## 🐛 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
+Use the `@ressjs/cli` commands (`ress dev`, `ress build`, `ress start`) to run it.
 
-### `index.html` opcional
+## License
 
-El router usa `index.html` del proyecto como shell cuando existe. Si no existe, usa una plantilla interna mínima con el contenedor `#root`; el SSR, los estilos y el entry cliente se inyectan igual. Mantener `index.html` permite personalizar el documento.
+Proprietary. See [LICENSE](./LICENSE).

package/dist/client/entry.d.mts

@@ -1,2 +1,2 @@
-export { Script, Style } from '@ressjs/assets/client';
-export type { ScriptProps, StyleProps } from '@ressjs/assets/client';
+export { Head, Script, Style } from '@ressjs/assets/client';
+export type { HeadProps, ScriptProps, StyleProps } from '@ressjs/assets/client';

package/dist/client/entry.mjs

@@ -1 +1 @@
-export { Script, Style } from '@ressjs/assets/client';
+export { Head, Script, Style } from '@ressjs/assets/client';

package/dist/client/index.d.ts

@@ -1,2 +1,2 @@
-export { Script, Style } from '@ressjs/assets';
-export type { ScriptProps, StyleProps } from '@ressjs/assets';
+export { Head, Script, Style } from '@ressjs/assets/client';
+export type { HeadProps, ScriptProps, StyleProps } from '@ressjs/assets/client';

package/dist/client/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Style = exports.Script = void 0;
-// CJS compatibility entry. The ESM entrypoint is `entry.mts` and uses the
-// browser-oriented `@ressjs/assets/client` export.
-var assets_1 = require("@ressjs/assets");
-Object.defineProperty(exports, "Script", { enumerable: true, get: function () { return assets_1.Script; } });
-Object.defineProperty(exports, "Style", { enumerable: true, get: function () { return assets_1.Style; } });
+exports.Style = exports.Script = exports.Head = void 0;
+// Compatibility alias. The implementation is owned by @ressjs/assets.
+var client_1 = require("@ressjs/assets/client");
+Object.defineProperty(exports, "Head", { enumerable: true, get: function () { return client_1.Head; } });
+Object.defineProperty(exports, "Script", { enumerable: true, get: function () { return client_1.Script; } });
+Object.defineProperty(exports, "Style", { enumerable: true, get: function () { return client_1.Style; } });

package/dist/config/codegen.d.ts

@@ -1,4 +1,13 @@
 import type { PlatformConfig } from './types';
+/**
+ * Tipos generados a partir de lo que el proyecto declara.
+ *
+ * Sin esto, declarar un token de plataforma propio en `ress.config.ts` funciona
+ * en tiempo de ejecución pero el editor no lo conoce: el desarrollador escribe
+ * `'kaios'` y no recibe ni sugerencia ni error si lo escribe mal. Los archivos se
+ * generan, no se versionan, y se rehacen cuando cambia la configuración que los
+ * origina.
+ */
 /**
  * Amplía `PlatformValueMap` de `@ressjs/platform` con los tokens del proyecto.
  *
@@ -21,3 +30,9 @@ export declare function generateProjectConfigTypes(values: Record<string, unknow
  * volvería a generar, en un ciclo que no termina.
  */
 export declare function writeGeneratedTypes(root: string, files: Record<string, string>): Promise<string[]>;
+/**
+ * Genera `types/` sólo para proyectos con `tsconfig.json` cuya configuración se cargó con
+ * `loadConfig`. La usan el plugin al arrancar y `ress info`, para que un
+ * proyecto recién creado o un clon limpio tengan sus tipos sin levantar nada.
+ */
+export declare function writeProjectTypes(root: string, platform: PlatformConfig): Promise<string[]>;