HTTPS — node-http-server

Transport modes

Choose one listener plan.

node:httpsBuilt-in TLS server

0Runtime dependencies

CJS + ESMHTTPS configuration

1 pipelineShared static behavior

Mode	Configuration	Listeners	Use it for
HTTP	Default configuration	`server.server`	CLI tasks, local assets, trusted networks, or TLS at an edge.
HTTPS only	Key + certificate + `https.only:true`	`server.secureServer`	Direct encrypted local or network serving.
HTTP + HTTPS	Key + certificate + `https.only:false`	`server.server` and `server.secureServer`	Paired listener deployments and controlled migration.

Both transports use the same roots, Host routing, hooks, request limits, timeouts, range handling, validators, compression, logging, and shutdown contract.

Interface choice: the CLI starts an HTTP listener. CommonJS and ESM carry certificate paths and HTTPS listener modes.

HTTPS-only · ESM

Start one encrypted listener.

ESM · HTTPS-only

import {Server} from 'node-http-server';

const server=new Server({
    root:'./public',
    host:'127.0.0.1',
    https:{
        privateKey:'./certs/private/server.key',
        certificate:'./certs/server.crt',
        port:8443,
        only:true
    }
});

server.deploy((instance,listener)=>{
    console.log('HTTPS ready',listener.address());
});

server.secureServer.once('error',error=>{
    console.error(error);
});

Result	Value
URL	`https://127.0.0.1:8443`
HTTP listener	`server.server === null`
HTTPS listener	`server.secureServer`
`address()`	HTTPS address

HTTP + HTTPS · CommonJS

Run paired listeners from one instance.

CommonJS · paired listeners

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

const server=new Server({
    root:'./public',
    host:'127.0.0.1',
    port:8080,
    https:{
        privateKey:'./certs/private/server.key',
        certificate:'./certs/server.crt',
        port:8443,
        only:false
    }
});

server.deploy((instance,listener)=>{
    const protocol=listener===instance.secureServer ? 'https' : 'http';
    console.log(protocol+' ready',listener.address());
});

server.server.once('error',error=>console.error(error));
server.secureServer.once('error',error=>console.error(error));

Readiness: the deploy callback runs once for the HTTP listener and once for the HTTPS listener. The listener argument identifies which address became ready.

TLS configuration

Pass filesystem paths to trusted material.

Key	Default	Contract
`https.privateKey`	`''`	Required private-key path when HTTPS is enabled.
`https.certificate`	`''`	Required certificate path when HTTPS is enabled.
`https.ca`	`''`	Optional CA certificate path.
`https.passphrase`	`false`	Optional private-key passphrase.
`https.port`	`443`	HTTPS port; `0` requests an OS-selected free port.
`https.only`	`false`	`true` selects HTTPS-only; `false` keeps HTTP and HTTPS.

Deployment reads the configured files and constructs the Node HTTPS server before listeners open. Missing, incomplete, unreadable, or invalid material fails startup as one atomic operation.

Complete Config reference →Generate HTTPS configuration →

Listener lifecycle

Inspect and close the listeners you own.

Member	HTTPS-only	HTTP + HTTPS
`server.server`	`null`	Active Node HTTP server
`server.secureServer`	Active Node HTTPS server	Active Node HTTPS server
`server.address()`	HTTPS address	HTTP address
`server.secureServer.address()`	HTTPS address	HTTPS address
`await server.close()`	Closes HTTPS	Closes both listeners

Listener bind failures use Node's native error event. Attach handlers to every active listener. Repeated and concurrent close() calls share the same close operation.

Certificate operations

Use material issued for the deployment.

Deployment	Certificate source	Operator action
Local development	Local CA or development certificate tooling	Trust the CA deliberately and match the requested hostname.
Direct production listener	Maintained public or private CA	Protect key files, monitor expiry, and redeploy after rotation.
Reverse proxy or hosting edge	Edge-managed certificate	Terminate TLS at the edge and run the server on the protected upstream network.

Private keys: store them outside every served root with narrow filesystem permissions. Generate fresh material for each environment.

Local certificate guide →Operations checklist →Security policy →

Troubleshooting

Map the first signal to the next check.

Signal	Meaning	Next check
`ERR_HTTPS_CONFIGURATION`	Key/certificate pair is incomplete.	Set both paths and confirm `https.only`.
Filesystem or PEM error during deploy	Material is unreadable or invalid.	Paths, permissions, file format, and passphrase.
`EACCES` on port 443	Process lacks bind permission.	Use an allowed port such as 8443 or grant the deployment's intended capability.
Browser certificate warning	Trust or hostname validation failed.	Certificate chain, SAN hostname, local CA trust, and system clock.
Deploy callback runs twice	Both listeners became ready.	Compare the callback listener with `secureServer`.
`address()` shows the HTTP port	Dual mode prefers the HTTP address.	Read `secureServer.address()` for HTTPS.
CLI output starts with `http://`	The command owns the HTTP interface.	Use the CommonJS or ESM configuration above for HTTPS.

Redirect and edge policy: route HTTP-to-HTTPS redirects, certificate automation, SNI, HTTP/2, and advanced TLS policy through application code or a maintained edge.