vanilla-jet 1.3.1 → 1.4.0

package/.github/workflows/deploy.yml

@@ -5,38 +5,45 @@ on:
     branches:
       - main
 
+permissions:
+  id-token: write
+  contents: write
+
 jobs:
   release:
     name: Publish
     runs-on: ubuntu-latest
-    environment: rep
 
     steps:
     - name: Check out the repository
-      uses: actions/checkout@v3
+      uses: actions/checkout@v4
 
     - name: Setup Node.js
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
-        node-version: '16'
-        registry-url: 'https://registry.npmjs.org/'
+        node-version: '24'
+        registry-url: 'https://registry.npmjs.org'
 
     - name: Install dependencies
-      run: npm install
+      run: npm ci
+
+    - name: Build
+      run: npm run build --if-present
+
+    - name: Test
+      run: npm test
 
     - name: Publish to npm
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       run: npm publish
 
     - name: Configure git identity
       run: |
-        git config --global user.email "actions@github.com"
-        git config --global user.name "GitHub Actions"
+        git config user.email "actions@github.com"
+        git config user.name "GitHub Actions"
 
     - name: Get version from package.json
       id: get_version
-      run: echo "::set-output name=version::$(node -p "require('./package.json').version")"
+      run: echo "version=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"
 
     - name: Check if tag exists
       run: |

package/.grunt/compile_html.js

@@ -10,18 +10,9 @@ let Functions = require('../framework/functions.js');
 let Dipper = require('../framework/dipper.js');
 let Config = require(processCwd() + '/config.js');
 
-// -- Get environment
-let env = process.argv[2] || 'development';
-if (env === 'dev') { env = 'development'; }
-if (env === 'build:qa') { env = 'qa'; }
-if (env === 'build:staging') { env = 'staging'; }
-if (env === 'build:prod') { env = 'production'; }
-
 // -- Init Dipper
 let settings = Config.settings;
-settings['shared']['environment'] = env;
-
-let opts = settings[env] || {},
+let opts = settings['profile'] || {},
   shared = settings['shared'] || {};
 const dipper = new Dipper(opts, shared);
 

package/.scripts/run_vite.js

@@ -0,0 +1,36 @@
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function resolveConsumerRoot() {
+  return process.cwd()
+    .replace('/node_modules/vanilla-jet', '')
+    .replace('/.scripts', '')
+    .replace('/.grunt', '');
+}
+
+function main() {
+  const action = process.argv[2] || 'dev';
+  const viteCommand = action === 'build' ? 'build' : 'serve';
+  const packageRoot = path.resolve(__dirname, '..');
+  const consumerRoot = resolveConsumerRoot();
+  const vitePackageJson = require.resolve('vite/package.json', { paths: [packageRoot] });
+  const viteBin = path.join(path.dirname(vitePackageJson), 'bin/vite.js');
+  const configFile = path.join(packageRoot, 'vite.config.js');
+
+  const args = [viteBin, viteCommand, '--config', configFile];
+  if (viteCommand === 'serve') {
+    args.push('--host');
+  }
+
+  const result = spawnSync(process.execPath, args, {
+    stdio: 'inherit',
+    cwd: consumerRoot,
+    env: Object.assign({}, process.env, {
+      VANILLAJET_PACKAGE_ROOT: packageRoot
+    })
+  });
+
+  process.exit(typeof result.status === 'number' ? result.status : 1);
+}
+
+main();

