nibula 1.2.6 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.4.0] - 2026-08-03
+
+### Changed
+- `nginx.conf` is now a complete, ready-to-use site file instead of a set of
+  directives to paste into your own `server` block. Replace three placeholders
+  (`YOUR_DOMAIN`, `SITE_FOLDER`, `YOUR_CERTIFICATE`), symlink it into
+  `sites-enabled/`, reload.
+- Nginx documentation moved from `docs/Deploy.md` to `docs/Nginx.md`;
+  `Deploy.md` now covers only where to publish, one section per server.
+
+### Added
+- HTTP → HTTPS redirect on port 80, with an optional ACME webroot block.
+- TLS setup via Let's Encrypt, with placeholders for the certificate path.
+- Security headers: `X-Content-Type-Options`, `X-Frame-Options`,
+  `Referrer-Policy`, `Strict-Transport-Security` (`max-age=300` by default).
+- `.php` requests return 404, preventing source-code leaks when php-fpm is
+  not configured.
+
+### Removed
+- **Breaking:** the automatic Node → PHP fallback on Nginx. `/api` is now
+  proxied to Node only; if the process is down, Nginx returns 502. For a PHP
+  deployment, edit the `.php` block and `try_files` as described in
+  `docs/Nginx.md`.
+
+### Migration
+Existing Nginx deployments: replace your `server` block with the new
+`nginx.conf` and fill in the three placeholders. If you relied on the PHP
+fallback, follow *Using the PHP backend* in `docs/Nginx.md`.
+
+## [1.3.0] - 2026-08-01
+
+### Added
+- A `global.js` module in `src/frontend/js/modules/`, for code that has to run
+  on every page — a header menu, a theme toggle, a cookie banner. Page entry
+  points import it once and it takes care of running the shared modules, so
+  there's no longer a line to remember in every single page.
+- `docs/Javascript.md` now covers the global module, with the header burger
+  menu as a worked example and a note on when a behaviour belongs in
+  `global.js` rather than in a page.
+
+### Changed
+- Page entry points, and the template new pages are created from, now start
+  with `import '../modules/global.js';`.
+
+### Notes
+- Existing projects keep working as they are. To adopt the global module, add
+  `src/frontend/js/modules/global.js` and the import line at the top of each
+  page entry point.
+
 ## [1.2.6] - 2026-08-01
 
 ### Fixed

package/README.md

@@ -43,10 +43,10 @@ Nibula ships with a clean, opinionated layout so beginners are never lost. But i
 
 * **Node.js**: v18.0.0 or higher
 * **Composer** *(only if you choose the PHP backend)*: latest version
+* **Better Nunjucks** — VS Code extension by **Ed Heltzel**
 
 ### Recommended
 
-* **Better Nunjucks** — VS Code extension by **Ed Heltzel**
 * **Material Icon Theme** — VS Code extension by **Philipp Kief**
 
 ## 📦 Installation

package/docs/Backend.md

@@ -11,7 +11,7 @@ Only the language differs.
 > | Host | PHP | Node.js |
 > |---|---|---|
 > | Apache (shared hosting, VPS) | ✅ | ⚠️ needs a persistent process (VPS only) |
-> | Nginx + PHP-FPM (VPS) | ✅ | ✅ (Nginx reverse-proxies to Node) |
+> | Nginx (VPS) | ⚠️ works, but the shipped `nginx.conf` targets Node — needs a manual `fastcgi_pass` block | ✅ (Nginx reverse-proxies to Node) |
 > | IIS (Windows Server) | ✅ FastCGI | ✅ via ARR reverse proxy |
 > | Static hosting (Netlify, Vercel, GitHub Pages, Cloudflare Pages) | ❌ | ❌ |
 >

package/docs/Deploy.md

@@ -1,13 +1,8 @@
-# Server Configuration
+# Deploy
 
-Nibula builds a static site into your output folder (`out`). To put it online you
-upload that folder to a web server. Which server config you need depends on
-**where** you publish and **which backend** you chose at scaffold time (PHP or
-Node.js — see `docs/Backend.md`).
-
-The shipped `.htaccess`, `web.config` and `nginx.conf` are written to cover
-**both** backends, so you don't swap config files based on your choice. There is
-one caveat on Apache/IIS, explained at the end.
+Nibula builds a static site into `out`. To publish it you upload that folder to a
+web server. What you need depends on **where** you publish and **which backend**
+you chose at scaffold time (PHP or Node.js — see `docs/Backend.md`).
 
 ## Prerequisites
 
