vanilla-jet 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable project changes are documented in this file.
 
 The format follows a structure inspired by Keep a Changelog and semantic versioning.
 
+## [1.5.0] - 2026-06-27
+
+### Added
+
+- **Service worker support (opt-in)** — `settings.profile.enable_service_worker`.
+  - `framework/sw.template.js`: generic cache-first worker (precache + on-demand prefixes).
+  - `scripts/generate_sw.js` + Gulp task `generateServiceWorker`: generates `public/sw.js` at build time.
+    - Precache list = core bundles (`app.min.css`, `vanilla.min.js`, `core/vanillaJet.min.js`) + LOCAL resources enqueued by the Dipper + `service_worker.precache` extras (existing files only).
+    - Cache name is content-pinned (md5 of `path:size-mtime`), so any asset change rotates the cache; `activate()` purges stale caches.
+    - Matches use `{ ignoreSearch: true }` to stay compatible with fingerprinted (`?v=`) asset URLs.
+  - `framework/router.js`: serves `/sw.js` from root scope with `Service-Worker-Allowed: /` and `Cache-Control: no-cache` when enabled.
+  - `framework/dipper.js`: `includeServiceWorker()` inline registration helper (web-only; honors `window.__VJ_DISABLE_SW__` to opt out and tear down inside native WebViews).
+  - Config knobs: `service_worker.precache`, `service_worker.on_demand_prefixes`, `service_worker.cache_prefix`.
+
+### Fixed
+
+- **Build-time environment injection regression (backward compatibility):** `scripts/compile_html.js`
+  again resolves the build environment (passed by Gulp via `--env`, forwarded as argv) and reads
+  `settings[env]`, restoring correct `api_url`/`environment` injection (`includeEnvironment()`). The 1.4.x
+  rewrite read a literal `settings['profile']` and also rendered the page content as a template name,
+  producing `API_URL="undefined"` and `template not found` for 1.3.x-shaped configs. `gulpfile.js` now
+  forwards `--env` to both `compile_html.js` and `generate_sw.js`.
+- **Broken dependency removed:** dropped `zlib@1.0.5` from `dependencies`. The framework uses Node's
+  built-in `zlib` (core modules take precedence), and the npm package has a native `node-waf` build step
+  that fails on modern Node — it broke `npm install`/`npm ci` for consumers. Pure dead weight.
+- **CLI build commands regression (backward compatibility):** `bin.js` again handles
+  `build:qa`, `build:staging` and `build:prod` (they map to `gulp build --env <env>`). 1.3.x consumers
+  call `npx vanilla-jet build:<env>`; the 1.4.x CLI had dropped these, so the build silently did nothing.
+- **Profile resolution regression (backward compatibility):** `framework/server.js` now resolves
+  `settings[options.profile] || settings['profile']`. Legacy consumers (1.3.x) that key settings by the
+  active profile name (e.g. `qa`, `production`) again receive their profile options instead of `{}`.
+- **PaaS port binding:** server now honors `process.env.PORT` (Cloud Run / Heroku) before `settings.profile.port`.
+- **Ephemeral port (`port: 0`) preserved:** port selection uses a nullish check instead of `|| 8080`, so a
+  deliberate `0` binds an ephemeral port instead of falling back to `8080`.
+
+### Testing
+
+- Added a real test harness (`test/`, `node --test`, no new deps) wired to `npm test`:
+  router, dipper, config-shape resolution, static serving (`200`/`304`/`404`), and service worker
+  generation + serving.
+
+### Compatibility notes
+
+- Service worker is **off by default**; existing apps are unaffected until they opt in.
+- Profile-resolution fix is backward compatible with both the legacy and the nested config shapes.
+
 ## [1.4.3] - 2026-02-19
 
 ### Removed

package/bin.js

@@ -28,4 +28,29 @@ switch (args[0]) {
       console.error('Error executing gulp:', error.message);
     }
     break;
