Set only what should change.

Using configuration

Pass an object or use Config directly.

const {Server}=require('node-http-server');

const server=new Server({
    host:'127.0.0.1',
    port:8080,
    root:'./public',
    server:{
        noCache:false,
        allowDotfiles:false,
        compression:true,
        maxRequestBodyBytes:1048576
    }
});

server.deploy();

const Config=require('node-http-server/config');
const mimeTypes=require('node-http-server/mime-types');

import Config from 'node-http-server/config';
import mimeTypes from 'node-http-server/mime-types';

Network, roots, and top-level state

Separate binding from Host routing.

new Server({
    root:'./www/default',
    domain:'example.test',
    domains:{
        'docs.example.test':'./www/docs',
        'app.example.test':'./www/app'
    }
}).deploy();

Static server behavior

The server object.

Limits and timeouts

Every disable value is explicit.

requestTimeout, headersTimeout, and keepAliveTimeout apply to HTTP/1 connections, including HTTPS fallback connections. They do not impose HTTP/2 stream deadlines. timeout controls HTTP/2 session inactivity.

File types and restrictions

Serve, reject, or use the binary fallback.

new Server({
    contentType:{
        md:'text/markdown; charset=utf-8',
        secret:false
    },
    restrictedType:{
        key:true,
        pem:true
    }
});

Extension keys omit the leading dot. The built-in map is available through Config.mimeTypes or the node-http-server/mime-types package subpath. If an object is merged after contentType:false, the built-in defaults are restored first and then overlaid.

Error responses

Override headers or individual bodies.

new Server({
    errors:{
        headers:{'Content-Type':'application/json'},
        404:'{"error":"not found"}'
    }
});

Logging

Append NDJSON or provide a writer.

The built-in writer adds a timestamp without mutating its input and redacts common credential headers. Serialization/filesystem errors are captured. Protect log destinations and treat any stored request body as sensitive.

new Server({
    log:true,
    logFunction(data){
        return sendRecordSomewhere(data);
    }
});

Native Node HTTP/2 over HTTPS

Supply key and certificate paths together.

Configured HTTPS defaults to HTTP/2 through node:http2.createSecureServer() with allowHTTP1:true. TLS negotiates HTTP/2 or HTTP/1.1 on the same port before requests begin. Plain HTTP remains HTTP/1.1. Node.js 22.12 or newer remains the runtime requirement, with zero runtime dependencies.

const server=new Server({
    host:'127.0.0.1',
    https:{
        privateKey:'/path/to/private.key',
        certificate:'/path/to/certificate.pem',
        port:8443,
        only:true
    }
});

server.deploy();

server.secureServer is a Node Http2SecureServer by default. Set https.http2:false when the application requires the original https.Server type or HTTP/1-specific native APIs. https.only controls the separate plain HTTP listener, not the negotiated HTTP version. See the hook contract for HTTP/2 request/response compatibility.

Validation and merging

Invalid configuration fails before serving.

Merge precedence is defaults, then constructor values, then later deploy()/merge() overlays. Known nested records shallow-overlay and omitted earlier values persist. Instances, Config.defaults, Config.mimeTypes, and user maps maintain independent mutable nested state. Unknown safe top-level keys remain application-owned metadata.