@@ -15,101 +10,56 @@ one caveat on Apache/IIS, explained at the end.
 FastCGI) and Composer for the backend dependencies. Works on typical shared
 hosting.
 
-**Node backend:** Node.js 18+ on the server and the ability to run a
-long-running process — i.e. a VPS you control, not typical shared hosting. No PHP
-or Composer required.
-
-## Where to publish
-
-### Shared hosting (Apache — e.g. Aruba, most cPanel providers)
-
-The most common and beginner-friendly option, and the natural home for the
-**PHP** backend (shared hosting can't keep a Node process alive). You rent space
-on a server that's already set up and just upload your files.
-
-Take the **contents of the `out` folder** and upload them to the hosting's public
-web root (often `htdocs`, `public_html`, or `www`). That's it — the site is live.
-`.htaccess` (Apache) or `web.config` (IIS) are already inside `out` and get picked
-up automatically, handling security and routing for you.
-
-### Your own server (Nginx — e.g. an Ubuntu VPS)
-
-If you rent a bare server (a VPS) and install everything yourself, it typically
-runs **Nginx** on **Ubuntu Server**. Here nothing is pre-configured: you set up
-Nginx, the backend, and the security rules by hand. This is the setup for the
-**Node** backend (and also works for PHP + PHP-FPM). The Nginx section below
-gives you the essential rules to start from.
+**Node backend:** Node.js 18+ and the ability to run a long-running process —
+i.e. a VPS you control, not typical shared hosting. No PHP or Composer required.
 
 ---
 
-## Apache (`.htaccess`)
-
-`.htaccess` files at `src/frontend/` and `src/backend/` are copied into the build
-output by Eleventy. No setup required — upload `out` and Apache reads them.
-
-They cover:
-- Directory listing disabled
-- 403 / 404 → `/404.html`
-- Sensitive files blocked (`web.config`, dotfiles, etc.)
-- Backend source directory sealed — all access funnels through the front controller
-- `/api/*` routing (see the dual-backend note below)
+## Shared hosting (Apache)
 
-**Dual backend:** if `mod_proxy` is available, `/api` is reverse-proxied to the
-Node backend (`127.0.0.1:3000`); if not (typical shared hosting), `/api` is
-rewritten to the PHP front controller. To force PHP on a server that *has*
-`mod_proxy`, comment the `mod_proxy` block in `.htaccess`.
+The most common option, and the natural home for the **PHP** backend — shared
+hosting can't keep a Node process alive.
 
-## IIS (`web.config`)
+Upload the **contents of `out`** to the hosting's web root (often `htdocs`,
+`public_html`, or `www`). Done. `.htaccess` is already inside `out` and Apache
+reads it automatically: directory listing off, 403/404 → `/404.html`, sensitive
+files blocked, backend source sealed, `/api/*` routed.
 
-For Windows-based hosting. `web.config` files at `src/frontend/` and
-`src/backend/` are copied into the build output by Eleventy and read
-automatically — same idea as `.htaccess`, different server.
+**Backend routing:** if `mod_proxy` is available, `/api` is reverse-proxied to
+Node on `127.0.0.1:3000`; if not, `/api` is rewritten to the PHP front
+controller. To force PHP on a proxy-enabled server, comment the `mod_proxy`
+block in `.htaccess`.
 
-**Dual backend:** the `ApiToNode` rewrite rule (requires the ARR + URL Rewrite
-modules) reverse-proxies `/api` to Node and wins if present. To use PHP instead,
-remove the `ApiToNode` rule; the `ApiToPhp` fallback then rewrites `/api` to the
-PHP front controller.
+## Windows hosting (IIS)
 
-## Nginx
+Same idea, different server. Upload the contents of `out`; `web.config` is
+already there and read automatically.
 
