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