+
+  // Environment-specific builds (restored for 1.3.x consumer compatibility).
+  case 'build:qa':
+    try {
+      execSync('npx gulp build --env qa', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
+
+  case 'build:staging':
+    try {
+      execSync('npx gulp build --env staging', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
+
+  case 'build:prod':
+    try {
+      execSync('npx gulp build --env production', { stdio: 'inherit', cwd: __dirname });
+    } catch (error) {
+      console.error('Error executing gulp:', error.message);
+    }
+    break;
 }

package/framework/dipper.js

@@ -385,6 +385,37 @@ Dipper.prototype.includeManifest = function() {
 	return tagString;
 }
 
+/**
+ * Inline registration for the VanillaJet service worker.
+ * Returns '' unless settings.profile.enable_service_worker is true.
+ * Web-only by design: a consumer running inside a native WebView can set
+ * `window.__VJ_DISABLE_SW__ = true` before this runs to opt out and tear down
+ * any previously installed worker (WebViews get no benefit and stuck SWs are
+ * hard to recover there).
+ */
+Dipper.prototype.includeServiceWorker = function() {
+
+	const obj = this;
+	if (!obj.options || !obj.options.enable_service_worker) {
+		return '';
+	}
+
+	return `
+		<script>
+			(function () {
+				if (!('serviceWorker' in navigator)) { return; }
+				if (window.__VJ_DISABLE_SW__) {
+					navigator.serviceWorker.getRegistration()
+						.then(function (registration) { if (registration) { registration.unregister(); } })
+						.catch(function (error) { console.error(error); });
+					return;
+				}
+				navigator.serviceWorker.register('/sw.js')
+					.catch(function (error) { console.error(error); });
+			})();
+		</script>`;
+}
+
 /**
  * Setup Sentry for error reporting on production and qa environments.
  */

package/framework/router.js

@@ -41,6 +41,7 @@ class Router {
     this.compressionMimes = [ 'css', 'js' ];
     this.compressionFiles = [ 'vanilla.min.js', 'app.min.css' ];
     this.enablePrecompressedNegotiation = Boolean(server?.options?.enable_precompressed_negotiation);
+    this.enableServiceWorker = Boolean(server?.options?.enable_service_worker);
 	}
 
 	routeToRegExp(route) {
@@ -99,10 +100,15 @@ class Router {
 					}
 				});
 
+				// -- Service worker: served from root scope so it can control the whole origin
+				if (!handled && !isMatch && obj.enableServiceWorker && request.path === '/sw.js') {
+					return obj.serveServiceWorker(res);
+				}
+
 				// -- Check static files
 				if (!handled && !isMatch) {
 
-					let ext = path.extname(request.path).replace('.', ''), 
+					let ext = path.extname(request.path).replace('.', ''),
             extHandled = false, 
             extHeader = {};
 					
@@ -369,6 +375,35 @@ class Router {
 		return this.defaultRoute;
 	}
 
+	serveServiceWorker(res) {
+		let obj = this;
+		let filename = path.join(obj.staticBasePath, 'public', 'sw.js');
+		fs.stat(filename, (err, stats) => {
+			if (err || !stats.isFile()) {
+				res.writeHead(404);
+				return res.end();
+			}
+			res.writeHead(200, {
+				'Content-Type': 'text/javascript; charset=utf-8',
+				// Allow the SW (served at /sw.js) to control the entire origin.
+				'Service-Worker-Allowed': '/',
+				// Keep the SW script itself fresh so updates roll out promptly.
+				'Cache-Control': 'no-cache'
+			});
+			let stream = fs.createReadStream(filename);
+			stream.on('error', () => {
+				res.writeHead(500);
+				res.end('Server Error');
+			});
+			res.on('close', () => {
+				if (!res.writableEnded) {
+					stream.destroy();
+				}
+			});
+			stream.pipe(res);
+		});
+	}
+
 	onNotFound(response) {
 		response.setStatus(404);
 		response.respond();

package/framework/server.js

@@ -23,16 +23,20 @@ class Server {
 
 	init(options, endpoints) {
 
-		let obj = this, 
-			settings = options.settings, 
-			opts = settings['profile'] || {}, 
-			shared = settings['shared'] || {}, 
+		let obj = this,
+			settings = options.settings,
+			// Resolve the active profile. Legacy consumers key settings by the active
+			// profile name (settings[options.profile], e.g. 'qa'); newer ones expose a
+			// single nested 'profile' object. Support both for backward compatibility.
+			opts = settings[options.profile] || settings['profile'] || {},
+			shared = settings['shared'] || {},
 			security = settings['security'] || {};
 
 		_.defaults(opts, {
 			https_server: false,
 			wsServer: false,
       enable_precompressed_negotiation: false,
+      enable_service_worker: false,
       request_timeout_ms: 30000,
       headers_timeout_ms: 35000,
       keep_alive_timeout_ms: 5000
@@ -70,8 +74,11 @@ class Server {
 	}
 
 	start() {
+		let boundPort = (this.httpx && this.httpx.address && this.httpx.address())
+			? this.httpx.address().port
+			: (process.env.PORT || this.options.port || 8080);
 		this.log('__________________  VanillaJet Server started  ___________________');
-		this.log(` >           Running on 0.0.0.0:${this.options.port}/           < `);
+		this.log(` >           Running on 0.0.0.0:${boundPort}/           < `);
 		this.log('------------------------------------------------------------------');
 	}
 
@@ -97,7 +104,13 @@ class Server {
     obj.httpx.requestTimeout = Number(obj.options.request_timeout_ms) || 30000;
     obj.httpx.headersTimeout = Number(obj.options.headers_timeout_ms) || 35000;
     obj.httpx.keepAliveTimeout = Number(obj.options.keep_alive_timeout_ms) || 5000;
-    obj.httpx.listen(obj.options.port || 8080);
+    // Honor process.env.PORT first so PaaS runtimes (Cloud Run, Heroku, …) that
+    // inject the listening port at runtime work without config changes. Use a
+    // nullish check so a deliberate port 0 (ephemeral) is preserved.
+    let port = (process.env.PORT !== undefined && process.env.PORT !== '')
+      ? process.env.PORT
+      : (obj.options.port !== undefined && obj.options.port !== null ? obj.options.port : 8080);
+    obj.httpx.listen(port);
   }
 
 	log(value) {

package/framework/sw.template.js

@@ -0,0 +1,82 @@
+/**
+ * VanillaJet service worker template.
+ *
+ * This file is NOT used as-is. The build (scripts/generate_sw.js) replaces the
+ * __PLACEHOLDERS__ below with values derived from the compiled assets and the
+ * consumer config, and writes the result to public/sw.js.
+ *
+ * Strategy: cache-first for a pinned set of local bundles/styles/plugins and an
+ * on-demand cache for prefixes (animations, images). The cache name is pinned to
+ * a content hash of the precached assets, so a rebuild that changes any asset
+ * produces a new cache and activate() purges the stale ones. Because VanillaJet
+ * fingerprints asset URLs (`?v=size-mtime`), matches use { ignoreSearch: true }
+ * so a cache entry keeps serving across version query changes within the cache.
+ */
+
+const CACHE_NAME = '__CACHE_NAME__';
+const CACHE_PREFIX = '__CACHE_PREFIX__';
+const PRECACHE_ASSETS = __PRECACHE_ASSETS__;
+const ON_DEMAND_PREFIXES = __ON_DEMAND_PREFIXES__;
+
+const MATCH_OPTIONS = { ignoreSearch: true };
+
+function isCacheable(pathname) {
+	return (
+		PRECACHE_ASSETS.includes(pathname) ||
+		ON_DEMAND_PREFIXES.some((prefix) => pathname.startsWith(prefix))
+	);
+}
+
+globalThis.addEventListener('install', (event) => {
+	event.waitUntil(
+		caches.open(CACHE_NAME).then((cache) =>
+			Promise.allSettled(PRECACHE_ASSETS.map((asset) => cache.add(asset))).then((results) => {
+				results.forEach((result, i) => {
+					if (result.status === 'rejected') {
+						console.error('SW precache failed: ' + PRECACHE_ASSETS[i], result.reason);
+					}
+				});
+			})
+		)
+	);
+	event.waitUntil(globalThis.skipWaiting());
+});
+
+globalThis.addEventListener('activate', (event) => {
+	event.waitUntil(
+		caches.keys().then((keys) =>
+			Promise.all(
+				keys
+					.filter((k) => k.startsWith(CACHE_PREFIX) && k !== CACHE_NAME)
+					.map((k) => caches.delete(k))
+			)
+		)
+	);
+	event.waitUntil(globalThis.clients.claim());
+});
+
+globalThis.addEventListener('fetch', (event) => {
+	const { request } = event;
+	if (request.method !== 'GET') return;
+
+	const url = new URL(request.url);
+	if (url.origin !== globalThis.location.origin || !isCacheable(url.pathname)) return;
+
+	// Cache-first: assets are immutable within a version (CACHE_NAME is content-pinned
+	// and activate() purges old caches on bump), so a cache hit never needs
+	// revalidation — skip the network entirely to save bandwidth on slow links.
+	event.respondWith(
+		caches.open(CACHE_NAME).then((cache) =>
+			cache.match(request, MATCH_OPTIONS).then((cached) => {
+				if (cached) return cached;
+
+				return fetch(request).then((response) => {
+					// waitUntil keeps the SW alive until the write finishes, so the asset
+					// is actually cached even if the SW is terminated right after.
+					if (response.ok) event.waitUntil(cache.put(request, response.clone()));
+					return response;
+				});
+			})
+		)
+	);
+});

package/gulpfile.js

@@ -24,6 +24,11 @@ function getCwd() {
 const base = getCwd();
 const cssOrigin = `${getCwd()}/assets/styles/less/admin.less`;
 
+// Build environment (passed via `gulp build --env <env>`). Forwarded to the
+// HTML/SW generators so they resolve the matching profile (api_url, etc).
+const argv = minimist(process.argv.slice(2));
+const buildEnv = argv.env || 'development';
+
 // Clean tasks
 function cleanBuildJS() {
   return del([`${getCwd()}/public/scripts/vanilla.min.js`], { force: true });
@@ -113,7 +118,13 @@ function compressCss() {
 // Template compilation
 function compileTemplates() {
   return gulp.src('.')
-    .pipe(shell([`node scripts/compile_html.js`]));
+    .pipe(shell([`node scripts/compile_html.js ${buildEnv}`]));
+}
+
+// Service worker generation (opt-in via settings.profile.enable_service_worker)
+function generateServiceWorker() {
+  return gulp.src('.')
+    .pipe(shell([`node scripts/generate_sw.js ${buildEnv}`]));
 }
 
 // Watch task
@@ -124,7 +135,8 @@ function watchFiles(cb) {
   watch([`${base}/assets/styles/less/**/*.less`], gulp.series(
     buildLess,
     compressCss,
-    compileTemplates
+    compileTemplates,
+    generateServiceWorker
   ));
 
   // Watch HTML files
@@ -140,7 +152,8 @@ function watchFiles(cb) {
     concatJs,
     cleanMinified,
     compressJs,
-    compileTemplates
+    compileTemplates,
+    generateServiceWorker
   ));
   
   cb();
@@ -154,7 +167,8 @@ const build = gulp.series(
   cleanMinified,
   buildLess,
   compileTemplates,
-  gulp.parallel(compressJs, compressCss)
+  gulp.parallel(compressJs, compressCss),
+  generateServiceWorker
 );
 
 const dev = gulp.series(
@@ -171,6 +185,7 @@ exports.concatJs = concatJs;
 exports.compressJs = compressJs;
 exports.compressCss = compressCss;
 exports.compileTemplates = compileTemplates;
+exports.generateServiceWorker = generateServiceWorker;
 exports.build = build;
 exports.dev = dev;
 exports.default = dev;