package/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable project changes are documented in this file.
+
+The format follows a structure inspired by Keep a Changelog and semantic versioning.
+
+## [1.4.0] - 2026-02-19
+
+### Highlights
+
+- Added `dev:vite` and `build:vite` scripts to introduce a Vite-first JS/LESS pipeline without removing legacy Gulp commands.
+- Added `vite.config.js` and `.scripts/run_vite.js` to support consumer-root execution, compatibility output in `public/`, and a dev helper route (`/__vanillajet__/`).
+- Added CLI support in `bin.js` for `npx vanilla-jet dev:vite` and `npx vanilla-jet build:vite`.
+- Updated `README.md` to document legacy vs modern workflows for HU 2.1.
+
+## [1.3.6] - 2026-02-19
+
+### Highlights (v1.3.6)
+
+- Fixed protected directory typo in `framework/router.js`: `node_mudules` -> `node_modules`.
+- Fixed stability issues in `framework/dipper.js`:
+  - `includeAnimations()` now calls the existing `includeAnimation()`.
+  - `dequeueStyle()` and `dequeueScript()` now read `item.requires` correctly.
+  - Dependency dequeue now runs only when explicitly requested (`dependencies === true`).
+- Fixed `package.json` recursive `test` script to avoid infinite loop and keep `npm test` stable.
+- Completed HU 1.4 hardening milestone and updated roadmap tracking.
+
+### Compatibility notes (v1.3.6)
+
+- No public API changes.
+- No route contract changes.
+- This patch only hardens runtime behavior and developer workflow reliability.
+
+## [1.3.5] - 2026-02-19
+
+### Highlights (v1.3.5)
+
+- Added safe precompressed fallback in `response.render()` for HTML templates: `.br` (when enabled and accepted) -> `.gz` (when accepted) -> original HTML.
+- Wired `Response` to server profile options, so HTML negotiation follows `settings.profile.enable_precompressed_negotiation`.
+- Added `Vary: Accept-Encoding` for negotiated HTML responses and support for `Accept-Encoding` quality params.
+- Updated documentation and roadmap status for HU 1.3.
+
+## [1.3.4] - 2026-02-19
+
+### Highlights (v1.3.4)
+
+- Added optional static precompressed negotiation flag: `settings.profile.enable_precompressed_negotiation`.
+- Static files now resolve safely with fallback chain: `.br` (when enabled and accepted) -> `.gz` (when accepted) -> original file.
+- Static compression negotiation now handles `Accept-Encoding` values with quality params (for example `gzip;q=1.0`).
+- `Vary: Accept-Encoding` is set for negotiated static responses.
+
+## [1.3.3] - 2026-02-18
+
+### Added
+
+- Static metadata in-memory cache in `framework/router.js` (`size`, `lastModified`, `etag`) to reduce repeated filesystem work.
+- Conditional request handling for static files using `If-None-Match` and `If-Modified-Since`.
+- Static response headers: `ETag`, `Last-Modified`, and `Cache-Control: no-cache, must-revalidate`.
+
+### Changed
+
+- Static files can now return `304 Not Modified` when validators match, reducing transfer for repeated requests.
+- Conditional requests force metadata refresh before deciding `304`, so clients can still see new content without hard reload.
+
+### Compatibility notes
+
+- No route or filename contract changes.
+- No impact on dynamic endpoints behavior.
+
+## [1.3.2] - 2026-02-18
+
+### Current documented state
+
+- Released version `1.3.2` of `vanilla-jet`.
+- The framework exports `Server` from `index.js` for simple integration in Node.js projects.
+- Includes a Gulp-based build pipeline for:
+  - JavaScript minification and concatenation.
+  - LESS/CSS compilation and minification.
+  - HTML template compilation with Nunjucks.
+  - Generation of compressed `.gz` artifacts.
+- Includes HTTP server and optional HTTPS server (self-managed certificates) in `framework/server.js`.
+- Includes internal router with Backbone-style route support (`:param`, `*splat`, optional segments).
+- Includes resource utilities (scripts, styles, meta tags, sentry, environment) in `framework/dipper.js`.
+
+### Compatibility note
+
+- This version keeps the historical behavior expected by existing projects.
+- Future improvements are planned with backward compatibility in mind. See `ROADMAP_INTEGRAL.md`.
+
+[1.3.3]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.3
+[1.3.2]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.2
+[1.3.4]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.4
+[1.3.5]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.5
+[1.3.6]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.3.6
+[1.4.0]: https://github.com/nalancer08/VanillaJet/releases/tag/v1.4.0

package/README.md

@@ -1,6 +1,144 @@
-<p align="center">
-  <img src="https://github.com/nalancer08/App-Builders/blob/master/Logos/logo_monocromatico_horizontal_.png">
-</p>
-
 # VanillaJet
