nibula 1.5.0 → 1.5.2

package/.eleventyignore

@@ -1,4 +1 @@
-src/frontend/assets/**
-src/frontend/js/**
-src/frontend/scss/**
-src/backend/**
+src/frontend/assets/**

package/CHANGELOG.md

@@ -5,6 +5,57 @@ 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.5.2] - 2026-08-05
+
+### Fixed
+- `nib new` no longer creates an empty `src/frontend/routes` folder. 1.5.1
+  removed it from `CREATE_DIRS` but left it in `MANDATORY_COPY`, so it still
+  arrived from the template. It is now created on demand when the first page is
+  added, and removed again when the last one is deleted.
+
+## [1.5.1] - 2026-08-05
+
+### Fixed
+- `nib new` no longer creates an empty `routes` folder. Page source folders are
+  created on demand when a page is added, and removed again when the last page
+  in them is deleted — `routes`, `scss/pages` and the JS/TS pages folder alike.
+- Removing a page that doesn't exist reported the skip and then went on to strip
+  its entry from `site.json` and `page-components.njk` anyway. It now stops.
+- `example.config.php` was missing the `APP_ENV` key, so PHP projects had no way
+  to discover the debug switch from the template. Behaviour was unaffected —
+  the code already fell back to `production` — but the key is now visible and
+  documented, and the two templates are identical again.
+- The backend's `dev` script set `APP_ENV` as an environment variable, which
+  neither backend reads. It ran in production mode and produced no debug output.
+  The script is gone; error verbosity is set in `config.js` / `config.php`.
+- `bin/create.js` repeated the `mysql2` version already declared in
+  `src/backend/package.json`. It now reads that file, so the two cannot drift.
+- `docs/Deploy.md` pointed at `backend/backend-node.service.example`, removed in
+  1.5.0. The systemd unit is written out in full instead.
+- `docs/Deploy.md` gave the backend path as `/var/www/backend/SITE_FOLDER`,
+  inverted with respect to the rest of the document.
+
+### Changed
+- Nginx setup steps moved from the `nginx.conf` header into `docs/Deploy.md`,
+  under "Your own server". The header keeps only the three placeholders that
+  appear in the file and a pointer to the docs, so a config copied into
+  `/etc/nginx/sites-available/` no longer carries 60 lines of install
+  instructions that were already followed.
+- `docs/Deploy.md` troubleshooting is now a table, with a row for a 502 on
+  `/api` caused by the Node process not running.
+- `.eleventyignore` reduced to `src/frontend/assets/**`. The `scss`, `js` and
+  `src/backend` entries excluded nothing: the first two are not Eleventy
+  template formats and the third is outside the input directory. The last one
+  was also misleading, since `.eleventy.js` deliberately copies `src/backend`
+  into the build.
+- `docs/Backend.md` documents `APP_ENV` in its own section, including the
+  `display_errors` behaviour specific to PHP, and states explicitly that it is
+  a config key rather than an environment variable.
+
+### Notes
+- Existing projects are unaffected: the scaffolding and template changes apply
+  only to newly created ones.
+
 ## [1.5.0] - 2026-08-04
 
 ### Added

package/README.md

@@ -76,19 +76,6 @@ cd your-project
 nib run
 ```
 
-## 💻 Commands
-
-Run these from anywhere inside a project — except `nib new`, which must be run **outside** a project, in the folder where you want the new one created.
-
-| Command | Description |
-|---|---|
-| `nib new <name>` | Create your new project |
-| `nib run` | Start the dev server and build the output folder at runtime |
-| `nib cli` | Open the page-management assistant |
-| `nib build` | Build the output folder |
-| `nib clean` | Remove the output directory |
-| `nib update` | Update Nibula to the latest version (applies from your next project on) |
-
 ## 📄 Managing pages
 
 Instead of creating and wiring up multiple files by hand, let the interactive assistant do it for you. To create, remove, or rename pages and configure the output path, run:
@@ -99,17 +86,18 @@ nib cli
 
 See [docs/Assistant CLI.md](docs/Assistant%20CLI.md) for details.
 
-## 🌍 Deploying
-
-Nibula builds a static site into your `out` folder, which you upload to a web
-server. Which backend you chose affects deployment:
+## 💻 Commands
 
-- **Node** runs as a long-running service on a VPS; the web server reverse-proxies `/api` to it.
-- **PHP** runs on ordinary shared hosting (Apache/IIS) or a VPS with PHP-FPM — no process to keep alive.
+Run these from anywhere inside a project — except `nib new`, which must be run **outside** a project, in the folder where you want the new one created.
 
-The shipped `.htaccess`, `web.config` and `nginx.conf` cover **both** backends.
-See [docs/Deploy.md](docs/Deploy.md) for the full guide, including how to start
-the Node service on your server.
+| Command | Description |
+|---|---|
+| `nib new <name>` | Create your new project |
+| `nib run` | Start the dev server and build the output folder at runtime |
+| `nib cli` | Open the page-management assistant |
+| `nib build` | Build the output folder |
+| `nib clean` | Remove the output directory |
+| `nib update` | Update Nibula to the latest version (applies from your next project on) |
 
 ## 🙌 Wrapping up
 
@@ -117,4 +105,4 @@ Thanks for giving Nibula a try.
 
 It's a one-person project, so every bit of feedback counts more than you'd think: if something breaks, if the documentation isn't clear, or if a feature is missing, open an [issue](https://github.com/Rhaastrake/Nibula/issues) — even just to tell me what you built with it.
 
-If Nibula was useful to you, leaving a ⭐ on the repository is the easiest way to help other people find it.
+If Nibula was useful to you, leaving a ⭐ on the repository is the easiest way to help other people find it.

package/bin/create.js

@@ -53,11 +53,11 @@ const BACKEND_CHOICES = [
     { label: 'PHP (Can run everywhere)',  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',
-};
+// Runtime dependencies for the Node backend, read from the backend's own
+// package.json so the two never drift. They are added to the ROOT package.json
+// when Node is chosen, so they land in the root node_modules (never in
+// src/backend).
+const NODE_BACKEND_DEPENDENCIES = require(path.join(templateDir, 'src/backend/package.json')).dependencies;
 
 // ── COPY CONFIG ───────────────────────────────────────────────────────────────
 
@@ -74,9 +74,7 @@ const FRONTEND_EXCLUDE = {
     [LANGUAGE.TYPESCRIPT]: ['js'],
 };
 
-const CREATE_DIRS = [
-    'src/frontend/routes',
-];
+const CREATE_DIRS = [];
 
 // Backend files that belong to exactly one backend, matched by basename.
 // Everything else (migrations, .htaccess, web.config, README, ...) is shared.

package/docs/Backend.md

@@ -107,19 +107,32 @@ both, PHP-array vs JS-object syntax.
 
 ```js
 module.exports = {
+    // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
     GENERAL_API_KEY: 'DEFAULT_KEY',
+
+    // If you want to restrict access to protected endpoints to specific clients, define custom keys per endpoint.
+    // For subfolder endpoints, use the relative path ('subfolder/endpoint')
     CUSTOM_ENDPOINT_KEYS: {
-        'subfolder/endpoint': 'custom-key',
+        'subfolder/example-protected': 'custom-key',
     },
-    GENERAL_ALLOWED_ORIGINS: ['*' /*, 'https://example.com' */],
+
+    GENERAL_ALLOWED_ORIGINS: [
+        '*',
+        // 'https://example.com',
+    ],
+
     CUSTOM_ENDPOINT_ORIGINS: {
-        'subfolder/endpoint': ['https://app.example.com'],
+        'subfolder/example-protected': ['https://app.example.com'],
     },
