📚 Documentation · 🐛 Report Bug · 💡 Request Feature

Why Kaelum?

Without Kaelum (raw Express)

const express = require("express");
const cors = require("cors");
const helmet = require("helmet");
const morgan = require("morgan");
const path = require("path");

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cors());
app.use(helmet());
app.use(morgan("dev"));
app.use(express.static(path.join(__dirname, "public")));
app.set("view engine", "ejs");

app.get("/users", listUsers);
app.post("/users", createUser);
app.get("/users/:id", getUser);

app.listen(3000);

With Kaelum ✨

const kaelum = require("kaelum");
const app = kaelum();

app.setConfig({
  cors: true,
  helmet: true,
  logs: "dev",
  port: 3000,
});

app.apiRoute("users", {
  get: listUsers,
  post: createUser,
  "/:id": { get: getUser },
});

app.start();

Less boilerplate. Same Express power. Better DX.

⚡ Quick Start

# Scaffold a new project
npx kaelum create my-app --template web

# Or an API project
npx kaelum create my-api --template api

# Run it
cd my-app && npm install && npm start

No global install needed — npx handles everything.

✨ Features

| Feature | Description | |---------|-------------| | 🚀 Zero-Config Start | JSON parsing, static files, EJS views — all pre-configured | | 🌳 Tree Routing | Recursive nested routes with addRoute and apiRoute | | 🔒 Security Built-in | One-toggle CORS, Helmet, and XSS protection | | 🛠️ CLI Scaffolding | npx kaelum create with Web and API templates | | 📦 Dual Module | Works with both require() and import | | 🏥 Health Checks | Built-in /health endpoint with readiness probes | | ⚡ Middleware Manager | Track, add, and remove middleware programmatically | | 🔄 Redirects | Declarative redirect maps with single, array, or object syntax | | 🛡️ Error Handler | Standardized JSON/HTML error responses with hooks |

📦 Installation

npm install kaelum

// CommonJS
const kaelum = require("kaelum");
const app = kaelum();

// ESM
import kaelum from "kaelum";
const app = kaelum();

🧩 API Overview

app.setConfig(options)

app.setConfig({
  cors: true,           // enable CORS
  helmet: true,         // HTTP security headers
  static: "public",     // serve static files
  logs: "dev",          // morgan request logging
  bodyParser: true,     // JSON + urlencoded (default: on)
  port: 3000,           // preferred port
  views: { engine: "ejs", path: "./views" },
});

app.addRoute(path, handlers)

app.addRoute("/dashboard", {
  get: (req, res) => res.render("dashboard"),
  post: handleForm,
  "/settings": {
    get: showSettings,
    put: updateSettings,
  },
});

app.apiRoute(resource, handlers)

app.apiRoute("products", {
  get: listAll,
  post: create,
  "/:id": {
    get: getById,
    put: update,
    delete: remove,
    "/reviews": {
      get: getReviews,   // GET /products/:id/reviews
      post: addReview,
    },
  },
});

Other Helpers

app.start(3000);                              // start server
app.setMiddleware("/admin", authMiddleware);   // scoped middleware
app.redirect("/old", "/new", 301);            // redirects
app.healthCheck("/health");                   // health endpoint
app.useErrorHandler({ exposeStack: false });  // error handling

📁 Project Templates

Web Template

my-web-app/
├── public/            # Static assets
├── views/             # EJS templates
├── controllers/       # Route logic (MVC)
├── middlewares/        # Custom middleware
├── routes.js          # Route definitions
├── app.js             # Entry point
└── package.json

API Template

my-api/
├── controllers/       # Business logic
├── middlewares/        # Auth, validation
├── routes.js          # API routes
├── app.js             # Entry point
└── package.json

🧪 Testing

npm test        # run all tests
npm run lint    # check code with ESLint
npm run format  # format code with Prettier

🤝 Contributing

We welcome contributions! Please read our Contributing Guide before submitting a PR.

See also: Code of Conduct · Security Policy

🌐 Ecosystem

| Package | Description | |---------|-------------| | kaelum | Core framework | | kaelumjs/docs | Documentation site | | kaelumjs/.github | Shared community standards |

☕ Support

If Kaelum helps you, consider supporting its development:

📝 License

MIT — see LICENSE.