-NodeJS framework to create apps with jQuery or VueJS over a SPA (Single Page Application), the framework helps to create the server and add dependencia, includes router and server side functions as routes (internal API).
+
+Node.js framework for building SPA applications with a JS/CSS/HTML build pipeline, HTTP/HTTPS server, internal router, and template rendering utilities.
+
+![VanillaJet logo](https://github.com/nalancer08/App-Builders/blob/master/Logos/logo_monocromatico_horizontal_.png)
+
+## Current version
+
+- Version: `1.4.0`
+- Changelog: see [`CHANGELOG.md`](./CHANGELOG.md)
+- Improvement plan (performance and backward compatibility): see `ROADMAP_INTEGRAL.md`
+
+## Requirements
+
+- Node.js `>=16` recommended
+- npm `>=8`
+
+## Installation
+
+```bash
+npm install vanilla-jet
+```
+
+If you are working in this local repository:
+
+```bash
+npm install
+```
+
+## Quick start
+
+### 1) Export the server from your project
+
+```js
+const { Server } = require('vanilla-jet');
+```
+
+### 2) Define endpoints (classes)
+
+Each endpoint should expose a `name` and register routes with the router in the constructor.
+
+```js
+class AppEndpoint {
+  constructor(router) {
+    this.name = 'AppEndpoint';
+    router.addRoute('get', '/', 'AppEndpoint.index');
+  }
+
+  index(request, response) {
+    response.setBody('Hello VanillaJet');
+    response.respond();
+  }
+}
+```
+
+### 3) Start the server
+
+```js
+const { Server } = require('vanilla-jet');
+const Config = require('./config');
+
+new Server(Config, [AppEndpoint]).start();
+```
+
+## Available commands
+
+From this repository:
+
+- `npm run setup`: generates a base `vanillaJet.package.json` if it does not exist.
+- `npm run dev`: legacy Gulp build + watcher for development.
+- `npm run dev:vite`: modern Vite dev server for JS/LESS DX (keeps Nunjucks flow unchanged).
+- `npm run build:vite`: modern Vite build for JS/LESS output in `public/`.
+- `npm run build:qa`: build for QA.
+- `npm run build:staging`: build for staging.
+- `npm run build:prod`: build for production.
+
+As CLI (`bin.js`):
+
+- `npx vanilla-jet setup`
+- `npx vanilla-jet dev`
+- `npx vanilla-jet build`
+- `npx vanilla-jet dev:vite`
+- `npx vanilla-jet build:vite`
+
+## Legacy vs Vite mode
+
+- Legacy (`npm run dev` / `npx vanilla-jet dev`):
+  - Keeps full historical Gulp pipeline (JS minify+concat, LESS, templates, gzip artifacts).
+  - Recommended when you need 100% historical behavior.
+- Vite (`npm run dev:vite` / `npx vanilla-jet dev:vite`):
+  - Focuses on JS/LESS developer experience with faster feedback.
+  - Does not replace Nunjucks compilation in this stage (HU 2.1), so template flow remains legacy.
+  - Dev helper page: open `http://localhost:5173/__vanillajet__/` to load the Vite entry.
+- Vite build (`npm run build:vite` / `npx vanilla-jet build:vite`):
+  - Generates `public/scripts/vanilla.min.js` and `public/styles/app.min.css`.
+  - Keeps existing legacy build commands available and unchanged.
+
+## Expected consumer project structure
+
+VanillaJet expects a structure similar to:
+
+- `assets/pages/home.html`
+- `assets/templates/**/*.html`
+- `assets/scripts/**/*.js`
+- `assets/styles/less/admin.less`
+- `public/` (compiled output)
+- `config.js`
+- `vanillaJet.package.json`
+
+## Build pipeline (summary)
+
+- Minifies JS and concatenates into `public/scripts/vanilla.min.js`
+- Compiles LESS and generates `public/styles/app.min.css`
+- Compiles templates and generates `public/pages/home.html`
+- Generates `.gz` versions of JS/CSS/HTML for compressed delivery
+
+## Compression negotiation (optional)
+
+You can enable precompressed static negotiation from `settings.profile`:
+
+```js
+module.exports = {
+  settings: {
+    profile: {
+      // Enables priority: .br -> .gz -> original file
+      enable_precompressed_negotiation: true
+    }
+  }
+};
+```
+
+Behavior details:
+
+- Default (`false`): keeps existing gzip behavior for supported static assets.
+- Enabled (`true`): if client accepts Brotli, server tries `.br` first.
+- Safe fallback: if `.br` or `.gz` does not exist, server serves the original file.
+- HTML rendering (`response.render`) also uses safe runtime fallback for precompressed templates (`.br`/`.gz`/original).
+
+## Additional documentation
+
+- Router: `docs/router.md`
+- Version history: [`CHANGELOG.md`](./CHANGELOG.md)
+- Roadmap and improvements: `ROADMAP_INTEGRAL.md`
+- Deployment templates (nginx + docker): `docs/deployment/`

package/ROADMAP_INTEGRAL.md

@@ -0,0 +1,248 @@
+# ROADMAP INTEGRAL - VanillaJet
+
+Documento canonico de planeacion por epicas e historias.
+Cada historia incluye su ciclo completo: fases, tareas, entregables, metricas, criterios y documentacion.
+
+## Objetivo
+
+- Modernizar el framework con `Vite` como base de DX.
+- Reducir dependencia de Node para servir frontend.
+- Adoptar `nginx` y Docker al final, con evidencia y sin romper legacy.
+
+## Reglas de ejecucion
+
+- Retrocompatibilidad primero.
+- Cambios sensibles con flags.
+- Todo cambio con medicion antes/despues.
+- Entregas pequenas y reversibles.
+
+---
+
+## EPIC 1 - Estabilidad base
+
+### HU 1.1 - Cache metadata + 304 (completada `v1.3.3`)
+
+#### Fases
+- F1: cache metadata.
+- F2: validacion condicional.
+- F3: no-regresion.
+
+#### Tareas
+- Cache `size/mtime/etag`.
+- Soporte `If-None-Match` y `If-Modified-Since`.
+
+#### Entregables
+- `framework/router.js` actualizado.
+
+#### Metricas
+- Menor latencia y menor I/O en estaticos repetidos.
+
+#### Criterios
+- `304` correcto.
+- Sin impacto en dinamico.
+
+#### Documentacion
+- `CHANGELOG.md`.
+
+### HU 1.2 - Negociacion `br/gz` estaticos (completada `v1.3.4`)
+
+#### Fases
+- F1: flag opt-in.
+- F2: fallback seguro.
+- F3: validacion.
+
+#### Tareas
+- `.br -> .gz -> original`.
+- `Vary: Accept-Encoding`.
+
+#### Entregables
+- `framework/router.js`.
+
+#### Metricas
+- Menor transferencia en cliente.
+
+#### Criterios
+- Fallback sin 404.
+
+#### Documentacion
+- `README.md`, `CHANGELOG.md`.
+
+### HU 1.3 - Fallback precompressed HTML (completada `v1.3.5`)
+
+#### Fases
+- F1: fallback runtime HTML.
+- F2: pruebas de ausencia de artefactos.
+- F3: release.
+
+#### Tareas
+- Resolver `.br/.gz/original` en `render`.
+
+#### Entregables
+- `framework/response.js`.
+
+#### Metricas
+- Menor peso de HTML inicial.
+
+#### Criterios
+- Sin errores por artefactos faltantes.
+
+#### Documentacion
+- `README.md`, `CHANGELOG.md`.
+
+### HU 1.4 - Hardening de bugs conocidos (completada `v1.3.6`)
+
+#### Fases
+- F1: correccion.
+- F2: smoke tests.
+- F3: patch release.
+
+#### Tareas
+- [x] `node_mudules -> node_modules`.
+- [x] fixes en `dipper`.
+- [x] fix script `test`.
+
+#### Entregables
+- Patch de estabilidad.
+
+#### Metricas
+- Menos errores silenciosos en runtime/build.
+
+#### Criterios
+- [x] `npm test` estable.
+
+#### Documentacion
+- `CHANGELOG.md` con nota de compatibilidad.
+
+---
+
+## EPIC 2 - Vite first (foco actual)
+
+### HU 2.1 - `dev:vite` y `build:vite` sin romper legacy (completada `v1.4.0`)
+
+#### Fases
+- F1: baseline.
+- F2: integrar scripts Vite.
+- F3: coexistencia con legacy.
+- F4: validacion en consumidor real.
+
+#### Tareas
+- [x] Config Vite (JS/LESS).
+- [x] Mantener Nunjucks en esta etapa.
+- [x] Documentar `dev` legacy vs `dev:vite`.
+
+#### Entregables
+- Config y scripts de Vite.
+
+#### Metricas
+- Arranque dev >= 40% mas rapido.
+- Rebuild incremental >= 50% mas rapido.
+
+#### Criterios
+- HMR estable.
+- Legacy intacto.
+
+#### Documentacion
+- `README.md` + `CHANGELOG.md`.
+
+### HU 2.2 - Node deja de servir frontend en modo moderno (pendiente)
+
+#### Fases
+- F1: contrato `legacy` vs `modern`.
+- F2: flag de transicion.
+- F3: validacion de compatibilidad.
+
+#### Tareas
+- Node solo API/dinamico en modo moderno.
+- Frontend servido por Vite (dev) y luego Nginx (prod).
+
+#### Entregables
+- Contrato por entorno.
+
+#### Metricas
+- Menos carga de static serving en Node.
+
+#### Criterios
+- Modo moderno sin dependencia de `response.render()`.
+- Modo legacy intacto.
+
+#### Documentacion
+- Guia de migracion de modo.
+
+---
+
+## EPIC 3 - Benchmark y decision gate
+
+### HU 3.1 - Go/No-Go de Nginx basado en datos (pendiente)
+
+#### Fases
+- F1: dise;o benchmark A/B.
+- F2: ejecucion.
+- F3: analisis.
+- F4: decision.
+
+#### Tareas
+- Medir p50/p95/p99, throughput, CPU, memoria.
+- Definir umbrales minimos de aprobacion.
+
+#### Entregables
+- Reporte benchmark.
+- Decision log Go/No-Go.
+
+#### Criterios
+- Decision trazable con evidencia.
+
+#### Documentacion
+- Documento benchmark + resumen tecnico.
+
+---
+
+## EPIC 4 - Adopcion final de infraestructura
+
+### HU 4.1 - Nginx oficial para consumidores (pendiente)
+
+#### Fases
+- F1: template.
+- F2: staging.
+- F3: guia de operacion.
+
+#### Tareas
+- `try_files`, SPA fallback, proxy a Node, cache y precompressed.
+
+#### Entregables
+- Template y guia.
+
+#### Documentacion
+- `docs/deployment/` + `README.md`.
+
+### HU 4.2 - Docker de referencia (pendiente)
+
+#### Fases
+- F1: Dockerfile.
+- F2: docker-compose.
+- F3: validacion server.
+
+#### Tareas
+- Definir imagenes, puertos y variables.
+- Documentar rollback.
+
+#### Entregables
+- Dockerfile y compose de referencia.
+
+#### Documentacion
+- `docs/deployment/` + `README.md`.
+
+---
+
+## Secuencia oficial de ejecucion
+
+1. HU 1.4
+2. HU 2.1
+3. HU 2.2
+4. HU 3.1
+5. HU 4.1
+6. HU 4.2
+
+## Estado global
+
+- Completado: HU 1.1, HU 1.2, HU 1.3, HU 1.4, HU 2.1.
+- Pendiente: HU 2.2, HU 3.1, HU 4.1, HU 4.2.

package/bin.js

@@ -9,39 +9,39 @@ const generatePackagesJson = require(path.join(__dirname, './.scripts/generate_p
 
 switch (args[0]) {
 
-    case 'setup':
-      generatePackagesJson();
-      break;
-    
-    case 'dev':
-      try {
-        execSync('npx gulp dev --env development', { stdio: 'inherit', cwd: __dirname });
-      } catch (error) {
-        console.error('Error ejecutando gulp:', error.message);
-      }
-      break;
-
-    case 'build:qa':
-      try {
-        execSync('npx gulp build --env qa', { stdio: 'inherit', cwd: __dirname });
-      } catch (error) {
-        console.error('Error ejecutando gulp:', error.message);
-      }
-      break;
-
-    case 'build:staging':
-      try {
-        execSync('npx gulp build --env staging', { stdio: 'inherit', cwd: __dirname });
-      } catch (error) {
-        console.error('Error ejecutando gulp:', error.message);
-      }
-      break;
-
-    case 'build:prod':
-      try {
-        execSync('npx gulp build --env production', { stdio: 'inherit', cwd: __dirname });
-      } catch (error) {
-        console.error('Error ejecutando gulp:', error.message);
-      }
-      break;
+  case 'setup':
+    generatePackagesJson();
+    break;
+
+  case 'dev':
+    try {
+      execSync('npx gulp dev --env development', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
+
+  case 'build':
+    try {
+      execSync('npx gulp build', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
+
+  case 'dev:vite':
+    try {
+      execSync('node ./.scripts/run_vite.js dev', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing Vite dev:', error.message);
+    }
+    break;
+
+  case 'build:vite':
+    try {
+      execSync('node ./.scripts/run_vite.js build', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing Vite build:', error.message);
+    }
+    break;
 }

package/docs/deployment/Dockerfile.app.example

@@ -0,0 +1,19 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install dependencies first for better layer cache
+COPY package*.json ./
+RUN npm ci
+
+# Copy app source
+COPY . .
+
+# Build command should generate static output under /app/public
+# Replace with your app build script (for example: npm run build:vite)
+RUN npm run build:vite || npm run build:prod
+
+EXPOSE 8080
+
+# Replace with your actual backend start command
+CMD ["node", "index.js"]