webspresso 0.0.66 → 0.0.67

package/README.md

@@ -17,6 +17,7 @@ A minimal, file-based SSR framework for Node.js with Nunjucks templating.
 - **Plugin System**: Extensible architecture with version control and inter-plugin communication
 - **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models, optional admin UI for ORM query cache metrics and purge
 - **Session authentication** (optional): `createAuth` / `quickAuth` in **`webspresso/core/auth`** — pass the manager to **`createApp({ auth })`** for `express-session`, `req.user` / `req.auth`, remember-me tokens, and policy-style authorization. Full walkthrough: **[`doc/index.html#authentication`](doc/index.html#authentication)**.
+- **Optional client runtime** (Alpine.js + [swup](https://swup.js.org/)): **`createApp({ clientRuntime: { alpine, swup } })`** serves scripts under **`/__webspresso/client-runtime/`** and exposes **`clientRuntime`** in Nunjucks; layouts can include **`views/partials/webspresso-client-runtime.njk`**. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`**. Demo: **`examples/alpine-swup-demo/`**. Details: **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
 - **TypeScript**: Published **`index.d.ts`** (via `package.json` `"types"`) for `createApp`, ORM, plugins, and router helpers — use from TS/JS with IDE autocomplete; runtime stays CommonJS
 
 ## Installation
@@ -357,8 +358,9 @@ Creates and configures the Express app.
   - `false`: Disable Helmet
   - `Object`: Custom Helmet configuration (merged with defaults)
 - `middlewares` (optional): Named middleware registry for routes
+- `clientRuntime` (optional): **`{ alpine?: boolean | object, swup?: boolean | object }`**. When either flag is enabled, mounts vendored Alpine 3 / swup 4 (+ Head + Scripts plugins) at **`/__webspresso/client-runtime/*`** and passes resolved **`{ alpine, swup }`** into SSR templates as **`clientRuntime`**. Override with env **`WEBSPRESSO_ALPINE`** / **`WEBSPRESSO_SWUP`** (`1` or `true`). Package exports **`resolveClientRuntime`** and **`CLIENT_RUNTIME_BASE`**. See **[Client runtime](#client-runtime)** below and **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
 - `auth` (optional): `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`require('webspresso/core/auth')`). Registers session + cookie parsing, attaches **`req.auth`** / **`req.user`**, and injects named route middleware **`auth`** and **`guest`** (do not reuse those names for custom handlers if you pass `auth`). See **[`doc/index.html#authentication`](doc/index.html#authentication)**.
-- `setupRoutes(app, ctx)` (optional): Register custom Express routes after file routes and plugin `onRoutesReady`, before the 404 handler — use for login/logout handlers when using the auth module; **`ctx.authMiddleware`** exposes `requireAuth`, `requireGuest`, etc.
+- `setupRoutes(app, ctx)` (optional): Register custom Express routes after file routes and plugin `onRoutesReady`, before the 404 handler — use for login/logout handlers when using the auth module; **`ctx.authMiddleware`** exposes `requireAuth`, `requireGuest`, etc.; **`ctx.clientRuntime`** is **`{ alpine, swup }`**
 
 **Example with middlewares:**
 
@@ -423,6 +425,27 @@ middlewares: {
 
 Plain `(req, res, next) => …` handlers still work as today. Tuple form **requires** a factory for that name (you get a clear error if you mix a plain handler with `['name', opts]`).
 
+### Client runtime
+
+Alpine.js + swup — opt-in progressive enhancement for SSR pages:
+
+- **`clientRuntime: { alpine: true, swup: true }`** (each can be toggled independently). Default is off; no scripts are injected when both are disabled.
+- Include **`{% include "partials/webspresso-client-runtime.njk" %}`** in your layout (copy from the npm package’s **`views/partials/`** or the framework repo). When **swup** is on, wrap the main content in **`<main id="swup">…</main>`** so transitions replace the correct region.
+- **swup** uses Head + Scripts plugins; **Alpine** is re-bound after each visit via **`Alpine.initTree`** on the container. Use **`data-no-swup`** on links for a full page load. Paths **`/_admin`** and **`/_webspresso`** are ignored by the default bootstrap; the admin panel and dev dashboard stay separate Mithril apps.
+- Dynamic UI can call **`pages/api/*`** from Alpine with **`fetch`** (see **`examples/alpine-swup-demo/`**).
+- **Helmet / CSP**: production **`script-src 'self'`** works for **`/__webspresso/client-runtime/`**; some Alpine builds may need **`unsafe-eval`** — validate for your version or use a stricter build.
+
+```javascript
+const { createApp } = require('webspresso');
+
+const { app } = createApp({
+  pagesDir: './pages',
+  viewsDir: './views',
+  publicDir: './public',
+  clientRuntime: { alpine: true, swup: true },
+});
+```
+
 ### App context (`req.db`, `getDb`, `attachDbMiddleware`)
 
 With **`createApp({ db })`**, file-based **API** routes (`pages/api/*.js`) get the same ORM instance on **`req.db`** before your **`middleware`** array and the handler run — no extra `require` in the handler:

package/index.d.ts

@@ -45,6 +45,11 @@ export interface CreateAppOptions {
   timeout?: string | false;
   auth?: unknown;
   db?: DatabaseInstance | null;
+  /** Opt-in Alpine / swup assets under `/__webspresso/client-runtime/*`. Env: WEBSPRESSO_ALPINE, WEBSPRESSO_SWUP. */
+  clientRuntime?: {
+    alpine?: boolean | Record<string, unknown>;
+    swup?: boolean | Record<string, unknown>;
+  };
   setupRoutes?: (app: Application, ctx: SetupRoutesContext) => void;
   [key: string]: unknown;
 }
@@ -54,6 +59,7 @@ export interface SetupRoutesContext {
   authMiddleware?: RequestHandler;
   pluginManager: PluginManager;
   options: CreateAppOptions;
+  clientRuntime: { alpine: boolean; swup: boolean };
 }
 
 export interface CreateAppResult {

package/index.js

@@ -3,6 +3,8 @@
  */
 
 const { createApp } = require('./src/server');
+const { resolveClientRuntime } = require('./src/client-runtime/resolve');
+const { CLIENT_RUNTIME_BASE } = require('./src/client-runtime/mount');
 const {
   attachDbMiddleware,
   getAppContext,
@@ -43,6 +45,8 @@ const { schemaExplorerPlugin, adminPanelPlugin, siteAnalyticsPlugin, auditLogPlu
 module.exports = {
   // Main API
   createApp,
+  resolveClientRuntime,
+  CLIENT_RUNTIME_BASE,
 
   attachDbMiddleware,
   getAppContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.66",
+  "version": "0.0.67",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",
@@ -42,9 +42,13 @@
     "utils/",
     "core/",
     "plugins/",
-    "templates/"
+    "templates/",
+    "views/partials/webspresso-client-runtime.njk"
   ],
   "dependencies": {
+    "@swup/head-plugin": "^2.3.1",
+    "@swup/scripts-plugin": "^2.1.0",
+    "alpinejs": "^3.15.11",
     "bcrypt": "^5.1.1",
     "commander": "^11.1.0",
     "connect-timeout": "^1.9.1",
@@ -57,6 +61,7 @@
     "knex": "^3.1.0",
     "nunjucks": "^3.2.4",
     "sharp": "^0.33.5",
+    "swup": "^4.8.3",
     "zod": "^3.23.0",
     "zod-to-json-schema": "^3.25.2"
   },
@@ -85,10 +90,10 @@
     }
   },
   "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/node": "^20.14.0",
     "@faker-js/faker": "^9.9.0",
     "@playwright/test": "^1.48.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^3.0.0",
     "better-sqlite3": "^11.10.0",
     "chokidar": "^3.5.3",

package/src/client-runtime/bootstrap-alpine-swup.js

@@ -0,0 +1,34 @@
+/* global Swup, SwupHeadPlugin, SwupScriptsPlugin, Alpine */
+(function () {
+  if (typeof Swup === 'undefined' || typeof SwupHeadPlugin === 'undefined' || typeof SwupScriptsPlugin === 'undefined' || typeof Alpine === 'undefined') {
+    return;
+  }
+
+  function ignoreVisit(url, ctx) {
+    var el = ctx && ctx.el;
+    if (el && el.closest && el.closest('[data-no-swup]')) return true;
+    try {
+      var u = new URL(url, window.location.origin);
+      var p = u.pathname;
+      if (p.indexOf('/_admin') === 0 || p.indexOf('/_webspresso') === 0) return true;
+    } catch (e) {
+      /* ignore */
+    }
+    return false;
+  }
+
+  var swup = new Swup({
+    containers: ['#swup'],
+    plugins: [new SwupHeadPlugin(), new SwupScriptsPlugin()],
+    ignoreVisit: ignoreVisit,
+  });
+
+  swup.hooks.on('content:replace', function () {
+    var root = document.querySelector('#swup');
+    if (root && typeof Alpine.initTree === 'function') {
+      Alpine.initTree(root);
+    }
+  });
+
+  window.__webspressoSwup = swup;
+})();

package/src/client-runtime/bootstrap-swup.js

@@ -0,0 +1,26 @@
+/* global Swup, SwupHeadPlugin, SwupScriptsPlugin */
+(function () {
+  if (typeof Swup === 'undefined' || typeof SwupHeadPlugin === 'undefined' || typeof SwupScriptsPlugin === 'undefined') {
+    return;
+  }
+
+  function ignoreVisit(url, ctx) {
+    var el = ctx && ctx.el;
+    if (el && el.closest && el.closest('[data-no-swup]')) return true;
+    try {
+      var u = new URL(url, window.location.origin);
+      var p = u.pathname;
+      if (p.indexOf('/_admin') === 0 || p.indexOf('/_webspresso') === 0) return true;
+    } catch (e) {
+      /* ignore */
+    }
+    return false;
+  }
+
+  var swup = new Swup({
+    containers: ['#swup'],
+    plugins: [new SwupHeadPlugin(), new SwupScriptsPlugin()],
+    ignoreVisit: ignoreVisit,
+  });
+  window.__webspressoSwup = swup;
+})();

package/src/client-runtime/mount.js

@@ -0,0 +1,65 @@
+/**
+ * Mount Express routes that serve vendored Alpine / Swup UMD builds from node_modules
+ * and framework bootstrap scripts from src/client-runtime/.
+ */
+
+const path = require('path');
+const express = require('express');
+
+const CLIENT_RUNTIME_BASE = '/__webspresso/client-runtime';
+
+/** Resolve a file next to the package's resolved main entry (works with package "exports"). */
+function pkgFileFromMain(pkg, ...segments) {
+  const entry = require.resolve(pkg);
+  return path.join(path.dirname(entry), ...segments);
+}
+
+/**
+ * @param {import('express').Express} app
+ * @param {{ alpine: boolean, swup: boolean }} flags
+ */
+function mountClientRuntime(app, flags) {
+  if (!flags || (!flags.alpine && !flags.swup)) return;
+
+  const router = express.Router();
+
+  function send(res, filePath) {
+    res.type('application/javascript');
+    res.sendFile(filePath);
+  }
+
+  if (flags.alpine) {
+    router.get('/alpine.min.js', (req, res) => {
+      send(res, pkgFileFromMain('alpinejs', 'cdn.min.js'));
+    });
+  }
+
+  if (flags.swup) {
+    router.get('/swup.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('swup', 'Swup.umd.js'));
+    });
+    router.get('/swup-head-plugin.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('@swup/head-plugin', 'index.umd.js'));
+    });
+    router.get('/swup-scripts-plugin.umd.js', (req, res) => {
+      send(res, pkgFileFromMain('@swup/scripts-plugin', 'index.umd.js'));
+    });
+    const runtimeDir = __dirname;
+    if (flags.alpine) {
+      router.get('/bootstrap-alpine-swup.js', (req, res) => {
+        send(res, path.join(runtimeDir, 'bootstrap-alpine-swup.js'));
+      });
+    } else {
+      router.get('/bootstrap-swup.js', (req, res) => {
+        send(res, path.join(runtimeDir, 'bootstrap-swup.js'));
+      });
+    }
+  }
+
+  app.use(CLIENT_RUNTIME_BASE, router);
+}
+
+module.exports = {
+  mountClientRuntime,
+  CLIENT_RUNTIME_BASE,
+};

package/src/client-runtime/resolve.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve clientRuntime flags from createApp({ clientRuntime }) and optional env overrides.
+ * Env: WEBSPRESSO_ALPINE=1|true, WEBSPRESSO_SWUP=1|true (override explicit false from options when set).
+ */
+
+function envTruthy(name) {
+  const v = process.env[name];
+  if (v == null || v === '') return undefined;
+  return v === '1' || /^true$/i.test(String(v));
+}
+
+function optionEnabled(v) {
+  if (v === true) return true;
+  if (v && typeof v === 'object') return true;
+  return false;
+}
+
+/**
+ * @param {object} [options]
+ * @param {object} [options.clientRuntime]
+ * @param {boolean|object} [options.clientRuntime.alpine]
+ * @param {boolean|object} [options.clientRuntime.swup]
+ * @returns {{ alpine: boolean, swup: boolean }}
+ */
+function resolveClientRuntime(options = {}) {
+  const cr = options.clientRuntime;
+  let alpine = false;
+  let swup = false;
+  if (cr && typeof cr === 'object') {
+    alpine = optionEnabled(cr.alpine);
+    swup = optionEnabled(cr.swup);
+  }
+  const envA = envTruthy('WEBSPRESSO_ALPINE');
+  const envS = envTruthy('WEBSPRESSO_SWUP');
+  if (envA !== undefined) alpine = envA;
+  if (envS !== undefined) swup = envS;
+  return { alpine, swup };
+}
+
+module.exports = { resolveClientRuntime };

package/src/file-router.js

@@ -365,10 +365,22 @@ function resolveMiddlewares(middlewareConfig, middlewareRegistry = {}) {
  * @param {Object} options.pluginManager - Plugin manager instance
  * @param {boolean} options.silent - Suppress console output
  * @param {Object} options.db - Database instance (exposed as ctx.db in load/meta)
+ * @param {{ alpine?: boolean, swup?: boolean }} [options.clientRuntime] - Passed to Nunjucks as `clientRuntime` (default both false)
  * @returns {Array} Route metadata for plugins
  */
 function mountPages(app, options) {
-  const { pagesDir, nunjucks, middlewares = {}, pluginManager = null, silent = false, db = null } = options;
+  const {
+    pagesDir,
+    nunjucks,
+    middlewares = {},
+    pluginManager = null,
+    silent = false,
+    db = null,
+    clientRuntime: clientRuntimeOpt = null,
+  } = options;
+  const clientRuntime = clientRuntimeOpt && typeof clientRuntimeOpt === 'object'
+    ? { alpine: !!clientRuntimeOpt.alpine, swup: !!clientRuntimeOpt.swup }
+    : { alpine: false, swup: false };
   const isDev = process.env.NODE_ENV !== 'production';
   const log = silent ? () => {} : console.log.bind(console);
   
@@ -548,7 +560,8 @@ function mountPages(app, options) {
             indexable: true,
             canonical: null
           },
-          fsy: { ...baseHelpers, ...pluginHelpers }
+          fsy: { ...baseHelpers, ...pluginHelpers },
+          clientRuntime,
         };
         
         // Execute hooks: onRequest
@@ -612,6 +625,7 @@ function mountPages(app, options) {
           locale: ctx.locale,
           t: ctx.t,
           fsy: ctx.fsy,
+          clientRuntime: ctx.clientRuntime,
           req: {
             path: req.path,
             query: req.query,

package/src/server.js

@@ -9,6 +9,8 @@ const nunjucks = require('nunjucks');
 const timeout = require('connect-timeout');
 
 const { setAppContext } = require('./app-context');
+const { mountClientRuntime } = require('./client-runtime/mount');
+const { resolveClientRuntime } = require('./client-runtime/resolve');
 const { mountPages } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector } = require('./helpers');
 const { createPluginManager } = require('./plugin-manager');
@@ -258,6 +260,7 @@ function haltOnTimedout(req, res, next) {
  * @param {string|boolean} options.timeout - Request timeout (default: '30s', false to disable)
  * @param {Object} options.auth - Authentication manager instance (from createAuth)
  * @param {Object} options.db - Database instance (exposed as ctx.db to plugins)
+ * @param {Object} [options.clientRuntime] - Optional client assets: `{ alpine?: boolean|object, swup?: boolean|object }`. Overridable by env `WEBSPRESSO_ALPINE` / `WEBSPRESSO_SWUP` (=1 or true). Serves `/__webspresso/client-runtime/*` when either flag is on.
  * @param {function(import('express').Express, Object): void} [options.setupRoutes] - Called after file routes and plugins, before 404 handler
  * @returns {Object} { app, nunjucksEnv, pluginManager, authMiddleware }
  */
@@ -294,6 +297,8 @@ function createApp(options = {}) {
     throw new Error('pagesDir is required');
   }
 
+  const clientRuntime = resolveClientRuntime(options);
+
   setAppContext({ db: options.db ?? null });
   
   const app = express();
@@ -378,7 +383,9 @@ function createApp(options = {}) {
       etag: true
     }));
   }
-  
+
+  mountClientRuntime(app, clientRuntime);
+
   // Configure Nunjucks
   const templateDirs = viewsDir ? [pagesDir, viewsDir] : [pagesDir];
   
@@ -439,7 +446,8 @@ function createApp(options = {}) {
     middlewares,
     pluginManager,
     silent: isTest,
-    db: options.db ?? null
+    db: options.db ?? null,
+    clientRuntime,
   });
   
   // Set route metadata in plugin manager
@@ -480,6 +488,7 @@ function createApp(options = {}) {
       authMiddleware,
       pluginManager,
       options,
+      clientRuntime,
     });
   }
   

package/templates/skills/webspresso-usage/SKILL.md

@@ -66,8 +66,9 @@ project/
 | `timeout` | e.g. `'30s'` or `false` |
 | `helmet` | `true` / `false` / object |
 | `assets` | `{ version, manifestPath, prefix }` for `fsy.asset` / `fsy.css` / `fsy.js` |
+| `clientRuntime` | Opt-in `{ alpine?, swup? }` — serves `/__webspresso/client-runtime/*`, template `clientRuntime`, partial `views/partials/webspresso-client-runtime.njk`, `<main id="swup">` when swup on. Env: `WEBSPRESSO_ALPINE`, `WEBSPRESSO_SWUP`. |
 | `auth` | Auth manager from `createAuth` (session routes) |
-| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
+| `setupRoutes(app, ctx)` | **Register custom Express routes here** — runs **after** file routes and plugins’ `onRoutesReady`, **before** 404. `ctx.clientRuntime` included. Do not rely on `app.get` *after* `createApp` returns unless routes are appended before the 404 middleware (see [`src/server.js`](../../../src/server.js)). |
 
 **Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware? }` (and related).
 

package/views/partials/webspresso-client-runtime.njk

@@ -0,0 +1,15 @@
+{# Served by createApp when clientRuntime.alpine / .swup are enabled. See src/client-runtime/. #}
+{% if clientRuntime and clientRuntime.alpine %}
+<style>[x-cloak] { display: none !important; }</style>
+<script defer src="/__webspresso/client-runtime/alpine.min.js"></script>
+{% endif %}
+{% if clientRuntime and clientRuntime.swup %}
+<script defer src="/__webspresso/client-runtime/swup.umd.js"></script>
+<script defer src="/__webspresso/client-runtime/swup-head-plugin.umd.js"></script>
+<script defer src="/__webspresso/client-runtime/swup-scripts-plugin.umd.js"></script>
+{% if clientRuntime.alpine %}
+<script defer src="/__webspresso/client-runtime/bootstrap-alpine-swup.js"></script>
+{% else %}
+<script defer src="/__webspresso/client-runtime/bootstrap-swup.js"></script>
+{% endif %}
+{% endif %}