ht-web-framework

A modular, extensible Express.js-based web server framework for Node.js, designed for rapid development of web applications with flexible routing, templating, and security features.

Features

• Express.js core with easy configuration
• Automatic route generation from a pagemap (JSONC)
• Multiple template engine support: Mustache, EJS, Handlebars
• Static file serving (customizable)
• Security headers and real IP detection (supports proxies and Cloudflare)
• Custom error handling with verbose/debug options
• Flexible middleware and script hooks for routes
• Built-in logging (console and file)

---

Installation

Add to your project (as a dependency):

npm install ht-web-framework --registry https://repo.ht-dev.de

Or, if using as a local dependency (see package.json):

npm install /path/to/ht-web-framework

"dependencies": {
  "ht-web-framework": "file:/path/to/ht-web-framework"
}

---

Usage

1. Import and Initialize

import { Server } from 'ht-web-framework';

// Load your config and pagemap (JSONC or JSON)
const config = {
  port: 8080,
  views: 'views',
  static: 'public',
  logging: true,
  logFile: 'logs/server.log',
  trustedProxies: ['127.0.0.1'],
  verboseErrors: true,
  // ...other options
};

const pagemap = `
{
  // Example pagemap structure
  "settings": {
    "title": "My App",
    "scripts": []
  },
  "navpages": [
    { "url": "/", "title": "Home" }
  ],
  "paths": {
    "get": {
      "/": { 
        "file": "index",
        "settings": {
            "type": "mustache"
        }
      }
    }
  }
}
`;

const server = new Server(config, pagemap);

2. Generate Routes

server.generateRoutes();

3. Start the Server

server.start(8080); // or omit to use config.port

---

Configuration

• config: Main server configuration object.

  • port: Port to listen on.
  • views: Directory for view templates.
  • static: Directory for static files.
  • logging: Enable/disable file logging.
  • logFile: Path to log file.
  • trustedProxies: Array of trusted proxy IPs.
  • verboseErrors: Show detailed error messages.
  • embedSite: (Optional) Allow embedding from a specific site via CORS.

• pagemap: JSON or JSONC string/object describing navigation, routes, and settings.

  • settings: Global settings (title, scripts, etc).
  • navpages: Array of navigation pages.
  • paths: Object mapping HTTP methods to route definitions.

---

Template Engines

• Mustache (.mustache)
• EJS (.ejs)
• Handlebars (.handlebars)

Set the type property in your pagemap route to select the engine.

Any other static file can also be served with the type static, file or image.

---

Static Files

• /static/builtin serves built-in assets.
• /static serves your configured static directory.

---

Error Handling

• Custom error pages for HTML and JSON requests.
• Verbose stack traces if verboseErrors is enabled.

---

Security

• Sets strict security headers by default.
• Real IP detection supports proxies and Cloudflare.
• Referrer, feature, and frame policies included.

---

Example

import { Server } from 'ht-web-framework';

const config = {
  port: 3000,
  views: 'views',
  static: 'public',
  logging: false,
  trustedProxies: ['127.0.0.1'],
  verboseErrors: true,
};

const pagemap = `
{
  "settings": { "title": "Demo", "scripts": [] },
  "navpages": [{ "url": "/", "title": "Home" }],
  "paths": {
    "get": {
      "/": { 
        "file": "index",
        "settings": {
            "type": "mustache"
        }
      }
    }
  }
}
`;

const server = new Server(config, pagemap);
server.generateRoutes().start();

---

License

MIT

---

See Also

• Express.js
• Mustache
• EJS
• Handlebars