+
+    // Database configuration
     DB_HOST: '127.0.0.1',
     DB_NAME: 'example_db',
     DB_USER: 'root',
     DB_PASS: '',
-    APP_ENV: 'production', // anything else = verbose errors
+
+    // Environment: 'production' hides error details; anything else = debug.
+    APP_ENV: 'production',
 };
 ```
 
@@ -147,6 +160,26 @@ endpoints).
 Resolution order: `CUSTOM_ENDPOINT_ORIGINS[path]` if present, otherwise
 `GENERAL_ALLOWED_ORIGINS`.
 
+### Error verbosity
+
+`APP_ENV` decides what an unhandled exception tells the client.
+
+| Value | Response to a 500 |
+|---|---|
+| `'production'` (default) | `{"status":"error","message":"Internal server error","code":500}` |
+| anything else | the real exception message, plus `stack` (Node) or `file` and `line` (PHP) |
+
+On PHP it does one extra thing: `'production'` also turns off `display_errors`
+and `error_reporting`, so a stray warning can't be printed before the JSON and
+corrupt the response body.
+
+Set it to something like `'development'` while building, and back to
+`'production'` before you publish. Missing key means `'production'`.
+
+> This is a config key, **not** an environment variable. Setting `APP_ENV` in a
+> shell or in a systemd unit has no effect — both backends read it from
+> `config.js` / `config.php` only.
+
 ## Database
 
 Both backends expose a connection singleton reading the same config —

package/docs/Deploy.md

@@ -62,6 +62,8 @@ automatically.
 modules) proxies `/api` to Node and wins if present. Remove it to fall through
 to `ApiToPhp`, which rewrites `/api` to the PHP front controller.
 
+---
+
 ## Your own server (Nginx on a VPS)
 
 Nginx doesn't read per-directory config files — the whole site lives in one file.
@@ -69,6 +71,68 @@ Nibula ships `nginx.conf` in the project root as a ready-to-use site file that
 **covers both backends without edits**: `/api` goes to Node, and if Node is
 unreachable the request falls through to PHP automatically.
 
+Upload the contents of `out` to `/var/www/SITE_FOLDER`, then follow the steps
+below.
+
+### 1. Replace
+
+| Placeholder | Where |
+|---|---|
+| `YOUR_DOMAIN` | `server_name`, twice (port 80 and 443) |
+| `SITE_FOLDER` | document root under `/var/www/` |
+| `YOUR_CERTIFICATE` | dir under `/etc/letsencrypt/live/` |
+| `SITE_NAME` | file name in the commands below |
+
+### 2. Install (skip if already present)
+
+```bash
+sudo apt update
+sudo apt install -y nginx certbot python3-certbot-nginx
+```
+
+If you are using PHP as backend:
+
+```bash
+sudo apt install -y php-fpm
+```
+
+### 3. Certificate
+
+```bash
+sudo certbot certonly --nginx --cert-name SITE_NAME -d YOUR_DOMAIN
+sudo systemctl enable --now certbot.timer      # auto-renew every 90 days
+```
+
+### 4. Install the site
+
+```bash
+# Move to nginx folders
+cd /etc/nginx/sites-available
+
+# Create and write a new file
+sudo nano SITE_NAME
+# CTRL + O, ENTER, CTRL + X
+
+# Copy the config to sites-enabled
+sudo cp SITE_NAME ../sites-enabled/
+
+# Test and reload the nginx configuration
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+### If it fails
+
+| Symptom | Cause |
+|---|---|
+| `cannot load certificate ... Permission denied` | `nginx -t` needs sudo |
+| `cannot load certificate ... No such file` | wrong certificate name |
+| `no alternative certificate subject name` | certificate doesn't cover domain |
+| `unknown directive "http2"` | nginx < 1.25, check with `nginx -v` |
+| NXDOMAIN / timeout during certbot | DNS not pointing here |
+| 500 instead of the 404 page | `404.html` missing |
+| 502 on `/api`, Node deployed | Node process not running |
+| 502 on `/api`, PHP deployed | wrong php-fpm socket path |
+
 ---
 
 ## Starting the Node backend on the server
