kaelum 1.3.6 → 1.4.0

package/README.md

@@ -1,258 +1,261 @@
-<div align="center">
-
-<h1>Kaelum</h1>
-
-[![npm version](https://img.shields.io/npm/v/kaelum)](https://www.npmjs.com/package/kaelum)
-[![Build Status](https://github.com/MatheusCampagnolo/kaelum/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/MatheusCampagnolo/kaelum/actions)
-[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
-[![Docs](https://img.shields.io/badge/docs-online-blue)](https://matheuscampagnolo.github.io/kaelum/)
-
-**Kaelum.js** — Minimalist Node.js framework to simplify creation of web pages and REST APIs.  
-Designed for students and developers who want a fast, opinionated project scaffold and a small, friendly API that encapsulates common Express.js boilerplate.
-
-👉 [**Read the full documentation here**](https://matheuscampagnolo.github.io/kaelum/)
-
-**If Kaelum helps you, consider supporting its development:**
-
-<a href='https://ko-fi.com/Z8Z51NK4KT' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
-
-</div>
-
-## 🚀 Quick start
-
-Create a new project (interactive):
-
-```bash
-npx kaelum create
-```
-
-Or create non-interactively (project name + template):
-
-```bash
-npx kaelum create my-app --template web
-# or
-npx kaelum create my-api --template api
-```
-
-Then:
-
-```bash
-cd my-app
-npm install
-npm start
-```
-
-> No need to install Kaelum globally — `npx` handles execution.
-
----
-
-## 📦 What Kaelum provides
-
-- CLI that scaffolds a ready-to-run project (Web or API template) using an opinionated **MVC** structure.
-- Thin abstraction layer over **Express.js** that:
-
-  - automates JSON / URL-encoded parsing by default,
-  - automatically configures common security middlewares via `setConfig` (CORS, Helmet),
-  - exposes a small, easy-to-learn API for routes, middleware and configuration.
-
-- Small set of helpers for common tasks: `start`, `addRoute`, `apiRoute`, `setConfig`, `static`, `redirect`, `healthCheck`, `useErrorHandler`, and more.
-
-Kaelum aims to reduce the initial setup burden while keeping flexibility for advanced users.
-
----
-
-## 📁 Template structures
-
-### Web template (`--template web`)
-
-```
-my-web-app/
-├── public/          # Static files (CSS, JS)
-│   └── style.css
-├── views/           # HTML templates
-│   └── index.html
-├── controllers/     # Controller logic (MVC)
-│   └── .gitkeep
-├── middlewares/     # Custom middlewares
-│   └── logger.js
-├── routes.js        # Route definitions (example uses Kaelum helpers)
-├── app.js           # Server initialization (uses Kaelum API)
-└── package.json
-```
-
-### API template (`--template api`)
-
-```
-my-api-app/
-├── controllers/
-│   └── usersController.js
-├── middlewares/
-│   └── authMock.js
-├── routes.js
-├── app.js
-└── package.json
-```
-
----
-
-## 🧩 Core API
-
-> Kaelum exposes a factory — use `require('kaelum')` and call it to get an app instance:
-
-```js
-const kaelum = require("kaelum");
-const app = kaelum();
-```
-
-### `app.setConfig(options)`
-
-Enable/disable common features:
-
-```js
-app.setConfig({
-  cors: true, // apply CORS (requires cors package in dependencies)
-  helmet: true, // apply Helmet
-  static: "public", // serve static files from "public"
-  bodyParser: true, // default: enabled (JSON + urlencoded)
-  logs: false, // enable request logging via morgan (if installed)
-  port: 3000, // prefered port (used when calling app.start() without port)
-});
-```
-
-- `setConfig` persists settings to the Kaelum config and will install/remove Kaelum-managed middlewares.
-- Kaelum enables JSON/urlencoded parsing by default so beginners won't forget to parse request bodies.
-
----
-
-### `app.start(port, callback)`
-
-Starts the HTTP server. If `port` is omitted, Kaelum reads `port` from `setConfig` or falls back to `3000`.
-
-```js
-app.start(3000, () => console.log("Running"));
-```
-
----
-
-### `app.addRoute(path, handlers)` and `app.apiRoute(resource, handlers)`
-
-Register routes easily:
-
-```js
-app.addRoute("/home", {
-  get: (req, res) => res.send("Welcome!"),
-  post: (req, res) => res.send("Posted!"),
-});
-
-// apiRoute builds RESTy resources with nested subpaths:
-app.apiRoute("users", {
-  get: listUsers,
-  post: createUser,
-  "/:id": {
-    get: getUserById,
-    put: updateUser,
-    delete: deleteUser,
-  },
-});
-```
-
-`addRoute` also accepts a single handler function (assumed `GET`).
-
----
-
-### `app.setMiddleware(...)`
-
-Flexible helper to register middleware(s):
-
-```js
-// single middleware
-app.setMiddleware(require("helmet")());
-
-// array of middlewares
-app.setMiddleware([mw1, mw2]);
-
-// mount middleware on a path
-app.setMiddleware("/admin", authMiddleware);
-```
-
----
-
-### `app.redirect(from, to, status)`
-
-Register a redirect route:
-
-```js
-app.redirect("/old-url", "/new-url", 302);
-```
-
----
-
-### `app.healthCheck(path = '/health')`
-
-Adds a health endpoint returning `{ status: 'OK', uptime, timestamp, pid }`.
-
----
-
-### `app.useErrorHandler(options)`
-
-Attach Kaelum's default JSON error handler:
-
-```js
-app.useErrorHandler({ exposeStack: false });
-```
-
-It will return standardized JSON for errors and log server-side errors (5xx) to `console.error`.
-
----
-
-## 🔧 Local development & contributing
-
-```bash
-git clone https://github.com/MatheusCampagnolo/kaelum.git
-cd kaelum
-npm install
-npm link
-```
-
-Now you can test the CLI locally:
-
-```bash
-npx kaelum create my-test --template web
-```
-
----
-
-## 📝 Why Kaelum?
-
-- Reduces repetitive boilerplate required to start Node/Express web projects.
-- Opinionated scaffolding (MVC) helps beginners adopt better structure.
-- Keeps a small API surface: easy to teach and document.
-- Extensible — `setConfig` and middleware helpers allow adding features without exposing Express internals.
-
----
-
-## ✅ Current status
-
-> Kaelum is under active development.
-> CLI scaffolds web and API templates, and the framework includes the MVP helpers (`start`, `addRoute`, `apiRoute`, `setConfig`, `static`, `redirect`, `healthCheck`, `useErrorHandler`) and security toggles for `cors` and `helmet`.
-
----
-
-## 📚 Links
-
-- [GitHub](https://github.com/MatheusCampagnolo/kaelum)
-- [npm](https://www.npmjs.com/package/kaelum)
-- [Documentation](https://matheuscampagnolo.github.io/kaelum/)
-
----
-
-## 🧾 License
-
-MIT — see [LICENSE](LICENSE).
-
----
-
-## ✍️ Notes for maintainers
-
-- Templates use `commonjs` (`require` / `module.exports`).
-- Update template dependencies to reference the correct Kaelum version when releasing new npm versions.
+<div align="center">
+
+<h1>Kaelum</h1>
+
+[![npm version](https://img.shields.io/npm/v/kaelum)](https://www.npmjs.com/package/kaelum)
+[![Build Status](https://github.com/MatheusCampagnolo/kaelum/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/MatheusCampagnolo/kaelum/actions)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-online-blue)](https://matheuscampagnolo.github.io/kaelum/)
+
+**Kaelum.js** — Minimalist Node.js framework to simplify creation of web pages and REST APIs.  
+Designed for students and developers who want a fast, opinionated project scaffold and a small, friendly API that encapsulates common Express.js boilerplate.
+
+👉 [**Read the full documentation here**](https://matheuscampagnolo.github.io/kaelum/)
+
+**If Kaelum helps you, consider supporting its development:**
+
+<a href='https://ko-fi.com/Z8Z51NK4KT' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
+
+</div>
+
+## 🚀 Quick start
+
+Create a new project (interactive):
+
+```bash
+npx kaelum create
+```
+
+Or create non-interactively (project name + template):
+
+```bash
+npx kaelum create my-app --template web
+# or
+npx kaelum create my-api --template api
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm start
+```
+
+> No need to install Kaelum globally — `npx` handles execution.
+
+---
+
+## 📦 What Kaelum provides
+
+- CLI that scaffolds a ready-to-run project (Web or API template) using an opinionated **MVC** structure.
+- Thin abstraction layer over **Express.js** that:
+
+  - automates JSON / URL-encoded parsing by default,
+  - automatically loads environment variables from `.env`,
+  - automatically configures common security middlewares via `setConfig` (CORS, Helmet),
+  - simplifies view engine setup via `setConfig`,
+  - exposes a small, easy-to-learn API for routes, middleware and configuration.
+
+- Small set of helpers for common tasks: `start`, `addRoute`, `apiRoute`, `setConfig`, `static`, `redirect`, `healthCheck`, `useErrorHandler`, and more.
+
+Kaelum aims to reduce the initial setup burden while keeping flexibility for advanced users.
+
+---
+
+## 📁 Template structures
+
+### Web template (`--template web`)
+
+```
+my-web-app/
+├── public/          # Static files (CSS, JS)
+│   └── style.css
+├── views/           # HTML templates
+│   └── index.html
+├── controllers/     # Controller logic (MVC)
+│   └── .gitkeep
+├── middlewares/     # Custom middlewares
+│   └── logger.js
+├── routes.js        # Route definitions (example uses Kaelum helpers)
+├── app.js           # Server initialization (uses Kaelum API)
+└── package.json
+```
+
+### API template (`--template api`)
+
+```
+my-api-app/
+├── controllers/
+│   └── usersController.js
+├── middlewares/
+│   └── authMock.js
+├── routes.js
+├── app.js
+└── package.json
+```
+
+---
+
+## 🧩 Core API
+
+> Kaelum exposes a factory — use `require('kaelum')` and call it to get an app instance:
+
+```js
+const kaelum = require("kaelum");
+const app = kaelum();
+```
+
+### `app.setConfig(options)`
+
+Enable/disable common features:
+
+```js
+app.setConfig({
+  cors: true, // apply CORS (requires cors package in dependencies)
+  helmet: true, // apply Helmet
+  static: "public", // serve static files from "public"
+  bodyParser: true, // default: enabled (JSON + urlencoded)
+  logs: false, // enable request logging via morgan (if installed)
+  port: 3000, // prefered port (used when calling app.start() without port)
+  views: { engine: 'ejs', path: './views' } // configure view engine
+});
+```
+
+- `setConfig` persists settings to the Kaelum config and will install/remove Kaelum-managed middlewares.
+- Kaelum enables JSON/urlencoded parsing by default so beginners won't forget to parse request bodies.
+
+---
+
+### `app.start(port, callback)`
+
+Starts the HTTP server. If `port` is omitted, Kaelum reads `port` from `setConfig` or falls back to `3000`.
+
+```js
+app.start(3000, () => console.log("Running"));
+```
+
+---
+
+### `app.addRoute(path, handlers)` and `app.apiRoute(resource, handlers)`
+
+Register routes easily:
+
+```js
+app.addRoute("/home", {
+  get: (req, res) => res.send("Welcome!"),
+  post: (req, res) => res.send("Posted!"),
+});
+
+// apiRoute builds RESTy resources with nested subpaths:
+app.apiRoute("users", {
+  get: listUsers,
+  post: createUser,
+  "/:id": {
+    get: getUserById,
+    put: updateUser,
+    delete: deleteUser,
+  },
+});
+```
+
+`addRoute` also accepts a single handler function (assumed `GET`).
+
+---
+
+### `app.setMiddleware(...)`
+
+Flexible helper to register middleware(s):
+
+```js
+// single middleware
+app.setMiddleware(require("helmet")());
+
+// array of middlewares
+app.setMiddleware([mw1, mw2]);
+
+// mount middleware on a path
+app.setMiddleware("/admin", authMiddleware);
+```
+
+---
+
+### `app.redirect(from, to, status)`
+
+Register a redirect route:
+
+```js
+app.redirect("/old-url", "/new-url", 302);
+```
+
+---
+
+### `app.healthCheck(path = '/health')`
+
+Adds a health endpoint returning `{ status: 'OK', uptime, timestamp, pid }`.
+
+---
+
+### `app.useErrorHandler(options)`
+
+Attach Kaelum's default JSON error handler:
+
+```js
+app.useErrorHandler({ exposeStack: false });
+```
+
+It will return standardized JSON for errors and log server-side errors (5xx) to `console.error`.
+
+---
+
+## 🔧 Local development & contributing
+
+```bash
+git clone https://github.com/MatheusCampagnolo/kaelum.git
+cd kaelum
+npm install
+npm link
+```
+
+Now you can test the CLI locally:
+
+```bash
+npx kaelum create my-test --template web
+```
+
+---
+
+## 📝 Why Kaelum?
+
+- Reduces repetitive boilerplate required to start Node/Express web projects.
+- Opinionated scaffolding (MVC) helps beginners adopt better structure.
+- Keeps a small API surface: easy to teach and document.
+- Extensible — `setConfig` and middleware helpers allow adding features without exposing Express internals.
+
+---
+
+## ✅ Current status
+
+> Kaelum is under active development.
+> CLI scaffolds web and API templates, and the framework includes the MVP helpers (`start`, `addRoute`, `apiRoute`, `setConfig`, `static`, `redirect`, `healthCheck`, `useErrorHandler`) and security toggles for `cors` and `helmet`.
+
+---
+
+## 📚 Links
+
+- [GitHub](https://github.com/MatheusCampagnolo/kaelum)
+- [npm](https://www.npmjs.com/package/kaelum)
+- [Documentation](https://matheuscampagnolo.github.io/kaelum/)
+
+---
+
+## 🧾 License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## ✍️ Notes for maintainers
+
+- Templates use `commonjs` (`require` / `module.exports`).
+- Update template dependencies to reference the correct Kaelum version when releasing new npm versions.

package/cli/templates/api/package.json

@@ -4,7 +4,7 @@
   "description": "Exemplo de app API gerado pela CLI Kaelum",
   "scripts": {
     "start": "node app.js",
-    "dev": "nodemon app.js"
+    "dev": "node --watch app.js"
   },
   "keywords": [
     "kaelum",
@@ -13,12 +13,10 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "kaelum": "^1.3.0",
+    "kaelum": "^1.4.0",
     "cors": "^2.8.5",
     "helmet": "^6.0.0",
     "morgan": "^1.10.0"
   },
-  "devDependencies": {
-    "nodemon": "^2.0.22"
-  }
+  "devDependencies": {}
 }

package/cli/templates/web/package.json

@@ -4,7 +4,7 @@
   "description": "Exemplo de app gerado pela CLI Kaelum (web template)",
   "scripts": {
     "start": "node app.js",
-    "dev": "nodemon app.js"
+    "dev": "node --watch app.js"
   },
   "keywords": [
     "kaelum",
@@ -13,11 +13,9 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "kaelum": "^1.3.0",
+    "kaelum": "^1.4.0",
     "cors": "^2.8.5",
     "helmet": "^6.0.0"
   },
-  "devDependencies": {
-    "nodemon": "^2.0.22"
-  }
+  "devDependencies": {}
 }

package/core/setConfig.js

@@ -1,255 +1,271 @@
-// core/setConfig.js
-// Kaelum centralized configuration helper.
-// - Supports toggling CORS, Helmet, static folder, Morgan logs, bodyParser, and port.
-// - Persists merged config to app locals (app.set("kaelum:config", ...)).
-// - Keeps references to Kaelum-installed middleware so toggles (false) remove them.
-
-const path = require("path");
-
-function tryRequire(name) {
-  try {
-    return require(name);
-  } catch (e) {
-    return null;
-  }
-}
-
-/**
- * Merge new options into existing stored config
- * @param {Object} app
- * @param {Object} options
- */
-function persistConfig(app, options = {}) {
-  const prev = app.locals.kaelumConfig || {};
-  const merged = Object.assign({}, prev, options);
-  app.locals.kaelumConfig = merged;
-  app.set("kaelum:config", merged);
-  return merged;
-}
-
-/**
- * Remove a middleware function reference from express stack
- * @param {Object} app
- * @param {Function} fn
- */
-function removeMiddlewareByFn(app, fn) {
-  if (!app || !app._router || !Array.isArray(app._router.stack)) return;
-  app._router.stack = app._router.stack.filter((layer) => layer.handle !== fn);
-}
-
-/**
- * Remove static middleware previously installed by Kaelum (if any)
- * @param {Object} app
- */
-function removeKaelumStatic(app) {
-  const prev = app.locals && app.locals._kaelum_static;
-  if (prev) {
-    removeMiddlewareByFn(app, prev);
-    app.locals._kaelum_static = null;
-  }
-}
-
-/**
- * Remove body parsers previously installed by Kaelum
- * @param {Object} app
- */
-function removeKaelumBodyParsers(app) {
-  const arr = app.locals && app.locals._kaelum_bodyparsers;
-  if (Array.isArray(arr)) {
-    arr.forEach((fn) => removeMiddlewareByFn(app, fn));
-    app.locals._kaelum_bodyparsers = [];
-  }
-}
-
-/**
- * Remove morgan logger if previously set
- * @param {Object} app
- */
-function removeKaelumLogger(app) {
-  const prev = app.locals && app.locals._kaelum_logger;
-  if (prev) {
-    removeMiddlewareByFn(app, prev);
-    app.locals._kaelum_logger = null;
-  }
-}
-
-/**
- * Remove Kaelum-installed CORS middleware (if any)
- * @param {Object} app
- */
-function removeKaelumCors(app) {
-  const prev = app.locals && app.locals._kaelum_cors;
-  if (prev) {
-    removeMiddlewareByFn(app, prev);
-    app.locals._kaelum_cors = null;
-  }
-}
-
-/**
- * Remove Kaelum-installed Helmet middleware (if any)
- * @param {Object} app
- */
-function removeKaelumHelmet(app) {
-  const prev = app.locals && app.locals._kaelum_helmet;
-  if (prev) {
-    removeMiddlewareByFn(app, prev);
-    app.locals._kaelum_helmet = null;
-  }
-}
-
-/**
- * Apply configuration options to the app
- * @param {Object} app - express app instance
- * @param {Object} options - supported keys: cors, helmet, static, logs, port, bodyParser
- */
-function setConfig(app, options = {}) {
-  if (!app) throw new Error("setConfig requires an app instance");
-
-  // persist/merge config
-  const cfg = persistConfig(app, options);
-
-  // --- CORS ---
-  if (options.hasOwnProperty("cors")) {
-    if (options.cors) {
-      const cors = tryRequire("cors");
-      const corsOpts = options.cors === true ? {} : options.cors;
-      if (!cors) {
-        console.warn(
-          "Kaelum: cors package not installed. Skipping CORS setup."
-        );
-      } else {
-        // remove previous Kaelum-installed cors if exists
-        removeKaelumCors(app);
-
-        // create middleware function and store reference so it can be removed later
-        const corsFn = cors(corsOpts);
-        app.locals._kaelum_cors = corsFn;
-        app.use(corsFn);
-        console.log("🛡️  CORS activated.");
-      }
-    } else {
-      // disable Kaelum-installed CORS middleware if present
-      removeKaelumCors(app);
-      console.log("🛡️  CORS disabled (Kaelum-managed).");
-    }
-  }
-
-  // --- Helmet ---
-  if (options.hasOwnProperty("helmet")) {
-    if (options.helmet) {
-      const helmet = tryRequire("helmet");
-      const helmetOpts = options.helmet === true ? {} : options.helmet;
-      if (!helmet) {
-        console.warn(
-          "Kaelum: helmet package not installed. Skipping Helmet setup."
-        );
-      } else {
-        // remove previous Kaelum-installed helmet if exists
-        removeKaelumHelmet(app);
-
-        const helmetFn = helmet(helmetOpts);
-        app.locals._kaelum_helmet = helmetFn;
-        app.use(helmetFn);
-        console.log("🛡️  Helmet activated.");
-      }
-    } else {
-      // disable Kaelum-installed Helmet middleware if present
-      removeKaelumHelmet(app);
-      console.log("🛡️  Helmet disabled (Kaelum-managed).");
-    }
-  }
-
-  // --- Static folder handling ---
-  if (options.hasOwnProperty("static")) {
-    // remove previous Kaelum static
-    removeKaelumStatic(app);
-
-    if (options.static) {
-      const expressStatic =
-        tryRequire("express").static || require("express").static;
-      // resolve to absolute path relative to project root if necessary
-      const dir =
-        typeof options.static === "string"
-          ? path.resolve(process.cwd(), options.static)
-          : path.join(process.cwd(), "public");
-      const staticFn = expressStatic(dir);
-      app.locals._kaelum_static = staticFn;
-      app.use(staticFn);
-      console.log(`📁 Static files served from ${dir}`);
-    } else {
-      // static === false -> nothing to add (static removed)
-      console.log("📁 Static serving disabled.");
-    }
-  }
-
-  // --- Body parser toggle ---
-  if (options.hasOwnProperty("bodyParser")) {
-    if (options.bodyParser === false) {
-      // remove Kaelum-installed body parsers
-      removeKaelumBodyParsers(app);
-      console.log("📦 Body parsers disabled.");
-    } else {
-      // ensure body parsers are installed (if not present)
-      if (
-        !app.locals._kaelum_bodyparsers ||
-        app.locals._kaelum_bodyparsers.length === 0
-      ) {
-        const jsonParser = tryRequire("express").json();
-        const urlencodedParser = tryRequire("express").urlencoded({
-          extended: true,
-        });
-        app.locals._kaelum_bodyparsers = [jsonParser, urlencodedParser];
-        app.use(jsonParser);
-        app.use(urlencodedParser);
-        console.log("📦 Body parsers enabled (JSON + URL-encoded).");
-      }
-    }
-  }
-
-  // --- Logs (morgan) ---
-  if (options.hasOwnProperty("logs")) {
-    // remove previous logger first
-    removeKaelumLogger(app);
-
-    if (options.logs) {
-      const morgan = tryRequire("morgan");
-      if (!morgan) {
-        console.warn("Kaelum: morgan package not installed. Skipping logs.");
-      } else {
-        // simple dev format by default; could be configured
-        const logger = morgan("dev");
-        app.locals._kaelum_logger = logger;
-        app.use(logger);
-        console.log("📊 Request logging enabled (morgan).");
-      }
-    } else {
-      console.log("📊 Request logging disabled.");
-    }
-  }
-
-  // --- Port persisted in config (start will read it) ---
-  if (options.hasOwnProperty("port")) {
-    const p = options.port;
-    if (p === false || p === null) {
-      // unset
-      const merged = Object.assign({}, app.locals.kaelumConfig);
-      delete merged.port;
-      app.locals.kaelumConfig = merged;
-      app.set("kaelum:config", merged);
-      console.log("🔌 Port preference cleared from Kaelum config.");
-    } else if (typeof p === "number" || typeof p === "string") {
-      // persist port as number if possible
-      const asNum = Number(p);
-      app.locals.kaelumConfig.port = Number.isNaN(asNum) ? p : asNum;
-      app.set("kaelum:config", app.locals.kaelumConfig);
-      console.log(
-        `🔌 Port set to ${app.locals.kaelumConfig.port} in Kaelum config.`
-      );
-    }
-  }
-
-  // Return the full merged config for convenience
-  return app.locals.kaelumConfig;
-}
-
+// core/setConfig.js
+// Kaelum centralized configuration helper.
+// - Supports toggling CORS, Helmet, static folder, Morgan logs, bodyParser, and port.
+// - Persists merged config to app locals (app.set("kaelum:config", ...)).
+// - Keeps references to Kaelum-installed middleware so toggles (false) remove them.
+
+const path = require("path");
+
+function tryRequire(name) {
+  try {
+    return require(name);
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * Merge new options into existing stored config
+ * @param {Object} app
+ * @param {Object} options
+ */
+function persistConfig(app, options = {}) {
+  const prev = app.locals.kaelumConfig || {};
+  const merged = Object.assign({}, prev, options);
+  app.locals.kaelumConfig = merged;
+  app.set("kaelum:config", merged);
+  return merged;
+}
+
+/**
+ * Remove a middleware function reference from express stack
+ * @param {Object} app
+ * @param {Function} fn
+ */
+function removeMiddlewareByFn(app, fn) {
+  if (!app || !app._router || !Array.isArray(app._router.stack)) return;
+  app._router.stack = app._router.stack.filter((layer) => layer.handle !== fn);
+}
+
+/**
+ * Remove static middleware previously installed by Kaelum (if any)
+ * @param {Object} app
+ */
+function removeKaelumStatic(app) {
+  const prev = app.locals && app.locals._kaelum_static;
+  if (prev) {
+    removeMiddlewareByFn(app, prev);
+    app.locals._kaelum_static = null;
+  }
+}
+
+/**
+ * Remove body parsers previously installed by Kaelum
+ * @param {Object} app
+ */
+function removeKaelumBodyParsers(app) {
+  const arr = app.locals && app.locals._kaelum_bodyparsers;
+  if (Array.isArray(arr)) {
+    arr.forEach((fn) => removeMiddlewareByFn(app, fn));
+    app.locals._kaelum_bodyparsers = [];
+  }
+}
+
+/**
+ * Remove morgan logger if previously set
+ * @param {Object} app
+ */
+function removeKaelumLogger(app) {
+  const prev = app.locals && app.locals._kaelum_logger;
+  if (prev) {
+    removeMiddlewareByFn(app, prev);
+    app.locals._kaelum_logger = null;
+  }
+}
+
+/**
+ * Remove Kaelum-installed CORS middleware (if any)
+ * @param {Object} app
+ */
+function removeKaelumCors(app) {
+  const prev = app.locals && app.locals._kaelum_cors;
+  if (prev) {
+    removeMiddlewareByFn(app, prev);
+    app.locals._kaelum_cors = null;
+  }
+}
+
+/**
+ * Remove Kaelum-installed Helmet middleware (if any)
+ * @param {Object} app
+ */
+function removeKaelumHelmet(app) {
+  const prev = app.locals && app.locals._kaelum_helmet;
+  if (prev) {
+    removeMiddlewareByFn(app, prev);
+    app.locals._kaelum_helmet = null;
+  }
+}
+
+/**
+ * Apply configuration options to the app
+ * @param {Object} app - express app instance
+ * @param {Object} options - supported keys: cors, helmet, static, logs, port, bodyParser
+ */
+function setConfig(app, options = {}) {
+  if (!app) throw new Error("setConfig requires an app instance");
+
+  // persist/merge config
+  const cfg = persistConfig(app, options);
+
+  // --- CORS ---
+  if (options.hasOwnProperty("cors")) {
+    if (options.cors) {
+      const cors = tryRequire("cors");
+      const corsOpts = options.cors === true ? {} : options.cors;
+      if (!cors) {
+        console.warn(
+          "Kaelum: cors package not installed. Skipping CORS setup."
+        );
+      } else {
+        // remove previous Kaelum-installed cors if exists
+        removeKaelumCors(app);
+
+        // create middleware function and store reference so it can be removed later
+        const corsFn = cors(corsOpts);
+        app.locals._kaelum_cors = corsFn;
+        app.use(corsFn);
+        console.log("🛡️  CORS activated.");
+      }
+    } else {
+      // disable Kaelum-installed CORS middleware if present
+      removeKaelumCors(app);
+      console.log("🛡️  CORS disabled (Kaelum-managed).");
+    }
+  }
+
+  // --- Helmet ---
+  if (options.hasOwnProperty("helmet")) {
+    if (options.helmet) {
+      const helmet = tryRequire("helmet");
+      const helmetOpts = options.helmet === true ? {} : options.helmet;
+      if (!helmet) {
+        console.warn(
+          "Kaelum: helmet package not installed. Skipping Helmet setup."
+        );
+      } else {
+        // remove previous Kaelum-installed helmet if exists
+        removeKaelumHelmet(app);
+
+        const helmetFn = helmet(helmetOpts);
+        app.locals._kaelum_helmet = helmetFn;
+        app.use(helmetFn);
+        console.log("🛡️  Helmet activated.");
+      }
+    } else {
+      // disable Kaelum-installed Helmet middleware if present
+      removeKaelumHelmet(app);
+      console.log("🛡️  Helmet disabled (Kaelum-managed).");
+    }
+  }
+
+  // --- Static folder handling ---
+  if (options.hasOwnProperty("static")) {
+    // remove previous Kaelum static
+    removeKaelumStatic(app);
+
+    if (options.static) {
+      const expressStatic =
+        tryRequire("express").static || require("express").static;
+      // resolve to absolute path relative to project root if necessary
+      const dir =
+        typeof options.static === "string"
+          ? path.resolve(process.cwd(), options.static)
+          : path.join(process.cwd(), "public");
+      const staticFn = expressStatic(dir);
+      app.locals._kaelum_static = staticFn;
+      app.use(staticFn);
+      console.log(`📁 Static files served from ${dir}`);
+    } else {
+      // static === false -> nothing to add (static removed)
+      console.log("📁 Static serving disabled.");
+    }
+  }
+
+  // --- Body parser toggle ---
+  if (options.hasOwnProperty("bodyParser")) {
+    if (options.bodyParser === false) {
+      // remove Kaelum-installed body parsers
+      removeKaelumBodyParsers(app);
+      console.log("📦 Body parsers disabled.");
+    } else {
+      // ensure body parsers are installed (if not present)
+      if (
+        !app.locals._kaelum_bodyparsers ||
+        app.locals._kaelum_bodyparsers.length === 0
+      ) {
+        const jsonParser = tryRequire("express").json();
+        const urlencodedParser = tryRequire("express").urlencoded({
+          extended: true,
+        });
+        app.locals._kaelum_bodyparsers = [jsonParser, urlencodedParser];
+        app.use(jsonParser);
+        app.use(urlencodedParser);
+        console.log("📦 Body parsers enabled (JSON + URL-encoded).");
+      }
+    }
+  }
+
+  // --- Logs (morgan) ---
+  if (options.hasOwnProperty("logs")) {
+    // remove previous logger first
+    removeKaelumLogger(app);
+
+    if (options.logs) {
+      const morgan = tryRequire("morgan");
+      if (!morgan) {
+        console.warn("Kaelum: morgan package not installed. Skipping logs.");
+      } else {
+        // simple dev format by default; could be configured
+        const logger = morgan("dev");
+        app.locals._kaelum_logger = logger;
+        app.use(logger);
+        console.log("📊 Request logging enabled (morgan).");
+      }
+    } else {
+      console.log("📊 Request logging disabled.");
+    }
+  }
+
+  // --- Port persisted in config (start will read it) ---
+  if (options.hasOwnProperty("port")) {
+    const p = options.port;
+    if (p === false || p === null) {
+      // unset
+      const merged = Object.assign({}, app.locals.kaelumConfig);
+      delete merged.port;
+      app.locals.kaelumConfig = merged;
+      app.set("kaelum:config", merged);
+      console.log("🔌 Port preference cleared from Kaelum config.");
+    } else if (typeof p === "number" || typeof p === "string") {
+      // persist port as number if possible
+      const asNum = Number(p);
+      app.locals.kaelumConfig.port = Number.isNaN(asNum) ? p : asNum;
+      app.set("kaelum:config", app.locals.kaelumConfig);
+      console.log(
+        `🔌 Port set to ${app.locals.kaelumConfig.port} in Kaelum config.`
+      );
+    }
+  }
+
+  // --- View Engine ---
+  if (options.hasOwnProperty("views")) {
+    const v = options.views;
+    if (v && typeof v === "object") {
+      if (v.engine) {
+        app.set("view engine", v.engine);
+        console.log(`🎨 View engine set to: ${v.engine}`);
+      }
+      if (v.path) {
+        const p = path.resolve(process.cwd(), v.path);
+        app.set("views", p);
+        console.log(`🎨 Views directory set to: ${p}`);
+      }
+    }
+  }
+
+  // Return the full merged config for convenience
+  return app.locals.kaelumConfig;
+}
+
 module.exports = setConfig;

package/createApp.js

@@ -6,6 +6,7 @@
 // - exposes existing core helpers (start, addRoute, setMiddleware, apiRoute)
 // - exposes error handler helper app.useErrorHandler()
 
+require("dotenv").config();
 const express = require("express");
 const path = require("path");
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaelum",
-  "version": "1.3.6",
+  "version": "1.4.0",
   "description": "A minimalist Node.js framework for building web pages and APIs with simplicity and speed.",
   "main": "index.js",
   "exports": {
@@ -27,6 +27,7 @@
   "license": "MIT",
   "dependencies": {
     "cors": "^2.8.5",
+    "dotenv": "^17.2.3",
     "ejs": "^3.1.10",
     "express": "^4.18.2",
     "fs-extra": "^11.3.0",