-Used when you run your **own Ubuntu Server** (a VPS). Unlike Apache and IIS, Nginx
-does **not** read per-directory config files, so there's nothing automatic here.
+**Backend routing:** the `ApiToNode` rewrite rule (requires the ARR + URL Rewrite
+modules) reverse-proxies `/api` to Node and wins if present. Remove it to fall
+back to `ApiToPhp`, which rewrites `/api` to the PHP front controller.
 
-**`nginx.conf` in the project root is not a ready-to-use file.** It is a set of
-directives you adapt into a complete Nginx `server { }` block — the one that
-defines your domain (`server_name`), ports (`listen`), and SSL certificates.
-Paste these rules inside your own server block and set `root` to your `out`
-folder.
+## Your own server (Nginx on a VPS)
 
-They provide:
-- `server_tokens off` — hides the Nginx version
-- `autoindex off` — disables directory listing
-- 403 / 404 → `/404.html`
-- Backend source directory (`/backend/`) sealed with `return 404`
-- Server config files (`.htaccess`, `web.config`) blocked anywhere in the tree
-- `/api/*` routed to the backend (see below)
-- Security headers on static responses
+The setup for the **Node** backend. Unlike Apache and IIS, Nginx doesn't read
+per-directory config files — the whole site is defined in one file.
 
-**Dual backend (auto-fallback):** the shipped `nginx.conf` sends `/api` to the
-Node backend on `127.0.0.1:3000` and, if Node is unreachable (502/504), falls
-back automatically to the PHP front controller. So the same config works whether
-you deployed Node or PHP — Nginx is the only server that can do this fallback
-automatically.
+Nibula ships `nginx.conf` in the project root as a **ready-to-use site file**:
+replace three placeholders, symlink it, reload.
 
-> Setting up Nginx fully (SSL, HTTPS redirect, PHP-FPM and/or the Node service)
-> goes beyond these rules. These directives are the security starting point, not
-> a complete server setup.
+```bash
+sudo cp nginx.conf /etc/nginx/sites-available/my-site
+sudo nano /etc/nginx/sites-available/my-site        # YOUR_DOMAIN, SITE_FOLDER, YOUR_CERTIFICATE
+sudo ln -s /etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
 
-### PHP-FPM socket
+Full reference, requirements and troubleshooting: **`docs/Nginx.md`**.
 
-When using the PHP path, the socket in the `/api` fallback targets Debian/Ubuntu
-by default. Check with `ls /run/php/` and adjust:
+## Static hosting (Netlify, Vercel, GitHub Pages)
 
-| Distro | Path |
-|---|---|
-| 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` |
+Frontend only. Neither backend runs there — no PHP, no persistent process. Fine
+if your site has no `/api` endpoints.
 
 ---
 
@@ -119,49 +69,48 @@ Unlike PHP, the Node backend is **not** executed by the web server per request
 it is a process you start and keep alive. After uploading your built `out` folder:
 
 1. Install the backend's runtime deps (only needed if an endpoint uses the DB):
-   ```bash
+```bash
    cd /var/www/your-site/out/backend
    npm install
-   ```
+```
 
 2. Make sure `config.js` exists in `out/backend/` (copy `example.config.js` to
    `config.js` if missing) and fill in your values.
 
 3. Start it — quick test first:
-   ```bash
+```bash
    node _core/index.js
    # -> [backend-node] listening on http://127.0.0.1:3000 (env: production)
-   ```
+```
    Then, from the server, confirm it answers:
-   ```bash
+```bash
    curl http://127.0.0.1:3000/api/example-public
-   ```
+```
 
    > Running `node _core/index.js` directly ties the process to your SSH session —
-   > close the terminal and the backend dies. The recommended way to try it out
-   > without staying stuck there is **`screen`** (a detachable terminal):
+   > close the terminal and the backend dies. To try it out without staying stuck
+   > there, use **`screen`** (a detachable terminal):
    > ```bash
    > screen -S backend            # open a named session
    > node _core/index.js          # start the backend inside it
    > # press Ctrl+A then D to detach — the backend keeps running
    > # reattach later with:  screen -r backend
    > ```
-   > `screen` is perfect for testing and small setups. For a real production
-   > deployment that also restarts on crash/reboot, prefer **systemd** (step 4).
+   > `screen` is fine for testing. For production, prefer **systemd** (step 4).
 
 4. To keep it running after logout, use **systemd**. 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:
