nibula 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to Nibula are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-07-21
+
+### Added
+- **Node.js backend** as an alternative to PHP, living side by side in
+  `src/backend/`: `_core/index.js` front controller (which is also the HTTP
+  server), `Response` and `RateLimiter` modules, a `mysql2` pool singleton
+  `Database.js`, `example.config.js`, and a `package.json` for the backend's
+  own dependencies. Same REST API as PHP: routing, `X-Api-Key` auth, CORS and
+  file-based rate limiting are identical.
+- **Backend choice at scaffold time**: `nib new` now asks whether to use Node.js
+  or PHP, in addition to language and CSS framework.
+- `backend/backend-node.service.example` — a ready-to-adapt **systemd** unit for
+  keeping the Node backend running on a server.
+- `config.js` is generated from `example.config.js` at scaffold time (mirroring
+  the existing `config.php` generation).
+- Deployment docs now cover running the Node backend with **`screen`** (quick /
+  small setups) and **systemd** (production), plus environment variables.
+
+### Changed
+- **Composer is now required only when the PHP backend is chosen.** If you pick
+  Node, `composer install` is skipped entirely and the backend's npm
+  dependencies (`mysql2`) are installed instead.
+- `.htaccess`, `web.config` and `nginx.conf` now cover **both** backends. On
+  nginx, `/api` goes to Node and automatically falls back to the PHP front
+  controller when Node is unreachable. On Apache/IIS the active backend is
+  selected by configuration (documented), since per-directory configs can't
+  health-check an upstream.
+- `.gitignore` now also ignores `src/backend/config.js`,
+  `src/backend/node_modules/` and `src/backend/cache/`.
+- Documentation (`README.md`, `docs/Backend.md`, `docs/Deploy.md`) updated:
+  backend examples now use JavaScript/Node as the reference, with the equivalent
+  PHP shown alongside and a note that PHP behaves identically.
+
+### Notes
+- Both backends are always scaffolded, so you can switch later without
+  re-creating the project. The PHP front controller only serves `.php` endpoint
+  files and the Node one only `.js`, so they coexist without conflict.
+
+## [1.0.2]
+
+- Previous release (PHP backend only).
+
+[1.1.0]: https://github.com/Rhaastrake/Nibula/releases/tag/v1.1.0
+[1.0.2]: https://github.com/Rhaastrake/Nibula/releases/tag/v1.0.2

package/README.md

@@ -21,7 +21,7 @@ Building a website from scratch involves a lot of moving parts: templating, buil
 - 🪶 **Lightweight by default** — SCSS frameworks can be filtered so you ship only what you actually use
 - 🌍 **Open source** — free to use, free to modify, free to share
 
