Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns

Node.js http.createServer() method

Reference for http.createServer(): create an HTTP server with a request listener, its options (timeouts, header limits), listening on a port, and common mistakes.

http.createServer([options], [requestListener]) creates and returns an http.Server. The server does nothing until you call server.listen(). For every incoming request the optional requestListener is called with two objects: req (an http.IncomingMessage, what the client sent) and res (an http.ServerResponse, what you send back).

The listener is just a shortcut for server.on("request", listener). Web frameworks such as Express and Fastify are functions that you pass here: they parse the URL, run middleware and call res.end() for you.

NODE
import http from "node:http";

const server = http.createServer((req, res) => {
  res.end("hello\n");
});
server.listen(3000);

Try it

Node.js A server, a request, a clean shutdown

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Routing by hand and options

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
http.createServer(requestListener?: (req, res) => void): http.Server
http.createServer(options: ServerOptions, requestListener?): http.Server
Option Description
IncomingMessage, ServerResponse Classes to use instead of the defaults (they must extend them).
keepAliveTimeout Milliseconds an idle keep-alive connection stays open. Default 5000.
headersTimeout Time allowed to receive the full headers. Default 60000.
requestTimeout Time allowed to receive the entire request. Default 300000; 0 disables.
connectionsCheckingInterval How often timed-out requests are checked. Default 30000.
maxHeaderSize Largest total header size in bytes. Default 16384.
joinDuplicateHeaders Join repeated request headers with , instead of discarding.
requireHostHeader Reply 400 to HTTP/1.1 requests without a Host header (default true).
insecureHTTPParser Accept non-standard HTTP. Avoid it: it enables request-smuggling attacks.
highWaterMark, keepAlive, noDelay Tuning for the underlying sockets.

Returns: an http.Server (an EventEmitter and a net.Server).

Errors and edge cases:

  • A thrown error inside the listener is an uncaught exception and can crash the process. Wrap async work in try/catch and answer with a 500.
  • If you never call res.end(), the client waits until a timeout. Every code path must finish the response.
  • Listening on a port already in use emits an error event with code: "EADDRINUSE".

Usage notes

  • Pass port 0 to let the operating system choose a port, then read it from server.address().port. This is what tests and our live examples do.
  • Without a host, listen(port) binds all interfaces. Use 127.0.0.1 for a local-only server.
  • req.url is only the path and query (/a?x=1), not a full URL. Build one with new URL(req.url, "http://localhost").
  • The listener runs on the event loop, so avoid long synchronous work in it.
  • http.createServer() speaks plain HTTP. For TLS use https.createServer() with a key and certificate, or terminate TLS in a reverse proxy.
  • Stop a server with server.close(); it waits for open connections. See http.Server for closeIdleConnections() and closeAllConnections().
  • Express and similar frameworks only add convenience on top of this API.