-   ```bash
+```bash
    sudo systemctl daemon-reload
    sudo systemctl enable --now backend-node
    sudo systemctl status backend-node
-   ```
+```
    (`pm2` also works: `pm2 start _core/index.js --name backend-node`.)
 
-The web server then reverse-proxies `/api` to this process; with the shipped
-`nginx.conf`, if Node is down Nginx falls back to PHP automatically.
+The web server then reverse-proxies `/api` to this process. If Node is down the
+proxy returns 502 — there is no automatic PHP fallback.
 
 ### Environment variables
 
@@ -174,17 +123,13 @@ The web server then reverse-proxies `/api` to this process; with the shipped
 
 ---
 
-## The one caveat on Apache and IIS
+## One config file, one backend
 
-Nginx can health-check the Node upstream and fall back to PHP automatically.
-Apache (`.htaccess`) and IIS (`web.config`) **cannot** — a per-directory config
-can't know whether Node is up. So there the routing is decided by configuration,
-not at runtime:
+Each server config targets a specific backend, decided at setup time rather than
+at runtime:
 
-- **Apache:** `mod_proxy` present → Node; absent → PHP. Comment the `mod_proxy`
-  block to force PHP on a proxy-enabled server.
-- **IIS:** `ApiToNode` rule present (needs ARR) → Node; remove it to use the
-  `ApiToPhp` fallback.
+- **Apache:** `mod_proxy` present → Node; absent → PHP
+- **IIS:** `ApiToNode` rule present (needs ARR) → Node; remove it for `ApiToPhp`
+- **Nginx:** ships configured for Node; see `docs/Nginx.md` for PHP
 
-Since a given deployment runs only one backend, this is a one-time setup, not a
-per-request concern.
+Since a given deployment runs only one backend, this is a one-time setup.

package/docs/Javascript.md

@@ -11,6 +11,7 @@ Import only what the page needs.
 ### examplePage.js <small>(`src/frontend/js/pages/`)</small>
 
 ```js
+import '../modules/global.js';
 // import { initExampleModule } from '../modules/exampleModule.js';
 
 document.addEventListener("DOMContentLoaded", () => {
@@ -20,6 +21,79 @@ document.addEventListener("DOMContentLoaded", () => {
 // Page logic here
 ```
 
+## Global JS
+
+Some code has to run on every page: a header menu, a theme toggle, a cookie banner. Repeating it in every page entry point means you'll eventually forget it on one of them, and the bug only shows up on that single page.
+
+That's what `global.js` is for. It lives in `src/frontend/js/modules/`, every page entry point imports it, and it takes care of running the shared modules.
+
+### global.js <small>(`src/frontend/js/modules/`)</small>
+
+```js
+// import { initExampleModule } from './exampleModule.js';
+
+function initGlobal() {
+    // initExampleModule();
+}
+
+// Global logic here
+
+// Do not touch this line
+document.addEventListener('DOMContentLoaded', initGlobal);
+```
+
+Pages import it without curly braces, since there is nothing to export — the module runs on its own as soon as it's part of the bundle:
+
+```js
+import '../modules/global.js';
+```
+
+Note that the import path inside `global.js` is `'./exampleModule.js'` and not `'../modules/exampleModule.js'`: `global.js` already sits in the modules folder, next to the modules it imports.
+
+### A concrete example: the header menu
+
+A responsive header has a burger button that opens the navigation on small screens. The header is included in `base.njk`, so it's on every page — a textbook case for `global.js`.
+
+Write the behaviour as a normal module:
+
+```js
+// src/frontend/js/modules/header.js
+
+export function initHeader() {
+    const toggle = document.querySelector('.menu-toggle');
+    const menu = document.querySelector('.menu');
+
+    if (!toggle || !menu) return;
+
+    toggle.addEventListener('click', () => {
+        menu.classList.toggle('is-open');
+    });
+}
+```
+
+Then wire it up once, in `global.js`:
+
+```js
+import { initHeader } from './header.js';
+
+function initGlobal() {
+    initHeader();
+}
+
+// Do not touch this line
+document.addEventListener('DOMContentLoaded', initGlobal);
+```
+
+The burger now works on every page, and no page entry point had to change. Adding another global behaviour later is two lines: one import, one call inside `initGlobal()`.
+
+The early `return` matters: if a page has no header, the module does nothing instead of throwing an error that would stop your other scripts.
+
+### Global or page module?
+
+Use `global.js` for behaviour tied to something present on every page — anything included in `base.njk`, essentially.
+
+Keep it in the page entry point when only one or two pages need it. Everything imported by `global.js` ends up in *every* page bundle, so a heavy module used by a single page belongs in that page instead.
+
 ## Modules
 
 Modules live in `src/frontend/js/modules/`. Modules that interact with the DOM must be called inside `DOMContentLoaded`; others can be called anywhere.

