nibula 1.0.1 → 1.1.0

package/README.md

@@ -16,11 +16,12 @@ Building a website from scratch involves a lot of moving parts: templating, buil
 - 🖱️ **A helpful CLI** — create a page with one command instead of hand-writing ten separate files
 - ⚙️ **Server configs handled for you** — `.htaccess` and `web.config` are generated automatically, and an `nginx.conf` is provided so that anyone comfortable with nginx already has what they need to run the site outside of shared hosting
 - 🎨 **Pick your CSS framework** — choose from 4 pre-installed options (or none), and switch later in a few guided steps
+- 🔌 **Pick your backend** — Node.js or PHP, chosen at creation; **Composer is only needed for PHP**
 - 🧩 **Your own modules** — add your own CSS and JS/TS modules freely and easily
 - 🪶 **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-2.9.0-blue)
+![Version](https://img.shields.io/badge/version-1.1.0-blue)
 ![License](https://img.shields.io/badge/license-Apache--2.0-blue)
 ![Eleventy](https://img.shields.io/badge/11ty-v3.1.2-black)
 
@@ -35,7 +36,7 @@ Either way, the project structure stays the same, so you can start easy and leve
 
 ## Backend included
 
-Essential server-side functionality comes built in — no extra setup required. Backend support will soon let you **choose between PHP, Node, and Python**, so the project can grow with you.
+Essential server-side functionality comes built in — no extra setup required. At project creation you **choose your backend: Node.js or PHP** (Python is planned). Both expose the **same REST API** — same routing, `X-Api-Key` auth, CORS and rate limiting — so you can even switch later without rewriting your endpoints. See [docs/Backend.md](docs/Backend.md) for details.
 
 ## Customizable, but with sensible defaults
 
@@ -43,8 +44,8 @@ Nibula ships with a clean, opinionated layout so beginners are never lost. But i
 
 ## Prerequisites
 
-* **Node.js**: v18.0.0 or higher
-* **Composer**: latest stable version
+* **Node.js**: v18.0.0 or higher — **always required** (the Nibula CLI, the build, and the optional Node backend all run on Node)
+* **Composer**: **only required if you choose the PHP backend**, to install its PHP dependencies. If you pick the **Node** backend, Composer is never used — you can skip installing it entirely.
 * *Optional:* the **Better Nunjucks** VS Code extension by Ed Heltzel
 
 ## Installation
@@ -65,7 +66,7 @@ From the folder where you keep your websites, run:
 nib new your-project
 ```
 
-The scaffolder is interactive: you choose the language (JavaScript/TypeScript) and the CSS framework, and all dependencies are installed automatically.
+The scaffolder is interactive: you choose the **language** (JavaScript/TypeScript), the **CSS framework**, and the **backend** (Node.js or PHP). All dependencies are installed automatically — and if you pick **Node**, the PHP/Composer step is skipped, so you don't need Composer at all.
 
 Then start the dev server and visit `localhost:8080`:
 
@@ -99,7 +100,20 @@ 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:
+
+- **PHP** runs on ordinary shared hosting (Apache/IIS) or a VPS with PHP-FPM — no process to keep alive.
+- **Node** runs as a long-running service on a VPS; the web server reverse-proxies `/api` to it.
+
+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.
+
 ## Roadmap
 
 * [ ] Add support for multiple themes
-* [ ] Backend integration choice — switch between PHP, Python, or Node
+* [x] Backend integration choice — pick **PHP or Node.js** at creation (Python planned)
+* [ ] Extend documentation with advanced usage examples

package/_tools/modules/pageComponents.js

@@ -34,7 +34,7 @@ function addPageBlock(pageName) {
 
     const block =
         `{% elif title == "${camelName}" %}\n` +
-        `{#{% include "component.njk" %}#}\n\n`;
+        `{% include "component.njk" ignore missing %}\n\n`;
 
     writePageComponents(content.replace('{% else %}', `${block}{% else %}`));
     console.log(`[updated] page block added for "${camelName}"`);

package/bin/create.js

@@ -28,6 +28,11 @@ const FRAMEWORK = Object.freeze({
     NONE:       'none',
 });
 
+const BACKEND = Object.freeze({
+    NODE: 'node',
+    PHP:  'php',
+});
+
 // ── CHOICES ──────────────────────────────────────────────────────────────────
 
 const LANGUAGE_CHOICES = [
@@ -43,6 +48,11 @@ const FRAMEWORK_CHOICES = [
     { label: 'None',                value: FRAMEWORK.NONE       },
 ];
 
+const BACKEND_CHOICES = [
+    { label: 'Node.js (index.js — no PHP, no Composer)', value: BACKEND.NODE },
+    { label: 'PHP (index.php — Composer dependencies)',  value: BACKEND.PHP  },
+];
+
 // ── COPY CONFIG ───────────────────────────────────────────────────────────────
 
 const MANDATORY_COPY = [
@@ -117,6 +127,9 @@ node_modules/
 src/backend/_core/vendor/
 out/
 src/backend/config.php
+src/backend/config.js
+src/backend/node_modules/
+src/backend/cache/
 `;
 
 
@@ -203,8 +216,9 @@ function njkUncomment(content, line) {
     return content.split(`{# ${line} #}`).join(line);
 }
 
-function installDependencies() {
-    const backendCore = path.join(targetDir, 'src', 'backend', '_core');
+function installDependencies(backend) {
+    const backendRoot = path.join(targetDir, 'src', 'backend');
+    const backendCore = path.join(backendRoot, '_core');
 
     log(`${color.blue}\n>> Installing Node modules...${color.reset}`);
     const npm = spawnSync('npm', ['install'], {
@@ -220,6 +234,20 @@ function installDependencies() {
         return false;
     }
 
+    // --- Node backend: install its own deps (mysql2), then SKIP Composer ---
+    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
+    }
+
+    // --- PHP backend: install Composer dependencies (if present) ---
     if (!fs.existsSync(path.join(backendCore, 'composer.json'))) {
         return true;
     }
@@ -353,6 +381,7 @@ async function init() {
 
     const language  = await askChoice('Select a language',      LANGUAGE_CHOICES);
     const framework = await askChoice('Select a CSS framework', FRAMEWORK_CHOICES);
+    const backend   = await askChoice('Select a backend',       BACKEND_CHOICES);
 
     log('');
 
@@ -372,6 +401,13 @@ async function init() {
         logAdd('src/backend/config.php');
     }
 
+    const configJsDest    = path.join(targetDir, 'src/backend/config.js');
+    const configJsExample = path.join(targetDir, 'src/backend/example.config.js');
+    if (!fs.existsSync(configJsDest) && fs.existsSync(configJsExample)) {
+        fs.copyFileSync(configJsExample, configJsDest);
+        logAdd('src/backend/config.js');
+    }
+
     const pkg = { ...PROJECT_PACKAGE };
 
     if (language === LANGUAGE.TYPESCRIPT) {
@@ -395,7 +431,7 @@ async function init() {
     applyFramework(framework);
     applyLanguage(language);
 
-    installDependencies();
+    installDependencies(backend);
 
     log(`\n${color.green}>> Done!${color.reset}`);
     log(`${color.yellow}\nNow run:\n${color.reset}`);

package/docs/Backend.md

@@ -1,46 +1,90 @@
 # Backend
 
-> **PHP requirement** — the backend runs only on servers with PHP support:
-> - **Apache** (shared hosting, VPS) ✅
-> - **Nginx** + PHP-FPM (VPS) ✅
-> - **IIS** + FastCGI (Windows Server) ✅
-> - **Static hosting** (Netlify, Vercel, GitHub Pages, Cloudflare Pages) ❌
-
-The backend is a PHP REST API located in `src/backend/`, copied to the output directory automatically at build time.
+Nibula ships **two interchangeable backends** in `src/backend/` — a **PHP** one
+and a **Node.js** one. You pick which to use when you scaffold a project
+(`nib new`). Both provide the same REST API: same routing, same `Response`
+envelope, same `X-Api-Key` auth, same CORS model, same file-based rate limiter.
+Only the language differs.
+
+> **Server requirement** — where each backend can run:
+>
+> | Host | PHP | Node.js |
+> |---|---|---|
+> | Apache (shared hosting, VPS) | ✅ | ⚠️ needs a persistent process (VPS only) |
+> | Nginx + PHP-FPM (VPS) | ✅ | ✅ (Nginx reverse-proxies to Node) |
+> | IIS (Windows Server) | ✅ FastCGI | ✅ via ARR reverse proxy |
+> | Static hosting (Netlify, Vercel, GitHub Pages, Cloudflare Pages) | ❌ | ❌ |
+>
+> Typical shared hosting can run **PHP** but not a long-running Node process, so
+> choose PHP there. On a VPS you control, either works.
+
+The backend lives in `src/backend/` and is copied to the output directory
+automatically at build time.
+
+## Choosing a backend
+
+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.
+
+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.
 
 ## Structure
 
 ```
 src/backend/
 ├── api/
-│   └── protected/    # Endpoints requiring X-Api-Key header
 │   ├── public/       # Endpoints accessible without an API key
+│   └── protected/    # Endpoints requiring the X-Api-Key header
 ├── _core/            # Framework internals (routing, modules) — do not edit
-│   └── modules/      # Response, RateLimiter, ...
+│   ├── index.php     # PHP front controller
+│   ├── index.js      # Node front controller (also the HTTP server)
+│   ├── init.php / init.js
+│   └── modules/      # Response, RateLimiter (.php and .js)
 ├── database/
-│   ├── Database.php
+│   ├── Database.php  # PDO singleton
+│   ├── Database.js   # mysql2 pool singleton
 │   └── migrations/
-├── example.config.php   # Template — versioned, safe to commit
-└── config.php           # Your local config, generated on setup — never commit this
+├── 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
 ```
 
-> A scaffolded project contains **both** files. `config.php` is generated automatically by `nib new` (a copy of the example) and is git-ignored, so your secrets stay local and are never pushed. `example.config.php` is kept and versioned: it's the file that ends up on GitHub, acting as a secret-free reference so anyone cloning the project knows which keys to set. If `config.php` is ever missing (e.g. after a fresh clone), just copy `example.config.php` to `config.php`.
+> 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.
 
-> Note: in the boilerplate repo itself, only `example.config.php` exists — `config.php` is created at scaffold time, not shipped.
+## Key difference: how each backend runs
 
-## Configuration
+- **PHP** is executed **per request** by the web server through PHP-FPM (or
+  FastCGI/mod_php). There is no process to keep alive.
+- **Node** is a **long-running process** that *is* the server, listening on
+  `127.0.0.1:3000`. The web server (Nginx/Apache/IIS) **reverse-proxies** `/api`
+  to it. You start it once and keep it alive (systemd/pm2). See `docs/Deploy.md`.
 
-`config.php` works like a `.env` file — it holds secrets and environment settings that stay local and out of version control.
+## Configuration
 
-Fill in your values:
+`config.php` / `config.js` work like a `.env` file — they hold secrets and
+environment settings that stay local and out of version control. Same keys in
+both, just PHP-array vs JS-object syntax.
 
 ### config.php <small>(`src/backend/`)</small>
 ```php
-// Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
+// Default key for protected endpoints without 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
-// For subfolder endpoints, use the relative path ('subfolder/endpoint')
+// Per-endpoint keys. For subfolder endpoints use the relative path ('subfolder/endpoint')
 'CUSTOM_ENDPOINT_KEYS' => [
     'subfolder/endpoint'    => 'custom-key',
 ],
@@ -61,39 +105,100 @@ Fill in your values:
 'DB_PASS' => '',
 ```
 
+### config.js <small>(`src/backend/`)</small>
+```js
+module.exports = {
+    GENERAL_API_KEY: 'DEFAULT_KEY',
+    CUSTOM_ENDPOINT_KEYS: {
+        'subfolder/endpoint': 'custom-key',
+    },
+    GENERAL_ALLOWED_ORIGINS: ['*' /*, 'https://example.com' */],
+    CUSTOM_ENDPOINT_ORIGINS: {
+        'subfolder/endpoint': ['https://app.example.com'],
+    },
+    DB_HOST: '127.0.0.1',
+    DB_NAME: 'example_db',
+    DB_USER: 'root',
+    DB_PASS: '',
+    APP_ENV: 'production', // anything other than 'production' = verbose errors
+};
+```
+
 ### API keys
 
-`GENERAL_API_KEY` is the fallback key for all protected endpoints. Use `CUSTOM_ENDPOINT_KEYS` to assign a different key to a specific endpoint — for subfolder endpoints, use the relative path as the key.
+`GENERAL_API_KEY` is the fallback key for all protected endpoints. Use
+`CUSTOM_ENDPOINT_KEYS` to assign a different key to a specific endpoint — for
+subfolder endpoints, use the relative path as the key.
 
-> ⚠️ The API key travels in the `X-Api-Key` header on every request. Use it only for server-to-server calls over HTTPS. Never embed it in frontend code, where it would be publicly visible.
+> ⚠️ The API key travels in the `X-Api-Key` header on every request. Use it only
+> for server-to-server calls over HTTPS. Never embed it in frontend code, where
+> it would be publicly visible.
 
 ### CORS (allowed origins)
 
 Cross-origin access mirrors the API-key model:
 
-- `GENERAL_ALLOWED_ORIGINS` — the default list of origins allowed to call any endpoint from a browser.
-- `CUSTOM_ENDPOINT_ORIGINS` — overrides the default for a specific endpoint, keyed by the same relative path used in `CUSTOM_ENDPOINT_KEYS`.
+- `GENERAL_ALLOWED_ORIGINS` — the default list of origins allowed to call any
+  endpoint from a browser.
+- `CUSTOM_ENDPOINT_ORIGINS` — overrides the default for a specific endpoint,
+  keyed by the same relative path used in `CUSTOM_ENDPOINT_KEYS`.
 
-Origins must be exact (scheme + host, no trailing slash), e.g. `https://example.com`. When a request's `Origin` is in the resolved list, it is reflected back in `Access-Control-Allow-Origin` (with `Vary: Origin`). An empty list sends no CORS header — the most restrictive setting; same-origin requests still work. Use `'*'` as the only element to allow any origin (not recommended for protected endpoints).
+Origins must be exact (scheme + host, no trailing slash), e.g.
+`https://example.com`. When a request's `Origin` is in the resolved list, it is
+reflected back in `Access-Control-Allow-Origin` (with `Vary: Origin`). An empty
+list sends no CORS header — the most restrictive setting; same-origin requests
+still work. Use `'*'` as the only element to allow any origin (not recommended
+for protected endpoints).
 
-Resolution order for a given endpoint: `CUSTOM_ENDPOINT_ORIGINS[path]` if present, otherwise `GENERAL_ALLOWED_ORIGINS`.
+Resolution order for a given endpoint: `CUSTOM_ENDPOINT_ORIGINS[path]` if
+present, otherwise `GENERAL_ALLOWED_ORIGINS`.
 
 ## How routing works
 
-The file path inside `api/` maps directly to the URL. Extra URL segments become route parameters available as `$requestParams[]`.
+The file path inside `api/` maps directly to the URL. The `public`/`protected`
+folder does **not** appear in the URL — it only decides whether the `X-Api-Key`
+check applies. So `api/public/example-public` and `api/protected/example-protected`
+are both reached at `/api/<endpoint>`:
+
+- `api/public/example-public` → `/api/example-public` (no key)
+- `api/protected/example-protected` → `/api/example-protected` (requires key)
 
-Every endpoint file has access to:
+Subfolders **do** appear: `api/public/users/list` → `/api/users/list`. Extra URL
+segments become route parameters. Every endpoint has access to:
 
-| Variable | Description |
+| Variable / field | Description |
 |---|---|
-| `$method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
-| `$requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
+| `method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
+| `requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
+
+> If two files share the same path — one in `public/`, one in `protected/` — the
+> public one wins (it is checked first), so the endpoint ends up **without**
+> authentication. Don't duplicate names across the two folders.
+
+> **About the examples below** — the code samples use **JavaScript (the Node
+> backend)** as the reference. That's just the example language: if you chose the
+> **PHP** backend it works exactly the same way, with the same variables, the
+> same `Response` helper and the same behaviour — only the syntax differs. Each
+> section shows the JS version first, with the equivalent PHP right after.
 
 ## Creating a public endpoint
 
-Create a `.php` file anywhere inside `api/public/`
+Create a file anywhere inside `api/public/`.
+
+### `api/public/example.js` (Node — reference)
+```js
+module.exports = ({ method, requestParams, Response }) => {
+    if (method !== 'GET') Response.error('Method not allowed', 405);
+    const id = requestParams[0] ? parseInt(requestParams[0], 10) : null;
+    Response.success({ id });
+};
+```
+
+The Node handler receives a context object: `method`, `requestParams`,
+`Response` (`.success` / `.error` / `.noContent`), plus `query`, `body` (parsed
+JSON), `rawBody`, `headers`, `config`, `req`, `res`.
 
-### api/public/example.php
+The same endpoint in PHP — identical logic, PHP syntax:
 ```php
 <?php
 declare(strict_types=1);
@@ -111,9 +216,18 @@ Response::success(['id' => $id]);
 
 ## Creating a protected endpoint
 
-Create a `.php` file inside `api/protected/`. The API key check happens automatically before your file runs.
+Create a file inside `api/protected/`. The API-key check happens automatically
+before your file runs.
 
-### api/protected/example.php
+### `api/protected/example.js` (Node — reference)
+```js
+module.exports = ({ method, Response }) => {
+    if (method !== 'GET') Response.error('Method not allowed', 405);
+    Response.success({ visits: 1024 });
+};
+```
+
+The same endpoint in PHP:
 ```php
 <?php
 declare(strict_types=1);
@@ -127,25 +241,48 @@ if ($method !== 'GET') {
 Response::success(['visits' => 1024]);
 ```
 
-To assign a dedicated key, add it to `config.php`:
+To assign a dedicated key, add it to your config:
 
+```js
+CUSTOM_ENDPOINT_KEYS: { 'endpoint': 'custom-key' }          // config.js
+```
 ```php
-'CUSTOM_ENDPOINT_KEYS' => [
-    'endpoint' => 'custom-key',
-],
+'CUSTOM_ENDPOINT_KEYS' => [ 'endpoint' => 'custom-key' ],   // config.php
 ```
 
 ## The Response helper
 
+Identical envelope in both backends — JS shown as reference, PHP works the same:
+
+```js
+Response.success(data, code);            // default 200
+Response.error(message, code, details);  // default 400
+Response.noContent();                    // 204
+```
 ```php
 Response::success($data, $code);            // default 200
 Response::error($message, $code, $details); // default 400
-Response::noContent();                      // 204
+Response::noContent();                       // 204
 ```
 
+Response shapes:
+- success → `{ "status": "success", "data": ... }`
+- error → `{ "status": "error", "message": "...", "code": ... }` (+ optional `details`)
+
+## Database
+
+Both backends expose a connection singleton reading the same config.
+
+- **Node** (reference) — `database/Database.js`, a `mysql2` pool singleton:
+  `const pool = Database.getInstance(); const [rows] = await pool.execute(sql, params);`
+  The `mysql2` driver is installed at scaffold time when you choose Node (it is
+  loaded lazily, so the backend also boots fine without a database).
+- **PHP** — `database/Database.php`, a PDO singleton:
+  `$pdo = Database::getInstance();`
+
 ## Pre-built endpoints
 
 | Route | Method | Description |
 |---|---|---|
-| `/api/public/example-public` | `GET` | Example endpoint that doesn't require any key |
-| `/api/protected/example-protected` | `GET` | Example endpoint that requires X-API-KEY |
+| `/api/example-public` | `GET` | Example endpoint that doesn't require any key |
+| `/api/example-protected` | `GET` | Example endpoint that requires `X-Api-Key` |