-![Version](https://img.shields.io/badge/version-1.1.0-blue)
+![Version](https://img.shields.io/badge/version-1.1.2-blue)
 ![License](https://img.shields.io/badge/license-Apache--2.0-blue)
 ![Eleventy](https://img.shields.io/badge/11ty-v3.1.2-black)
 

package/bin/create.js

@@ -36,7 +36,7 @@ const BACKEND = Object.freeze({
 // ── CHOICES ──────────────────────────────────────────────────────────────────
 
 const LANGUAGE_CHOICES = [
-    { label: 'JavaScript (recomened)', value: LANGUAGE.JAVASCRIPT },
+    { label: 'JavaScript (recomended)', value: LANGUAGE.JAVASCRIPT },
     { label: 'TypeScript',           value: LANGUAGE.TYPESCRIPT },
 ];
 
@@ -53,6 +53,12 @@ const BACKEND_CHOICES = [
     { label: 'PHP (index.php — Composer dependencies)',  value: BACKEND.PHP  },
 ];
 
+// Runtime dependency added to the ROOT package.json when the Node backend is
+// chosen, so it lands in the root node_modules (never in src/backend).
+const NODE_BACKEND_DEPENDENCIES = {
+    mysql2: '^3.11.0',
+};
+
 // ── COPY CONFIG ───────────────────────────────────────────────────────────────
 
 const MANDATORY_COPY = [
@@ -72,6 +78,14 @@ const CREATE_DIRS = [
     'src/frontend/_routes',
 ];
 
+// Backend files that belong to exactly one backend, matched by basename.
+// Everything else (migrations, .htaccess, web.config, README, ...) is shared.
+const NODE_ONLY_FILES = new Set(['package.json', 'backend-node.service.example']);
+const PHP_ONLY_FILES  = new Set(['composer.json', 'composer.lock']);
+const PHP_ONLY_DIRS   = new Set(['vendor']);
+// Runtime artifacts that must never be copied from the template, either way.
+const BACKEND_SKIP_DIRS = new Set(['node_modules', 'cache', '.git']);
+
 // ── FRAMEWORK CONFIG ──────────────────────────────────────────────────────────
 
 const ALL_FRAMEWORKS = Object.values(FRAMEWORK).filter(f => f !== FRAMEWORK.NONE);
@@ -128,7 +142,6 @@ src/backend/_core/vendor/
 out/
 src/backend/config.php
 src/backend/config.js
-src/backend/node_modules/
 src/backend/cache/
 `;
 
@@ -198,6 +211,48 @@ function copyRecursive(src, dest, exclude = []) {
     }
 }
 
+/**
+ * Decide whether a backend entry belongs to the chosen backend.
+ * Returns false for entries that must be SKIPPED.
+ */
+function backendEntryKept(basename, isDir, backend) {
+    // Never copy runtime artifacts from the template.
+    if (isDir && BACKEND_SKIP_DIRS.has(basename)) return false;
+
+    if (backend === BACKEND.NODE) {
+        // Node project: drop every PHP artifact.
+        if (basename.endsWith('.php')) return false;
+        if (PHP_ONLY_FILES.has(basename)) return false;
+        if (isDir && PHP_ONLY_DIRS.has(basename)) return false;
+        return true;
+    }
+
+    // PHP project: drop every Node artifact.
+    if (basename.endsWith('.js')) return false;
+    if (NODE_ONLY_FILES.has(basename)) return false;
+    return true;
+}
+
+/**
+ * Copy src/backend into the project keeping only the chosen backend's files.
+ * Shared files (SQL migrations, .htaccess, web.config, README, ...) are kept
+ * for both. Empty directories left behind by filtering are not created.
+ */
+function copyBackend(src, dest, backend) {
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+        for (const child of fs.readdirSync(src)) {
+            const childSrc = path.join(src, child);
+            const isDir    = fs.statSync(childSrc).isDirectory();
+            if (!backendEntryKept(child, isDir, backend)) continue;
+            copyBackend(childSrc, path.join(dest, child), backend);
+        }
+    } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+    }
+}
+
 function slashComment(content, line) {
     content = content.replace(new RegExp(`^([ \\t]*)// (${escapeRegex(line)})$`, 'gm'), '$1$2');
     return content.replace(new RegExp(`^([ \\t]*)(${escapeRegex(line)})$`, 'gm'), '$1// $2');
@@ -217,8 +272,7 @@ function njkUncomment(content, line) {
 }
 
 function installDependencies(backend) {
-    const backendRoot = path.join(targetDir, 'src', 'backend');
-    const backendCore = path.join(backendRoot, '_core');
+    const backendCore = path.join(targetDir, 'src', 'backend', '_core');
 
     log(`${color.blue}\n>> Installing Node modules...${color.reset}`);
     const npm = spawnSync('npm', ['install'], {
@@ -234,17 +288,11 @@ function installDependencies(backend) {
         return false;
     }
 
-    // --- Node backend: install its own deps (mysql2), then SKIP Composer ---
+    // Node backend: its runtime deps were added to the ROOT package.json and
+    // installed above into the root node_modules — there is no separate install
+    // inside src/backend, and Composer is never run.
     if (backend === BACKEND.NODE) {
-        if (fs.existsSync(path.join(backendRoot, 'package.json'))) {
-            log(`\n${color.blue}>> Installing Node backend modules...${color.reset}`);
-            spawnSync('npm', ['install'], {
-                cwd: backendRoot,
-                stdio: 'inherit',
-                shell: process.platform === 'win32',
-            });
-        }
-        return true; // Composer is never run for the Node backend
+        return true;
     }
 
     // --- PHP backend: install Composer dependencies (if present) ---
@@ -389,11 +437,19 @@ async function init() {
         const src  = path.join(templateDir, target);
         const dest = path.join(targetDir, target);
         if (!fs.existsSync(src)) continue;
-        const exclude = target === 'src/frontend' ? FRONTEND_EXCLUDE[language] : [];
-        copyRecursive(src, dest, exclude);
+
+        if (target === 'src/backend') {
+            // Copy only the chosen backend's files (the other backend is omitted).
+            copyBackend(src, dest, backend);
+        } else {
+            const exclude = target === 'src/frontend' ? FRONTEND_EXCLUDE[language] : [];
+            copyRecursive(src, dest, exclude);
+        }
         logAdd(target);
     }
 
+    // Generate the local config only for the chosen backend. The other backend's
+    // example file was not copied, so its guard below is simply skipped.
     const configDest    = path.join(targetDir, 'src/backend/config.php');
     const configExample = path.join(targetDir, 'src/backend/example.config.php');
     if (!fs.existsSync(configDest) && fs.existsSync(configExample)) {
@@ -408,7 +464,17 @@ async function init() {
         logAdd('src/backend/config.js');
     }
 
+    // Build the project package.json. Clone the shared dependency maps so we
+    // never mutate the PROJECT_PACKAGE constant.
     const pkg = { ...PROJECT_PACKAGE };
+    pkg.dependencies    = { ...PROJECT_PACKAGE.dependencies };
+    pkg.devDependencies = { ...PROJECT_PACKAGE.devDependencies };
+
+    // Node backend deps live in the ROOT node_modules — add them to root deps
+    // so `npm install` installs them there (never in src/backend).
+    if (backend === BACKEND.NODE) {
+        pkg.dependencies = { ...pkg.dependencies, ...NODE_BACKEND_DEPENDENCIES };
+    }
 
     if (language === LANGUAGE.TYPESCRIPT) {
         const tsSrc  = path.join(templateDir, 'tsconfig.json');

package/docs/Backend.md

@@ -27,43 +27,51 @@ When you run `nib new`, the scaffolder asks three questions: language, CSS
 framework, and **backend**. Pick Node.js or PHP.
 
 - **If you pick Node**, Composer is never run — you get an npm-only setup, and
-  the backend's own dependency (`mysql2`, used only if you touch the database)
-  is installed for you.
-- **If you pick PHP**, Composer dependencies are installed as before.
+  the backend's dependency (`mysql2`, used only if you touch the database) is
+  added to the **root** `package.json` and installed into the root `node_modules`.
+- **If you pick PHP**, Composer dependencies are installed as before, and no Node
+  backend files are added.
 
-Both file sets are always present in `src/backend/`, so you can switch later
-without re-scaffolding. The PHP front controller only looks at `.php` endpoint
-files and the Node one only at `.js` files, so they coexist without conflict.
+**Only the backend you choose is copied into the project.** A Node project
+contains no PHP files; a PHP project contains no `.js` backend files. Shared,
+backend-agnostic files (SQL migrations, `.htaccess`, `web.config`) are always
+included.
 
 ## Structure
 
+The structure below shows both backends for reference; **your project will have
+only one side of each pair** (plus the shared files).
+
 ```
 src/backend/
 ├── api/
 │   ├── public/       # Endpoints accessible without an API key
 │   └── protected/    # Endpoints requiring the X-Api-Key header
 ├── _core/            # Framework internals (routing, modules) — do not edit
-│   ├── index.php     # PHP front controller
-│   ├── index.js      # Node front controller (also the HTTP server)
+│   ├── index.php     # PHP front controller            (PHP project)
+│   ├── index.js      # Node front controller + server   (Node project)
 │   ├── init.php / init.js
-│   └── modules/      # Response, RateLimiter (.php and .js)
+│   └── modules/      # Response, RateLimiter
 ├── database/
-│   ├── Database.php  # PDO singleton
-│   ├── Database.js   # mysql2 pool singleton
-│   └── migrations/
-├── package.json          # Node backend deps + start script
-├── example.config.php    # PHP template — versioned, safe to commit
-├── example.config.js     # Node template — versioned, safe to commit
-├── config.php            # Local PHP config — generated on setup, never commit
-└── config.js             # Local Node config — generated on setup, never commit
+│   ├── Database.php  # PDO singleton                    (PHP project)
+│   ├── Database.js   # mysql2 pool singleton            (Node project)
+│   └── migrations/   # shared
+├── package.json          # Node project only — backend deps + start script
+├── example.config.php    # PHP project only  — versioned template
+├── example.config.js     # Node project only — versioned template
+├── config.php            # PHP project only  — generated on setup, never commit
+└── config.js             # Node project only — generated on setup, never commit
 ```
 
-> A scaffolded project contains **both** the example and the generated config for
-> each backend. `config.php` / `config.js` are generated automatically by
-> `nib new` (copies of the examples) and are git-ignored, so your secrets stay
-> local. The `example.config.*` files are versioned: they end up on GitHub as
-> secret-free references. If a `config.*` is ever missing (e.g. after a fresh
-> clone), just copy the matching `example.config.*` to it.
+> `config.php` / `config.js` are generated automatically by `nib new` (a copy of
+> the matching `example.config.*`) and are git-ignored, so your secrets stay
+> local. The `example.config.*` file is versioned as a secret-free reference. If
+> `config.*` is ever missing (e.g. after a fresh clone), copy the example to it.
+
+> **Where do the Node backend's dependencies live?** In the **root**
+> `node_modules`, not in `src/backend` — so your source tree stays clean (no
+> `src/backend/node_modules` locally). On the server you install them into
+> `out/backend` instead; see `docs/Deploy.md`.
 
 ## Key difference: how each backend runs
 

package/nginx.conf

@@ -1,75 +1,75 @@
-# Example nginx directives for a Nibula site — covers BOTH backends.
-#
-# /api is served by Node (index.js) if it is running on 127.0.0.1:3000; if Node
-# is unreachable, nginx falls back to the PHP front controller automatically.
-# So the same config works whether you deployed the Node backend or the PHP one:
-#   - Node backend running  -> Node answers /api
-#   - only PHP deployed      -> Node is down -> falls back to PHP-FPM
-#
-# This is NOT a ready-to-use file: paste these directives inside your own
-# server { } block (the one with server_name, listen and SSL) and set `root`
-# to your `out` folder.
-
-# Hide the nginx version from response headers
-server_tokens off;
-
-# Force HTTPS on future requests (applies site-wide, including /api)
-add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
-
-root /var/www/your-site/out;
-index index.html;
-
-# Disable directory listing
-autoindex off;
-
-error_page 403 404 /404.html;
-location = /404.html {
-    internal;
-}
-
-# Never expose the backend source directory over HTTP.
-location ^~ /backend/ {
-    return 404;
-}
-
-# Block server config files anywhere in the tree (.htaccess, web.config).
-location ~* (^|/)(\.htaccess|web\.config)$ {
-    return 404;
-}
-
-# --- /api: Node primary, PHP fallback ---------------------------------------
-# Try the Node backend first. If it is down (502/504), retry through the PHP
-# front controller. Security headers for API responses are set by the backend.
-location ^~ /api/ {
-    proxy_pass http://127.0.0.1:3000;
-    proxy_http_version 1.1;
-    proxy_set_header Host              $host;
-    proxy_set_header X-Real-IP         $remote_addr;
-    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-
-    proxy_intercept_errors on;
-    error_page 502 504 = @php_backend;
-}
-
-location @php_backend {
-    include fastcgi_params;
-    fastcgi_param SCRIPT_FILENAME $document_root/backend/_core/index.php;
-
-    # Adjust the PHP-FPM socket to your distro:
-    #   Debian / Ubuntu : unix:/run/php/php8.3-fpm.sock
-    #   RHEL / Fedora   : unix:/run/php-fpm/php-fpm.sock
-    #   TCP fallback    : 127.0.0.1:9000
-    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
-}
-
-# Serve static files, fall back to the 404 page.
-# A location with add_header does not inherit server-level headers,
-# so Strict-Transport-Security is repeated here.
-location / {
-    add_header X-Content-Type-Options "nosniff" always;
-    add_header X-Frame-Options "SAMEORIGIN" always;
-    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
-    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
-    try_files $uri $uri/ /404.html;
-}
+# Example nginx directives for a Nibula site — covers BOTH backends.
+#
+# /api is served by Node (index.js) if it is running on 127.0.0.1:3000; if Node
+# is unreachable, nginx falls back to the PHP front controller automatically.
+# So the same config works whether you deployed the Node backend or the PHP one:
+#   - Node backend running  -> Node answers /api
+#   - only PHP deployed      -> Node is down -> falls back to PHP-FPM
+#
+# This is NOT a ready-to-use file: paste these directives inside your own
+# server { } block (the one with server_name, listen and SSL) and set `root`
+# to your `out` folder.
+
+# Hide the nginx version from response headers
+server_tokens off;
+
+# Force HTTPS on future requests (applies site-wide, including /api)
+add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+root /var/www/your-site/out;
+index index.html;
+
+# Disable directory listing
+autoindex off;
+
+error_page 403 404 /404.html;
+location = /404.html {
+    internal;
+}
+
+# Never expose the backend source directory over HTTP.
+location ^~ /backend/ {
+    return 404;
+}
+
+# Block server config files anywhere in the tree (.htaccess, web.config).
+location ~* (^|/)(\.htaccess|web\.config)$ {
+    return 404;
+}
+
+# --- /api: Node primary, PHP fallback ---------------------------------------
+# Try the Node backend first. If it is down (502/504), retry through the PHP
+# front controller. Security headers for API responses are set by the backend.
+location ^~ /api/ {
+    proxy_pass http://127.0.0.1:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Host              $host;
+    proxy_set_header X-Real-IP         $remote_addr;
+    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    proxy_intercept_errors on;
+    error_page 502 504 = @php_backend;
+}
+
+location @php_backend {
+    include fastcgi_params;
+    fastcgi_param SCRIPT_FILENAME $document_root/backend/_core/index.php;
+
+    # Adjust the PHP-FPM socket to your distro:
+    #   Debian / Ubuntu : unix:/run/php/php8.3-fpm.sock
+    #   RHEL / Fedora   : unix:/run/php-fpm/php-fpm.sock
+    #   TCP fallback    : 127.0.0.1:9000
+    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
+}
+
+# Serve static files, fall back to the 404 page.
+# A location with add_header does not inherit server-level headers,
+# so Strict-Transport-Security is repeated here.
+location / {
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    try_files $uri $uri/ /404.html;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A beginner-friendly static site generator built on Eleventy that stays close to vanilla HTML, CSS and JS — with a page-management CLI, an optional PHP backend, and SEO files generated for you.",
   "keywords": [
     "static-site-generator",