package/docs/Nginx.md

@@ -0,0 +1,133 @@
+# Nginx
+
+`nginx.conf` in the project root is a **ready-to-use site file** for a Nibula
+site on your own server (a VPS). Replace three placeholders, symlink it, reload.
+
+It targets the **Node** backend; see *Using the PHP backend* below for PHP.
+
+## Setup
+
+| Placeholder | Value |
+|---|---|
+| `YOUR_DOMAIN` | your domain — appears twice (port 80 and 443) |
+| `SITE_FOLDER` | document root under `/var/www/` — your uploaded `out` folder |
+| `YOUR_CERTIFICATE` | dir name under `/etc/letsencrypt/live/` — **not always equal to the domain**: a cert may be issued for a different hostname (common with DDNS) or cover several domains. Check with `sudo certbot certificates` |
+
+```bash
+sudo cp nginx.conf /etc/nginx/sites-available/my-site
+sudo nano /etc/nginx/sites-available/my-site        # replace the placeholders
+sudo ln -s /etc/nginx/sites-available/my-site /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+Verify:
+
+```bash
+curl -I http://YOUR_DOMAIN/                # 301 to https
+curl -I https://YOUR_DOMAIN/               # 200
+curl -I https://YOUR_DOMAIN/nonexistent    # 404, not 200 or 500
+```
+
+On RHEL/Alpine there is no `sites-available`; put the file in
+`/etc/nginx/conf.d/` instead.
+
+## Requirements
+
+- A valid certificate covering `YOUR_DOMAIN`
+- `404.html` present in the document root and readable by nginx
+- Nginx ≥ 1.25 for `http2 on;` — on older versions use `listen 443 ssl http2;`
+
+## What it provides
+
+- HTTP → HTTPS redirect on port 80
+- TLS via Let's Encrypt, with the Certbot SSL options included
+- `server_tokens off` and `autoindex off`
+- 403 / 404 → `/404.html`, preserving the original status code
+- Backend source directory (`/backend/`) sealed with `return 404`
+- `web.config`, dotfiles and `.php` blocked
+- Security headers: `X-Content-Type-Options`, `X-Frame-Options`,
+  `Referrer-Policy`, `Strict-Transport-Security`
+- `/api/*` reverse-proxied to the Node backend on `127.0.0.1:3000`
+
+## Certificate renewal
+
+The `/.well-known/acme-challenge/` block is only needed with the **webroot**
+authenticator. If you obtained the certificate with `certbot --nginx`, remove it.
+Check with:
+
+```bash
+grep authenticator /etc/letsencrypt/renewal/YOUR_DOMAIN.conf
+```
+
+When adding a domain to an existing certificate, always pass `--cert-name` **and
+list every domain already covered** — omitted ones are dropped, and without the
+flag Certbot creates a separate certificate instead of expanding.
+
+## HSTS
+
+The file ships with `max-age=300` deliberately. Browsers cache the HSTS policy
+for the whole `max-age` **even after you remove the header**, so a long value
+combined with a broken certificate locks visitors out with no way back.
+
+Raise it to `31536000` once HTTPS is confirmed stable. Add `; includeSubDomains`
+only if every current and future subdomain is served over HTTPS with a valid
+certificate.
+
+## WebSocket
+
+Not enabled by default. If your backend uses socket.io or similar, add a map at
+`http` level (e.g. `/etc/nginx/conf.d/websocket.conf`):
+
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+```
+
+and inside `location ^~ /api/`:
+
+```nginx
+proxy_set_header Upgrade    $http_upgrade;
+proxy_set_header Connection $connection_upgrade;
+```
+
+For long-lived connections also raise `proxy_read_timeout`, ideally in a
+dedicated location for the socket path so normal API requests keep the 60s
+default.
+
+## Using the PHP backend
+
+This file targets Node. `.php` requests return 404 by design: without a
+`fastcgi_pass` block Nginx would serve them as plain text and leak source code,
+database credentials included.
+
+For a PHP deployment, replace the `.php` block with:
+
+```nginx
+location ~ \.php$ {
+    include snippets/fastcgi-php.conf;
+    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
+}
+```
+
+and change `try_files` in `location /` to `$uri $uri/ /index.php?$query_string`.
+
+Check the socket path with `ls /run/php/`:
+
+| Distro | Path |
+|---|---|
+| 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` |
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `cannot load certificate ... Permission denied` | `nginx -t` run without `sudo` — the certs are root-only |
+| `no alternative certificate subject name matches` | the cert doesn't cover `YOUR_DOMAIN`; check `sudo certbot certificates` |
+| 500 instead of the 404 page | `404.html` missing or unreadable by nginx |
+| `unknown directive "http2"` | Nginx < 1.25 — use `listen 443 ssl http2;` |
+| 502 on `/api/*` | the Node process isn't running; see `docs/Deploy.md` |
+| Site not responding at all | symlink missing in `sites-enabled/`, or nginx not reloaded |

package/nginx.conf

@@ -1,75 +1,118 @@
-# Example nginx directives for a Nibula site — covers BOTH backends.
+# =============================================================================
+#  Nibula — default nginx site configuration
+#  Static site + optional HTTP backend on 127.0.0.1:3000. PHP not handled.
+# -----------------------------------------------------------------------------
+#  REPLACE
+#    YOUR_DOMAIN        server_name, twice (port 80 and 443)
+#    SITE_FOLDER        document root under /var/www/
+#    YOUR_CERTIFICATE   dir under /etc/letsencrypt/live/ — not always the same
+#                       as YOUR_DOMAIN. Check: sudo certbot certificates
 #
-# /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
+#  REQUIRES
+#    valid certificate covering YOUR_DOMAIN
+#    /var/www/SITE_FOLDER/404.html readable by nginx
+#    nginx >= 1.25 for the http2 directive
 #
-# 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.
+#  ENABLE
+#    sudo ln -s /etc/nginx/sites-available/FILE /etc/nginx/sites-enabled/
+#    sudo nginx -t && sudo systemctl reload nginx
+#    curl -I https://YOUR_DOMAIN/nonexistent          # expect 404
+#
+#  IF IT FAILS
+#    "cannot load certificate ... Permission denied"  → run nginx -t with sudo
+#    500 instead of 404                               → 404.html missing
+# =============================================================================
 
-# Hide the nginx version from response headers
-server_tokens off;
+### HTTP -> HTTPS redirect
+server {
+    listen      80;
+    listen      [::]:80;
+    server_name YOUR_DOMAIN;
 
-# Force HTTPS on future requests (applies site-wide, including /api)
-add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+    # Webroot ACME renewal; drop if using the nginx authenticator.
+    location ^~ /.well-known/acme-challenge/ {
+        root /var/www/certbot;
+    }
 
-root /var/www/your-site/out;
-index index.html;
+    location / {
+        return 301 https://$host$request_uri;
+    }
+}
 
-# Disable directory listing
-autoindex off;
+server {
+### Essentials
+    listen      443 ssl;
+    listen      [::]:443 ssl;
 
-error_page 403 404 /404.html;
-location = /404.html {
-    internal;
-}
+    # nginx >= 1.25; older: "listen 443 ssl http2;"
+    http2       on;
 
-# Never expose the backend source directory over HTTP.
-location ^~ /backend/ {
-    return 404;
-}
+    server_name YOUR_DOMAIN;
+    root        /var/www/SITE_FOLDER;
+    index       index.html;
 
-# Block server config files anywhere in the tree (.htaccess, web.config).
-location ~* (^|/)(\.htaccess|web\.config)$ {
-    return 404;
-}
+### Certificate
+    ssl_certificate     /etc/letsencrypt/live/YOUR_CERTIFICATE/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/YOUR_CERTIFICATE/privkey.pem;
+    include             /etc/letsencrypt/options-ssl-nginx.conf;
+    ssl_dhparam         /etc/letsencrypt/ssl-dhparams.pem;
 
-# --- /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;
-}
+### Security headers
+    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;
 
-location @php_backend {
-    include fastcgi_params;
-    fastcgi_param SCRIPT_FILENAME $document_root/backend/_core/index.php;
+    # HSTS persists in browsers for max-age even if removed here. Raise to
+    # 31536000 once stable; "; includeSubDomains" needs HTTPS on all subdomains.
+    add_header Strict-Transport-Security "max-age=300" always;
 
-    # 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;
-}
+    server_tokens off;
+    autoindex     off;
 
-# 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;
-}
+### Blocked paths
+    error_page 403 404 /404.html;
+
+    location ^~ /backend/ {
+        return 404;
+    }
+
+    location ~* ^/(web\.config)$ {
+        return 404;
+    }
+
+    location ~ /\. {
+        return 404;
+    }
+
+    # PHP not handled: without php-fpm these would leak source code.
+    # For PHP sites, replace this block with fastcgi_pass and change
+    # try_files below to: $uri $uri/ /index.php?$query_string
+    location ~ \.php$ {
+        return 404;
+    }
+
+### API 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_read_timeout defaults to 60s; raise only for slow endpoints.
+        proxy_connect_timeout 5s;
+
+        # WebSocket is not enabled; needs a $connection_upgrade map at http level.
+    }
+
+### Static files
+    location / {
+        try_files $uri $uri/ $uri.html =404;
+    }
+
+### Error page
+    location = /404.html {
+        internal;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nibula",
-  "version": "1.2.6",
+  "version": "1.4.0",
   "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/frontend/js/modules/global.js

@@ -0,0 +1,10 @@
+// import { initExampleModule } from "./exampleModule.js";
+
+function initGlobal() {
+    // initExampleModule();
+}
+
+// Global logic here
+
+// Do not touch this line
+document.addEventListener('DOMContentLoaded', initGlobal);

package/src/frontend/js/pages/404.js

@@ -1,4 +1,5 @@
-// import { initExampleModule } from '../modules/exampleModule.js';
+import '../modules/global.js';
+// import { initExampleModule } from '../modules/exampleModule';
 
 document.addEventListener("DOMContentLoaded", () => {
     // initExampleModule();

package/src/frontend/js/pages/homepage.js

@@ -1,4 +1,5 @@
-// import { initExampleModule } from '../modules/exampleModule.js';
+import '../modules/global.js';
+// import { initExampleModule } from '../modules/exampleModule';
 
 document.addEventListener("DOMContentLoaded", () => {
     // initExampleModule();

package/src/frontend/ts/modules/global.ts

@@ -0,0 +1,10 @@
+// import { initExampleModule } from "./exampleModule";
+
+function initGlobal() {
+    // initExampleModule();
+}
+
+// Global logic here
+
+// Do not touch this line
+document.addEventListener('DOMContentLoaded', initGlobal);

package/src/frontend/ts/pages/404.ts

@@ -1,3 +1,4 @@
+import '../modules/global.js';
 // import { initExampleModule } from '../modules/exampleModule';
 
 document.addEventListener("DOMContentLoaded", (): void => {

package/src/frontend/ts/pages/homepage.ts

@@ -1,3 +1,4 @@
+import '../modules/global.js';
 // import { initExampleModule } from '../modules/exampleModule';
 
 document.addEventListener("DOMContentLoaded", (): void => {

package/tools/res/templates/template.js

@@ -1,4 +1,5 @@
-// import { initExampleModule } from '../modules/exampleModule.js';
+import '../modules/global.js';
+// import { initExampleModule } from '../modules/exampleModule';
 
 document.addEventListener("DOMContentLoaded", () => {
     // initExampleModule();

package/tools/res/templates/template.ts

@@ -1,3 +1,4 @@
+import '../modules/global.js';
 // import { initExampleModule } from '../modules/exampleModule';
 
 document.addEventListener("DOMContentLoaded", (): void => {