vanilla-jet 1.5.4 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable project changes are documented in this file.
 
 The format follows a structure inspired by Keep a Changelog and semantic versioning.
 
+## [1.6.0] - 2026-06-29
+
+### Added
+
+- **Template externalization (opt-in):** `settings.profile.externalize_templates`. `compile_html.js`
+  moves `<script type="text/template">` blocks out of the page into a cacheable `public/scripts/templates.js`
+  (loaded `defer` before the app bundle, so views still find their templates in the DOM at boot). Shrinks
+  the initial HTML dramatically; the templates file is brotli + immutable + service-worker cached. The SW
+  precache now includes `templates.js`.
+
+### Fixed
+
+- **Watch keeps precompressed assets fresh:** `compressBr` now runs in the LESS/JS watch series, so `.gz`/`.br`
+  no longer go stale on incremental dev rebuilds.
+
+### Notes
+
+- Recommended: enable caching features (`enable_service_worker`, `externalize_templates`, precompression,
+  immutable) in `qa`/`production`; keep `enable_service_worker` **off in development` so a cache-first SW does
+  not serve stale assets during rapid rebuilds.
+
+## [1.5.5] - 2026-06-28
+
+### Changed
+
+- **Fingerprinted assets are now cached immutably.** Static requests carrying a `?v=` (the
+  `?v=size-mtime` fingerprint from `dipper.versionedUrl`) are served `Cache-Control: public,
+  max-age=31536000, immutable`; non-versioned assets keep `no-cache, must-revalidate`. This eliminates
+  per-asset revalidation round-trips for clients without the service worker (notably native WebViews).
+
 ## [1.5.4] - 2026-06-28
 
 ### Fixed

package/README.md

@@ -1,19 +1,23 @@
 # VanillaJet
 
-Node.js framework for building SPA applications with a JS/CSS/HTML build pipeline, HTTP/HTTPS server, internal router, and template rendering utilities.
+Node.js framework for building SPA applications: a Gulp build pipeline (JS/CSS/HTML), a lightweight
+HTTP/HTTPS server, an internal router, and template/resource utilities — with first-class, opt-in
+performance features (Brotli, immutable caching, a generated service worker, deferred scripts, and
+template externalization).
 
 ![VanillaJet logo](https://github.com/nalancer08/App-Builders/blob/master/Logos/logo_monocromatico_horizontal_.png)
 
 ## Current version
 
-- Version: `1.4.3`
-- Changelog: see [`CHANGELOG.md`](./CHANGELOG.md)
-- Improvement plan (performance and backward compatibility): see `ROADMAP_INTEGRAL.md`
+- Version: `1.6.0`
+- Changelog: [`CHANGELOG.md`](./CHANGELOG.md)
+- **Full project docs (architecture, runtime, build, deployment, perf): [`master.md`](./master.md)**
+- Roadmap: [`ROADMAP_INTEGRAL.md`](./ROADMAP_INTEGRAL.md)
 
 ## Requirements
 
-- Node.js `>=16` recommended
-- npm `>=8`
+- Node.js `>= 18` (tested on 24)
+- npm `>= 8`
 
 ## Installation
 
@@ -21,124 +25,110 @@ Node.js framework for building SPA applications with a JS/CSS/HTML build pipelin
 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
+// index.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.
+const Config = require('./config');
 
-```js
 class AppEndpoint {
   constructor(router) {
     this.name = 'AppEndpoint';
-    router.addRoute('get', '/', 'AppEndpoint.index');
+    router.setDefaultRoute('home');                  // maps "/"
+    router.addRoute('get', '/home', 'AppEndpoint.home');
   }
-
-  index(request, response) {
-    response.setBody('Hello VanillaJet');
-    response.respond();
+  home(request, response) {
+    response.render(request, 'home.html');           // streams public/pages/home.html
+    return true;                                      // <- mark the request as handled
   }
 }
-```
-
-### 3) Start the server
-
-```js
-const { Server } = require('vanilla-jet');
-const Config = require('./config');
 
 new Server(Config, [AppEndpoint]).start();
 ```
 
-## Available commands
+## Configuration (`config.js`)
 
-From this repository:
+Two shapes are supported (both resolved automatically):
 
-- `npm run setup`: generates a base `vanillaJet.package.json` if it does not exist.
-- `npm run dev`: build + watcher for development.
-- `npm run build:qa`: build for QA.
-- `npm run build:staging`: build for staging.
-- `npm run build:prod`: build for production.
-- `npm run benchmark:static`: runs reproducible static serving benchmark (cold/warm).
+```js
+// Legacy (keyed by active profile name, selected with `--p qa`)
+module.exports = {
+  profile: process.argv... ,                 // 'development' | 'qa' | 'production'
+  settings: {
+    development: { port: 1234, api_url: '...' },
+    qa:          { port: 443,  api_url: '...' },
+    production:  { port: 443,  api_url: '...' },
+    shared:   { site_name: 'My App', environment: 'qa', sentry: {...} },
+    security: { pass_salt: '...', token_salt: '...' }
+  }
+};
 
-As CLI (`bin.js`):
+// Nested (single profile)
+module.exports = { settings: { profile: { port: 8080, api_url: '...' }, shared: {...}, security: {...} } };
+```
 
-- `npx vanilla-jet setup`
-- `npx vanilla-jet dev`
-- `npx vanilla-jet build`
+### Profile options (all optional)
 
-## Expected consumer project structure
+| Option | Default | What it does |
+|---|---|---|
+| `port` | `8080` | Listen port. `process.env.PORT` wins (Cloud Run/Heroku). |
+| `enable_precompressed_negotiation` | `false` | Serve `.br` → `.gz` → original via `Accept-Encoding`. |
+| `enable_service_worker` | `false` | Generate + serve a cache-first service worker. **Recommended: on in prod/qa, off in dev.** |
+| `service_worker` | — | `{ cache_prefix, on_demand_prefixes, precache, precache_exclude }`. Precache is auto-derived from `vanillaJet.package.json`. |
+| `defer_scripts` | `false` | Add `defer` to non-async scripts so they don't block parsing. |
+| `externalize_templates` | `false` | Move `<script type="text/template">` blocks out of the page into a cacheable `public/scripts/templates.js`. |
+| `request_timeout_ms` / `headers_timeout_ms` / `keep_alive_timeout_ms` | `30000` / `35000` / `5000` | Defensive server timeouts. |
+| `https_server` / `self_managed_certs` | `false` | HTTP/2 with self-managed `key`/`cert`. |
 
-VanillaJet expects a structure similar to:
+## Commands
 
-- `assets/pages/home.html`
-- `assets/templates/**/*.html`
-- `assets/scripts/**/*.js`
-- `assets/styles/less/admin.less`
-- `public/` (compiled output)
-- `config.js`
-- `vanillaJet.package.json`
+CLI (`bin.js`): `npx vanilla-jet setup | dev | build | build:qa | build:staging | build:prod`
 
-## Build pipeline (summary)
+From this repo: `npm run dev` · `npm run build:prod` · `npm test` · `npm run benchmark:static`
 
-Gulp-based pipeline (no Grunt):
+## Expected consumer structure
 
-- 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
+```
+assets/pages/home.html · assets/templates/**/*.html · assets/scripts/**/*.js · assets/styles/less/admin.less
+config.js · vanillaJet.package.json · public/ (build output)
+```
 
-## Compression negotiation (optional)
+## Build pipeline (Gulp)
 
-You can enable precompressed static negotiation from `settings.profile`:
+- Minifies + concatenates JS → `public/scripts/vanilla.min.js`
+- Compiles LESS → `public/styles/app.min.css`
+- Compiles templates → `public/pages/home.html` (+ optional `templates.js`)
+- Precompresses every `.js`/`.css`/`.html` to `.gz` + `.br`
+- Generates the service worker (when enabled)
 
-```js
-module.exports = {
-  settings: {
-    profile: {
-      // Enables priority: .br -> .gz -> original file
-      enable_precompressed_negotiation: true
-    }
-  }
-};
-```
-
-Behavior details:
+## Performance features (opt-in)
 
-- 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).
+- **Brotli + gzip** precompression with `Accept-Encoding` negotiation and safe fallback.
+- **Immutable caching**: fingerprinted assets (`?v=size-mtime`) are served `Cache-Control: public,
+  max-age=31536000, immutable`; HTML and unversioned assets stay `no-cache`. Big win for clients
+  without the service worker (e.g. native WebViews).
+- **Service worker** (cache-first), precache auto-derived from `vanillaJet.package.json`, content-pinned
+  cache name, `ignoreSearch` for fingerprinted URLs, and an inline registration helper
+  (`dipper.includeServiceWorker()`, web-only with a `window.__VJ_DISABLE_SW__` opt-out for WebViews).
+- **`defer` scripts** and **template externalization** to shrink the render-blocking critical path.
 
-## Static performance notes (HU 2.1)
+See [`master.md`](./master.md) §12–§17 and [`docs/benchmark-static.md`](./docs/benchmark-static.md).
 
-Static serving includes a warm-path optimization focused on Node runtime latency:
+## Testing
 
-- Reuses static resolution for repeated requests (`route + accept-encoding`).
-- Keeps conditional revalidation (`ETag`/`Last-Modified`) strict so reload reflects changes immediately.
-- Keeps streaming strategy for large assets (`fs.createReadStream`) with tuned chunk size.
-- Preserves conditional cache behavior (`ETag`/`Last-Modified` + `304`) and precompressed fallback contract.
+```bash
+npm test                 # node --test (router, dipper, config, static serving, service worker)
+npm run benchmark:static # reproducible static-serving benchmark (cold/warm)
+```
 
-Benchmark guide:
+## Deployment
 
-- [`docs/benchmark-static.md`](./docs/benchmark-static.md)
+Templates (nginx + Docker) in [`docs/deployment/`](./docs/deployment/). Honors `process.env.PORT`, so
+PaaS runtimes (Cloud Run, Heroku) work without config changes. Enable caching features in prod/qa
+profiles; keep them off in `development` for fresh iteration.
 
-## Additional documentation
+## More docs
 
-- Router: `docs/router.md`
-- Benchmark: [`docs/benchmark-static.md`](./docs/benchmark-static.md)
-- Version history: [`CHANGELOG.md`](./CHANGELOG.md)
-- Roadmap and improvements: `ROADMAP_INTEGRAL.md`
-- Deployment templates (nginx + docker): `docs/deployment/`
+- **[`master.md`](./master.md)** — full architecture, runtime flow, perf playbook, upgrade notes.
+- [`docs/router.md`](./docs/router.md) · [`CHANGELOG.md`](./CHANGELOG.md) · [`ROADMAP_INTEGRAL.md`](./ROADMAP_INTEGRAL.md)

package/framework/router.js

@@ -139,7 +139,10 @@ class Router {
               }
 
               let metadata = staticFile.metadata;
-              let staticHeaders = obj.buildStaticHeaders(extHeader, staticCandidates, staticFile.contentEncoding, metadata);
+              // Fingerprinted assets (requested with ?v=size-mtime) are safe to cache forever:
+              // any content change produces a new URL. Everything else keeps revalidation.
+              let isImmutable = Boolean(request.get('v'));
+              let staticHeaders = obj.buildStaticHeaders(extHeader, staticCandidates, staticFile.contentEncoding, metadata, isImmutable);
 
               if (obj.isNotModified(req, metadata)) {
                 let notModifiedHeaders = Object.assign({}, staticHeaders);
@@ -280,7 +283,7 @@ class Router {
     return `${route}|${normalizedEncodings}`;
   }
 
-  buildStaticHeaders(extHeader, candidates, contentEncoding, metadata) {
+  buildStaticHeaders(extHeader, candidates, contentEncoding, metadata, isImmutable) {
     let staticHeaders = Object.assign({}, extHeader);
     if (contentEncoding) {
       staticHeaders['Content-Encoding'] = contentEncoding;
@@ -292,8 +295,15 @@ class Router {
     staticHeaders['Content-Length'] = metadata.size;
     staticHeaders['ETag'] = metadata.etag;
     staticHeaders['Last-Modified'] = metadata.lastModified;
-    // Force revalidation to keep clients fresh without hard reload.
-    staticHeaders['Cache-Control'] = 'no-cache, must-revalidate';
+    if (isImmutable) {
+      // Fingerprinted URL (?v=): cache for a year and skip revalidation entirely.
+      // This is the big win for clients without the service worker (e.g. native WebViews),
+      // which otherwise revalidate every asset on every load.
+      staticHeaders['Cache-Control'] = 'public, max-age=31536000, immutable';
+    } else {
+      // Non-versioned assets: force revalidation to keep clients fresh without a hard reload.
+      staticHeaders['Cache-Control'] = 'no-cache, must-revalidate';
+    }
     return staticHeaders;
   }
 

package/gulpfile.js

@@ -142,7 +142,8 @@ function watchFiles(cb) {
     buildLess,
     compressCss,
     compileTemplates,
-    generateServiceWorker
+    generateServiceWorker,
+    compressBr
   ));
 
   // Watch HTML files
@@ -159,7 +160,8 @@ function watchFiles(cb) {
     cleanMinified,
     compressJs,
     compileTemplates,
-    generateServiceWorker
+    generateServiceWorker,
+    compressBr
   ));
   
   cb();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-jet",
-  "version": "1.5.4",
+  "version": "1.6.0",
   "description": "VannilaJet framework",
   "main": "index.js",
   "bin": {

package/scripts/compile_html.js

@@ -184,7 +184,7 @@ function replaceInclude(lines, originalLine, templateCompiled) {
 // -- Step 4
 async function createHTMLFile(content, filePath) {
   const { minify } = require('html-minifier-terser');
-  const minified = await minify(content, {
+  let minified = await minify(content, {
     collapseWhitespace: true,
     collapseInlineTagWhitespace: true,
     removeComments: true,
@@ -195,6 +195,14 @@ async function createHTMLFile(content, filePath) {
     minifyJS: true
   });
 
+  // -- Externalize <script type="text/template"> blocks into public/scripts/templates.js
+  // (opt-in via settings.profile.externalize_templates). The page shrinks to ~the shell;
+  // templates load from a separate cacheable file (brotli + SW + immutable) BEFORE the app
+  // bundle (defer + document order), so views still find their templates in the DOM at boot.
+  if (opts.externalize_templates) {
+    minified = externalizeTemplates(minified);
+  }
+
   const publicPath = path.join(processCwd(), '/public/pages');
   fs.mkdirSync(publicPath, { recursive: true });
   const absolutePath = path.join(publicPath, filePath);
@@ -210,6 +218,45 @@ async function createHTMLFile(content, filePath) {
   console.log(chalk.green(`Created gzipped version at: ${absolutePath}.gz`));
 }
 
+// -- Move all <script type="text/template"> blocks out of the page into
+// public/scripts/templates.js (a tiny injector that adds them to the DOM). Returns the
+// page HTML with those blocks replaced by a single deferred <script> tag (placed where the
+// first block was — before the app bundle, so it runs first by document order).
+function externalizeTemplates(html) {
+  const templateRegex = /<script\b[^>]*\btype\s*=\s*["']text\/template["'][^>]*>[\s\S]*?<\/script>/gi;
+  const blocks = html.match(templateRegex) || [];
+  if (!blocks.length) {
+    return html;
+  }
+
+  const scriptsDir = path.join(processCwd(), 'public', 'scripts');
+  fs.mkdirSync(scriptsDir, { recursive: true });
+
+  const payload = blocks.join('\n');
+  // External file → a literal </script> inside the payload is harmless (no inline HTML parser).
+  const injector =
+    '(function(){var c=document.createElement("div");c.style.display="none";' +
+    'c.setAttribute("data-vj-templates","");c.innerHTML=' + JSON.stringify(payload) + ';' +
+    'document.body.insertBefore(c,document.body.firstChild);})();';
+
+  const templatesPath = path.join(scriptsDir, 'templates.js');
+  fs.writeFileSync(templatesPath, injector, 'utf8');
+  fs.writeFileSync(templatesPath + '.gz', zlib.gzipSync(injector, { level: 9 }));
+
+  const stats = fs.statSync(templatesPath);
+  const version = `${stats.size}-${Math.floor(stats.mtimeMs)}`;
+  const tag = `<script defer src="/public/scripts/templates.js?v=${version}"></script>`;
+
+  let inserted = false;
+  const result = html.replace(templateRegex, () => {
+    if (!inserted) { inserted = true; return tag; }
+    return '';
+  });
+
+  console.log(chalk.green(`VanillaJet - externalized ${blocks.length} templates to public/scripts/templates.js`));
+  return result;
+}
+
 // -- Helpers
 function cleanALine(line) {
   line = line.replaceAll(' ', '');

package/scripts/generate_sw.js

@@ -15,7 +15,8 @@ const TEMPLATE_PATH = path.join(__dirname, '..', 'framework', 'sw.template.js');
 const CORE_PRECACHE = [
 	'/public/styles/app.min.css',
 	'/public/scripts/vanilla.min.js',
-	'/public/scripts/core/vanillaJet.min.js'
+	'/public/scripts/core/vanillaJet.min.js',
+	'/public/scripts/templates.js'
 ];
 
 const DEFAULT_ON_DEMAND_PREFIXES = ['/public/animations/', '/public/images/'];

package/test/server.test.js

@@ -78,6 +78,17 @@ test('static asset is served with caching validators', async () => {
   assert.ok(res.headers.get('last-modified'), 'Last-Modified should be present');
 });
 
+test('fingerprinted (?v=) asset is cached immutable; plain asset revalidates', async () => {
+  const versioned = await fetch(`${baseUrl}/public/scripts/test.min.js?v=123-456`);
+  await versioned.arrayBuffer();
+  assert.equal(versioned.status, 200);
+  assert.match(versioned.headers.get('cache-control') || '', /immutable/);
+
+  const plain = await fetch(`${baseUrl}/public/scripts/test.min.js`);
+  await plain.arrayBuffer();
+  assert.match(plain.headers.get('cache-control') || '', /no-cache/);
+});
+
 test('conditional request returns 304 when ETag matches', async () => {
   const first = await fetch(`${baseUrl}/public/scripts/test.min.js`);
   const etag = first.headers.get('etag');