How to Create a Simple Web Server with Node.js: Complete Implementation Guide

Use require('http') to import the built-in module, call http.createServer() to instantiate a JavaScript Server class that wraps native C++ bindings in src/node_http_server.cc, and execute server.listen() to bind a TCP handle via libuv and begin accepting connections.

Node.js implements a full-stack HTTP server architecture that bridges native C/C++ networking primitives with high-level JavaScript APIs. When you create a Node.js web server, you leverage the http module which loads the JavaScript wrapper in lib/_http_server.js and creates native objects exposed through V8 bindings. According to the nodejs/node source code, this design allows your JavaScript code to orchestrate events while the server handles thousands of concurrent connections on a single thread using non-blocking I/O.

Understanding the Node.js HTTP Server Architecture

The Node.js web server architecture operates on an event-driven, non-blocking model that separates JavaScript API orchestration from low-level network operations managed by libuv.

Bootstrap and the Event Loop

When you launch a Node.js process, the entry point in src/node.cc initializes the V8 JavaScript engine and the libuv event loop. This foundation enables asynchronous I/O operations that power the HTTP server without blocking the main thread.

Module Loading and Server Creation

Calling require('http') loads lib/http.js, which re-exports the server constructor from lib/_http_server.js. When you invoke http.createServer(callback), the JavaScript Server class constructs a native HttpServer instance that registers a libuv TCP handle in the C++ layer.

Request Handling Flow

Once you call server.listen(port), libuv monitors the socket for incoming connections. The native code in src/node_http_server.cc parses HTTP request lines and headers, then emits a "request" event on the JavaScript Server instance. Your callback receives an IncomingMessage object (defined in lib/_http_incoming.js) containing request details and a ServerResponse object (from lib/_http_outgoing.js) for constructing the reply. When you call response.end(), the native layer flushes data back through libuv.

Implementing a Basic Node.js Web Server

To implement a functional web server, you handle the request-response lifecycle using the standard library modules.

Creating the Server Instance

The http.createServer() method accepts a callback function that executes for every incoming request. This callback receives the request and response objects:

const http = require('http');

const server = http.createServer((req, res) => {
  // req: IncomingMessage - provides URL, method, headers
  // res: ServerResponse - used to send status, headers, and body
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello, Node!\n');
});

Starting the Listener

The server.listen() method binds the TCP handle to a specific port and begins accepting connections. You can provide a callback that executes once the server starts listening:

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

Complete Working Example

Combine these components into a single file that you can run with the node command:

// simple-server.js
const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello, Node!\n');
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

Execute the server:

node simple-server.js

Visit http://localhost:3000/ to see the response. The event loop remains free to process additional work while handling requests.

Key Source Files in Node.js

The following files define the architecture you interact with when building a web server:

• src/node.cc: Core entry point that initializes the V8 engine and libuv event loop.
• src/node_http_server.cc: Native C++ implementation that creates the HttpServer instance and registers libuv TCP handles.
• lib/http.js: Public API entry point that re-exports the server constructor.
• lib/_http_server.js: JavaScript Server class that wraps the native implementation and emits "request" events.
• lib/_http_incoming.js: Defines the IncomingMessage class representing HTTP requests.
• lib/_http_outgoing.js: Defines the ServerResponse class for managing outgoing HTTP data.

Advanced Implementation Patterns

Beyond basic request handling, you can extend your Node.js web server with additional capabilities.

Serving Static Files

Combine the http module with fs to read files asynchronously and stream them to the response:

const fs = require('fs');
const path = require('path');

const server = http.createServer((req, res) => {
  const filePath = path.join(__dirname, 'public', req.url === '/' ? 'index.html' : req.url);
  fs.readFile(filePath, (err, data) => {
    if (err) {
      res.writeHead(404);
      res.end('File not found');
      return;
    }
    res.writeHead(200);
    res.end(data);
  });
});

Implementing Routing

Inspect req.url and req.method to dispatch requests to different handlers:

const server = http.createServer((req, res) => {
  if (req.url === '/api' && req.method === 'GET') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ message: 'API endpoint' }));
  } else {
    res.writeHead(404);
    res.end('Route not found');
  }
});

Enabling HTTPS

Replace http with https (wrappers defined in lib/_http_server.js) and provide TLS credentials to create a secure server:

const https = require('https');
const fs = require('fs');

const options = {
  key: fs.readFileSync('private-key.pem'),
  cert: fs.readFileSync('certificate.pem')
};

https.createServer(options, (req, res) => {
  res.writeHead(200);
  res.end('Secure connection');
}).listen(443);

Summary

• Node.js web servers bridge JavaScript APIs with native C++ networking code through the http module.
• The architecture relies on src/node_http_server.cc for TCP handle management and lib/_http_server.js for JavaScript event emission.
• Use http.createServer() to instantiate a server and server.listen() to bind to a port via libuv.
• Request handling involves IncomingMessage objects for input and ServerResponse objects for output, defined in lib/_http_incoming.js and lib/_http_outgoing.js respectively.
• Non-blocking I/O allows thousands of concurrent connections on a single thread.

Frequently Asked Questions

How does Node.js handle concurrent connections without blocking?

Node.js leverages the libuv event loop and non-blocking I/O operations managed in src/node_http_server.cc. When a connection arrives, libuv emits a socket event that the native layer captures, parses the HTTP headers, and dispatches a JavaScript event without waiting for previous requests to complete. This allows a single-threaded process to manage thousands of simultaneous connections efficiently.

What is the difference between http.createServer() and the native C++ implementation?

http.createServer() is a JavaScript method defined in lib/_http_server.js that constructs a high-level Server object. This JavaScript class wraps a native HttpServer instance created in src/node_http_server.cc. The JavaScript layer handles your callback functions and event emissions, while the C++ layer manages the actual TCP socket bindings and HTTP protocol parsing through libuv.

Can I modify the HTTP parsing behavior in Node.js?

The HTTP parsing logic resides in the native C++ layer within src/node_http_server.cc and related parser files. While you cannot directly modify the core parser behavior without recompiling Node.js, you can implement custom middleware in your JavaScript request handlers to transform incoming data after the native layer has parsed the headers into the IncomingMessage object defined in lib/_http_incoming.js.

How do I implement HTTPS instead of HTTP in Node.js?

Replace require('http') with require('https'), which uses the same underlying architecture in lib/_http_server.js but adds TLS encryption. Provide an options object containing your SSL certificate and private key to https.createServer(options, callback). The native layer then establishes secure TCP connections before processing HTTP requests.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}