@@ -77,7 +141,7 @@ After uploading `out`:
 
 1. Install the backend's runtime deps:
    ```bash
-   cd /var/www/backend/SITE_FOLDER
+   cd /var/www/SITE_FOLDER/backend
    npm install
    ```
 
@@ -91,24 +155,50 @@ After uploading `out`:
    sudo node /var/www/SITE_FOLDER/backend/_core/index.js
    curl http://127.0.0.1:3000/api/example-public
    ```
-4. Exit the screen without closing the process with `CTRL + A`, `D`. To resume the screen type `screen -r node-backend`.
 
-5. For production use **systemd**, which also restarts on crash and reboot. An
-   example unit ships at `backend/backend-node.service.example` — copy it to
-   `/etc/systemd/system/backend-node.service`, adjust `WorkingDirectory` and the
-   `node` path (`which node`), then:
+4. Exit the screen without closing the process with `CTRL + A`, `D`. To resume
+   the screen type `screen -r node-backend`.
+
+5. For production use **systemd**, which also restarts on crash and reboot.
+   Create `/etc/systemd/system/backend-node.service`:
+
+   ```ini
+   [Unit]
+   Description=Nibula Node backend
+   After=network.target
+
+   [Service]
+   Type=simple
+   User=www-data
+   WorkingDirectory=/var/www/SITE_FOLDER/backend
+   ExecStart=/usr/bin/node /var/www/SITE_FOLDER/backend/_core/index.js
+   Restart=always
+   RestartSec=5
+
+   [Install]
+   WantedBy=multi-user.target
+   ```
+
+   Adjust `WorkingDirectory` and the `node` path (`which node`), then:
+
    ```bash
    sudo systemctl daemon-reload
    sudo systemctl enable --now backend-node
    sudo systemctl status backend-node
    ```
+
    (`pm2` works too: `pm2 start _core/index.js --name backend-node`.)
 
 ### Environment variables
 
+Read by the Node backend at startup. Set them in the systemd unit with
+`Environment=KEY=value`.
+
 | Variable | Default | Purpose |
 |---|---|---|
-| `PORT` | `3000` | Port Node listens on (match your proxy target) |
+| `PORT` | `3000` | Port Node listens on (must match the proxy target in `nginx.conf`) |
 | `HOST` | `127.0.0.1` | Bind address — keep it local; the web server is the public face |
-| `APP_ENV` | `production` | `production` hides error details; anything else = verbose 500s |
-| `DOCUMENT_ROOT` | auto (`SITE_FOLDER/`) | Where `404.html` lives; detected as the folder above `backend/` |
+| `DOCUMENT_ROOT` | auto (`SITE_FOLDER/`) | Where `404.html` lives; detected as the folder above `backend/` |
+
+Error verbosity is **not** an environment variable: it is the `APP_ENV` key in
+`config.js` / `config.php`. See `docs/Backend.md`.

package/nginx.conf

@@ -1,49 +1,12 @@
 # =============================================================================
-#  Nibula — default nginx site configuration
+#  Nibula — nginx site configuration
 # -----------------------------------------------------------------------------
-# 1. REPLACE
+#  Replace the three placeholders below, then follow the setup steps in
+#  docs/Deploy.md → "Your own server (Nginx on a VPS)".
 #
-#    YOUR_DOMAIN        server_name, twice (port 80 and 443)
-#    SITE_FOLDER        document root under /var/www/
-#    YOUR_CERTIFICATE   dir under /etc/letsencrypt/live/ 
-#    SITE_NAME          commands below file name
-#
-# 2. INSTALL (skip if already present)
-#
-#     sudo apt update
-#     sudo apt install -y nginx certbot python3-certbot-nginx
-#
-#     If you are using PHP as backend:
-#     sudo apt install -y php-fpm
-#
-# 3. CERTIFICATE
-#
-#     sudo certbot certonly --nginx --cert-name SITE_NAME -d YOUR_DOMAIN
-#     sudo systemctl enable --now certbot.timer      # auto-renew every 90 days
-#
-# 4. INSTALL THE SITE
-#
-#    Move to nginx folders
-#    cd /etc/nginx/sites-available
-#
-#    Create and write a new file
-#    sudo nano SITE_NAME
-#    CTRL + O, ENTER, CTRL + X
-#
-#    Copy the config to sites-enabled
-#    sudo cp SITE_NAME ../sites-enabled/
-#
-#    Test and reload the nginx configuration
-#    sudo nginx -t && sudo systemctl reload nginx
-#
-# IF IT FAILS
-#    cannot load certificate ... Permission denied  → nginx -t needs sudo
-#    cannot load certificate ... No such file       → wrong certificate name
-#    no alternative certificate subject name        → certificate doesn't cover domain
-#    unknown directive "http2"                      → nginx < 1.25, check with nginx -v
-#    500 instead of the 404 page                    → 404.html missing
-#    NXDOMAIN / timeout during certbot              → DNS not pointing here
-#    502 on /api with PHP deployed                  → wrong php-fpm socket path
+#    YOUR_DOMAIN        your domain — server_name, twice (port 80 and 443)
+#    SITE_FOLDER        the folder under /var/www/ holding the site
+#    YOUR_CERTIFICATE   the directory name under /etc/letsencrypt/live/
 # =============================================================================
 
 # HTTP (80) configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "1.5.0",
+  "version": "1.5.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",

package/src/backend/example.config.php

@@ -1,14 +1,21 @@
 <?php
 declare(strict_types=1);
 
+/**
+ * Mirror of src/backend/example.config.js
+ *
+ * Versioned, secret-free template. On setup, copy this file to config.php and
+ * fill in real values. config.php is git-ignored and stays local.
+ */
+
 return [
     // Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
     'GENERAL_API_KEY' => 'DEFAULT_KEY',
 
-    // If you want restrict access to protected endpoints to specific clients, you can define custom keys for each endpoint
+    // If you want to restrict access to protected endpoints to specific clients, define custom keys per endpoint.
     // For subfolder endpoints, use the relative path ('subfolder/endpoint')
     'CUSTOM_ENDPOINT_KEYS' => [
-        'subfolder/example-protected'    => 'custom-key',
+        'subfolder/example-protected' => 'custom-key',
     ],
 
     'GENERAL_ALLOWED_ORIGINS' => [
@@ -17,7 +24,7 @@ return [
     ],
 
     'CUSTOM_ENDPOINT_ORIGINS' => [
-        'subfolder/example-protected'    => ['https://app.example.com'],
+        'subfolder/example-protected' => ['https://app.example.com'],
     ],
 
     // Database configuration
@@ -25,4 +32,7 @@ return [
     'DB_NAME' => 'example_db',
     'DB_USER' => 'root',
     'DB_PASS' => '',
+
+    // Environment: 'production' hides error details; anything else = debug.
+    'APP_ENV' => 'production',
 ];

package/src/backend/package.json

@@ -6,8 +6,7 @@
   "main": "_core/index.js",
   "type": "commonjs",
   "scripts": {
-    "start": "node _core/index.js",
-    "dev": "APP_ENV=development node _core/index.js"
+    "start": "node _core/index.js"
   },
   "engines": {
     "node": ">=18"

package/tools/lib/files.js

@@ -52,6 +52,16 @@ function removeDirectory(target) {
     return true;
 }
 
+function removeDirectoryIfEmpty(target) {
+    try {
+        if (fs.readdirSync(target).length > 0) return false;
+        fs.rmdirSync(target);
+        return true;
+    } catch (error) {
+        return false;
+    }
+}
+
 module.exports = {
     exists,
     readText,
@@ -62,4 +72,5 @@ module.exports = {
     moveFile,
     removeFile,
     removeDirectory,
-};
+    removeDirectoryIfEmpty,
+};

package/tools/lib/pageActions.js

@@ -1,7 +1,7 @@
 const path = require('path');
 const settings = require('../config/settings.json');
 const { PATHS } = require('./paths');
-const { exists, readText, writeText, copyFile, moveFile, removeFile, removeDirectory } = require('./files');
+const { exists, readText, writeText, copyFile, moveFile, removeFile, removeDirectory, removeDirectoryIfEmpty } = require('./files');
 const { log } = require('./logger');
 const { formatText } = require('./text');
 const { languageSettings } = require('./project');
@@ -133,6 +133,12 @@ function removePage(pageName) {
 
     removePageBlock(pageName);
     removeSiteData(pageName);
+
+    const sourceDirectories = [source.style, source.script, source.route].map(file => path.dirname(file));
+
+    for (const directory of sourceDirectories) {
+        if (removeDirectoryIfEmpty(directory)) log('page.fileDeleted', { path: directory });
+    }
 }
 
 module.exports = { addPage, removePage, renamePage };

package/.github/workflows/publish.yml

@@ -1,37 +0,0 @@
-name: Publish to npm
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
-
-      - name: Check that package.json matches the tag
-        if: github.event_name == 'release'
-        run: |
-          TAG="${GITHUB_REF_NAME#v}"
-          PKG=$(node -p "require('./package.json').version")
-          if [ "$TAG" != "$PKG" ]; then
-            echo "Tag $TAG does not match package.json version $PKG"
-            exit 1
-          fi
-
-      - run: npm install -g npm@latest
-
-      - run: npm ci
-
-      - run: npm publish --provenance --access public